From 689ddc61133aac63859856484020738ae089859a Mon Sep 17 00:00:00 2001 From: Diana-Hoober Date: Fri, 12 Sep 2025 17:18:23 -0700 Subject: [PATCH 01/46] Add index.md to Drupal guide folder --- .../index.md | 119 ++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md new file mode 100644 index 00000000000..eb259d19ab8 --- /dev/null +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -0,0 +1,119 @@ +--- +slug: +title: How to Install and Configure Drupal on Ubuntu 22.04 +titlee_meta: +description: Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices and legacy notes for Conda users. +author: ["Diana Hoober"] +contributors: ["Diana Hoober"] +published: 2025-9-15 +keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Conda] +license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +--- + +These instructions and examples demonstrate how to install and configure Drupal 11 within a contributor-safe, systems-aware environment. When deployed on an Akamai-optimized infrastructure, Drupal benefits from global edge caching for faster content delivery, intelligent cache purging to ensure timely updates, and enterprise-grade security features such as DDoS protection and web application firewalls. + +Additionally, beginners, legacy users, and contributors benefit from Akamai’s CDN architecture, which offloads traffic from the origin server and allows Drupal to efficiently scale load while maintaining performance and reliability. Integration modules let Drupal directly communicate with Akamai’s caching layers, for a robust solution for structured content management within a secure, high-performance delivery framework. + +## System Prerequisites + +To ensure Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure, the following prerequisites must be in place. + +- ✅ OS: Ubuntu 22.04 LTS +- ✅ Apache: Version 2.4.52+ +- ✅ PHP: Version 8.1+ (Drupal 11 optimized for PHP 8.3) +- ✅ MariaDB or MySQL: Installed and secured +- ✅ Composer: Installed globally +- ✅ Drupal: Latest stable version (11.2.3 as of Sept 2025) + +This setup provides a stable foundation for structured content management, contributor workflows, and integration with Akamai’s caching and security layers. + +## Install and Configure the Supporting Stack + +This section walks through the varied components that form the foundation for a stable, scalable Drupal deployment. + +- Apache2 +- MariaDB server +- PHP and required extensions +- Composer (with install command options) +- Optional: Drush, phpMyAdmin + +### Initialize the Drupal Application Environment + +This phase pulls in Drupal core, scaffolds the file structure, and prepares the environment for configuration using the Composer action: + + composer create-project drupal/recommended-project [project name] + +Once the command completes, you’ll see a structured directory layout designed to support modular development and secure deployment. The `/web` folder contains all public-facing files, including `index.php`, assets, and the `.htaccess` configuration. + +The root directory holds the `composer.json` file, which defines project dependencies, and the `/vendor` folder, which contains Composer-managed libraries. This separation ensures clarity between application logic and public content, making it easier to manage updates and enforce security boundaries. + +Before proceeding, adjust file ownership to ensure the web server can read and write where needed. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), with a command like: + + sudo chown -R www-data:www-data web + +This step prevents permission errors during runtime and ensures that Drupal can generate files, manage uloads, and interact with modules safely. + +### Configure the Web Server for Drupal + +Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. + +- **Enable `mod_rewrite`** + Drupal uses clean URLs, which require Apache’s rewrite module. Enable it with: + + ```bash + sudo a2enmod rewrite + sudo systemctl restart apache2 + +- **Set** `AllowOverride` **to** `All` + Drupal's `.htaccess` file needs permission to override degault settings. In your Apache config (typically `/etc/apache2/sites-available/000-default.conf` or a custom firtual host), update the `` block: + + + AllowOverride All + + +- Then reload Apache: + + sudo systemctl reload apache2 + +- Optional: Configure a Virtual Host + For local development or multiple site setups, define a virtual host pointing to the Drupal `/web` directory: + + + ServerName drupal.local + DocumentRoot /var/www/html/web + + + AllowOverride All + Require all granted + + + +- Don't forget to update your `/etc/hosts` file: + + 127.0.0.1 drupal.local + +- And enable the site: + + sudo a2ensite drupal.conf + sudo systemctl reload apache2 + +## Local Testing Setup- Add entry to /etc/hosts (e.g., 127.0.0.1 drupal.local) + +- Test site in browser +- Troubleshooting tips (permissions, rewrite module, PHP errors) + +## Security and Optimization- Run mysql_secure_installation + +- Enable SSL (optional) +- File permissions and .htaccess notes + +## Contributor-Safe Notes- Composer-first workflow + +- Legacy bridging for users coming from Drupal 8 +- Avoiding brittle installs and opaque errors +- Encouraging use of drush for command-line efficiency + +## Conclusion- Summary of setup + +- Next steps (theme development, module installation) +- Link to official Drupal documentation From 1fbcb53345dd239397adc6594423ba0ba417895d Mon Sep 17 00:00:00 2001 From: Diana-Hoober Date: Mon, 15 Sep 2025 16:41:25 -0700 Subject: [PATCH 02/46] Finalized draft content for Drupal --- .../index.md | 137 +++++++++++++++--- 1 file changed, 117 insertions(+), 20 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index eb259d19ab8..9c2367c1fea 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -41,31 +41,32 @@ This section walks through the varied components that form the foundation for a This phase pulls in Drupal core, scaffolds the file structure, and prepares the environment for configuration using the Composer action: - composer create-project drupal/recommended-project [project name] + composer create-project drupal/recommended-project my_drupal_site -Once the command completes, you’ll see a structured directory layout designed to support modular development and secure deployment. The `/web` folder contains all public-facing files, including `index.php`, assets, and the `.htaccess` configuration. +Replace `my_drupal_site` with your project folder name. -The root directory holds the `composer.json` file, which defines project dependencies, and the `/vendor` folder, which contains Composer-managed libraries. This separation ensures clarity between application logic and public content, making it easier to manage updates and enforce security boundaries. +Once the command completes, your new project directory will include a /web folder for public-facing files, a composer.json file that defines dependencies, and a /vendor folder for Composer-managed libraries. This structure supports modular development and secure deployment by clearly separating application logic from public content—making updates easier to manage and reducing security risks. -Before proceeding, adjust file ownership to ensure the web server can read and write where needed. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), with a command like: +This structure supports modular development and secure deployment by clearly separating application logic from public content—making updates easier to manage and reducing security risks. + +Before proceeding, ensure the web server has permission to interact with the new environment. Set the /web directory and its contents to be owned by www-data (or your system’s web server user), using: sudo chown -R www-data:www-data web -This step prevents permission errors during runtime and ensures that Drupal can generate files, manage uloads, and interact with modules safely. +This step prevents permission errors during runtime and ensures that Drupal can generate files, manage uploads, and interact with modules safely. ### Configure the Web Server for Drupal -Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. +Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. If you're using the default site, the config file is typically located at `/etc/apache2/sites-available/000-default.conf`. For custom setups, use your virtual host file (e.g., /etc/apache2/sites-available/drupal.conf`). - **Enable `mod_rewrite`** Drupal uses clean URLs, which require Apache’s rewrite module. Enable it with: - - ```bash + sudo a2enmod rewrite sudo systemctl restart apache2 - **Set** `AllowOverride` **to** `All` - Drupal's `.htaccess` file needs permission to override degault settings. In your Apache config (typically `/etc/apache2/sites-available/000-default.conf` or a custom firtual host), update the `` block: + Drupal's `.htaccess` file needs permission to override default settings. In your Apache config (typically `/etc/apache2/sites-available/000-default.conf` or a custom virtual host), update the `` block: AllowOverride All @@ -78,7 +79,7 @@ Apache is assumed to be installed and running. This section focuses on enabling - Optional: Configure a Virtual Host For local development or multiple site setups, define a virtual host pointing to the Drupal `/web` directory: - + ServerName drupal.local DocumentRoot /var/www/html/web @@ -97,23 +98,119 @@ Apache is assumed to be installed and running. This section focuses on enabling sudo a2ensite drupal.conf sudo systemctl reload apache2 -## Local Testing Setup- Add entry to /etc/hosts (e.g., 127.0.0.1 drupal.local) +## Local Testing Setup + +- Add an entry to /etc/hosts + +This maps `drupal.local` to your local machine: + + 127.0.0.1 drupal.local + +- Test site in your browser + +Visit http://drupal.local. If the setup is successful, you’ll see the Drupal installer or welcome screen in your browser. This confirms that Apache, PHP, and file permissions are working correctly. -- Test site in browser - Troubleshooting tips (permissions, rewrite module, PHP errors) -## Security and Optimization- Run mysql_secure_installation +If the site doesn't load: + + - Check file permissions on the `/web` directory. + - Confirm `mod_rewrite` is enabled. + - Review Apache config for `AllowOverride All`. + - Look for PHP errors in your logs (`/var/log/apache2/error.log`) + +If you see a blank page or 403 error, check that Apache is reading `.htaccess` and that PHP is installed and enabled. Run this in the terminal: + + php -v + +If PHP is installed, you'll see version info like this: + + PHP 8.1.2 (cli) (built: ...) + +If it's missing, the system will say `command not found`, and you need to install PHP and its Apache integration. Follow this [guide for Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-ubuntu-22-04) to set Apache up before continuing. + +## Security and Optimization + +1. Run the MySQL hardening script to remove insecure defaults and set a root password: + + sudo mysql_secure_installation + +This interactive tool lets you: + +- Set or update the root password +- Remove anonymous users +- Disallow remote root login +- Remove the test database +- Reload privilege tables + +{{< note>}} +These steps help protect your Drupal site from unauthorized access and are strongly recommended for production environments. + +1. Enable SSL (Optional) + +If deploying Drupal in a production or pubic-facing environment, configure SSL to encrypt traffic: -- Enable SSL (optional) -- File permissions and .htaccess notes +- Use *Let's Encrypt* or a self-signed certificate. +- Updae your Apache virtual host to include: -## Contributor-Safe Notes- Composer-first workflow + + SSLEngine on + SSLCerificateFile /path/to/cert.pem + SSLCertificateKeyFile /path/to/key.p +''' + + +For local development, SSL is optional. For public sites it is essential. + +1. File permissions and `.htaccess` notes + +- Ensure the `/web/site/default` directory is writable by the web server during installation: + + sudo chown -R www-data:www-data web/sites/default + +- After installation, lock down permissions: + + sudo chmod 444 web/sites/default/settings.php + +- Drupal relies on `.htaccess` for security rules like: + + - Preventing access to sensitive files + - Blocking directory listings + - Enforcing clean URLs + +{{< Tip>}} +If `.htaccess` rules aren't being applied, double-check `AllowOverride All` in your Apache config. +{{< /Tip>}} + +1. Security Checklist + - Databes hardened with `mysql_secure_installation` + - File permission set for install and post-install + - `.htaccess` rules active + - SSL configured (if pubic-facing) + +## Contributor-Safe Notes: Composer-First Workflow - Legacy bridging for users coming from Drupal 8 + +Drupal 9+ expects a Compower-managed workflow. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assume Composer-first setup to ensure compatibility with moder module management and depencency resolution. + - Avoiding brittle installs and opaque errors -- Encouraging use of drush for command-line efficiency -## Conclusion- Summary of setup +Composer tracks dependencies explicitly, reducing the risk of missing extensions or mismatched versions. Manual installs often fail silently or introduce hard-to-trace errors. Using `composer create-project` ensures a reproducible, contributor-safe environment. + +- Encouraging use of Drush for command-line efficiency + +Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. + + /vendor/bin/drush/status + +## Conclusion: What Comes Next + +From here, you can begin customiaing your site: + +- Official [Drupal Documentation](https://www.drupal.org/documentation). + +- Theme development: Create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to get a clear sense of what's possible. + +To see demonstrated [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) -- Next steps (theme development, module installation) -- Link to official Drupal documentation From bcee7470b4f029d0064021e74d6f36a3c8ff5c8f Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Mon, 22 Sep 2025 14:38:09 -0700 Subject: [PATCH 03/46] Installing Drupal on Ubuntu 22.04 --- .../index.md | 434 ++++++++++++++---- 1 file changed, 345 insertions(+), 89 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 9c2367c1fea..153c56cb0ad 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -1,133 +1,372 @@ --- -slug: +slug: install-configure-initialize-Drupal-on-ubuntu-22-04 title: How to Install and Configure Drupal on Ubuntu 22.04 titlee_meta: -description: Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices and legacy notes for Conda users. +description: Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices. author: ["Diana Hoober"] contributors: ["Diana Hoober"] -published: 2025-9-15 -keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Conda] +published: 2025-9-30 +keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Composer] license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' --- -These instructions and examples demonstrate how to install and configure Drupal 11 within a contributor-safe, systems-aware environment. When deployed on an Akamai-optimized infrastructure, Drupal benefits from global edge caching for faster content delivery, intelligent cache purging to ensure timely updates, and enterprise-grade security features such as DDoS protection and web application firewalls. +This guide walks through installing and configuring Drupal 11 in a contributor-safe, systems-aware environment. -Additionally, beginners, legacy users, and contributors benefit from Akamai’s CDN architecture, which offloads traffic from the origin server and allows Drupal to efficiently scale load while maintaining performance and reliability. Integration modules let Drupal directly communicate with Akamai’s caching layers, for a robust solution for structured content management within a secure, high-performance delivery framework. +Drupal is a flexible content management system (CMS) used for structured content and scalable site architecture. While it runs in many hosting contexts, it performs especially well on Akamai’s compute instance, which supports high-traffic, content-rich deployments. + + +## Before You Begin + +This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases--specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer. First, we'll walk through prerequisites, setup and verification to ensure a reliable install, then move into installing Drupal . ## System Prerequisites -To ensure Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure, the following prerequisites must be in place. +To ensure Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure, the following prerequisites must be in place. - ✅ OS: Ubuntu 22.04 LTS - ✅ Apache: Version 2.4.52+ - ✅ PHP: Version 8.1+ (Drupal 11 optimized for PHP 8.3) -- ✅ MariaDB or MySQL: Installed and secured -- ✅ Composer: Installed globally -- ✅ Drupal: Latest stable version (11.2.3 as of Sept 2025) +- ✅ MariaDB 10.3.7+ or MySQL: 5.7.8 (Drupal 11) Installed and secured +- ✅ Composer: 2.7.0+ (Drupal 11) Installed globally +- ✅ Drupal: Latest stable version (11.1.8 as of Sept 2025) will be installed after the environment setup + +This configuration provides a stable foundation for structured content management, contributor workflows, and integration with Akamai’s caching and security layers. + +## Environment Setup: Preparing to Install Drupal + +This section walks through verifying system components, setting up file structure and preparing the database--everything Drupal needs before installation begins. + +### Infrastructure Verification + +Confirm that required components are correctly installed and active to prevent silent failures during setup. -This setup provides a stable foundation for structured content management, contributor workflows, and integration with Akamai’s caching and security layers. +#### Check PHP Version and Extensions -## Install and Configure the Supporting Stack +Run the following commands to verifiy what extensions are installed: -This section walks through the varied components that form the foundation for a stable, scalable Drupal deployment. + php -v + php -m | grep -E 'gd|mbstring|xml|curl|zip|mysqli|pdo_mysql|opcache' + +If not all required PHP extensions are installed, you can safely add any needed extensions by running: + + sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache (see [Troubleshooting Tips](websites\cms\drupal\how-to-install-and-configure-drupal-on-ubuntu-22-04\index.md\#troubleshooting-tips)). + +Following the installation, restart Apache or Nginx to load the new extensions. -- Apache2 -- MariaDB server -- PHP and required extensions -- Composer (with install command options) -- Optional: Drush, phpMyAdmin + sudo systemctl restart apache2 -### Initialize the Drupal Application Environment +Verify they're active: -This phase pulls in Drupal core, scaffolds the file structure, and prepares the environment for configuration using the Composer action: + php -m | grep -E 'gd|mbstring|xml|curl|zip|mysqli|pdo_mysql|opcache' - composer create-project drupal/recommended-project my_drupal_site +Each one should be listed. -Replace `my_drupal_site` with your project folder name. +#### Check Composer -Once the command completes, your new project directory will include a /web folder for public-facing files, a composer.json file that defines dependencies, and a /vendor folder for Composer-managed libraries. This structure supports modular development and secure deployment by clearly separating application logic from public content—making updates easier to manage and reducing security risks. +If check Composer installation yields `composer` not found error, you can install it with: -This structure supports modular development and secure deployment by clearly separating application logic from public content—making updates easier to manage and reducing security risks. + sudo apt update && sudo apt install composer -Before proceeding, ensure the web server has permission to interact with the new environment. Set the /web directory and its contents to be owned by www-data (or your system’s web server user), using: +To verify installation, run: + + composer --version + +#### Verify the Web Server + +Before proceeding, make sure your web server has permission to interact with the Drupal environment. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), using: sudo chown -R www-data:www-data web This step prevents permission errors during runtime and ensures that Drupal can generate files, manage uploads, and interact with modules safely. -### Configure the Web Server for Drupal +{{< Tip>}} +If you're using Nginx or a different web server, replace `www-data` with your actual server user (e.g., `nginx`, `apache`, or a custom service account). +{{< /Tip>}} -Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. If you're using the default site, the config file is typically located at `/etc/apache2/sites-available/000-default.conf`. For custom setups, use your virtual host file (e.g., /etc/apache2/sites-available/drupal.conf`). +To confirm ownership was updated, run this from the parent directory of `web`: -- **Enable `mod_rewrite`** - Drupal uses clean URLs, which require Apache’s rewrite module. Enable it with: - - sudo a2enmod rewrite - sudo systemctl restart apache2 + ls -ld web -- **Set** `AllowOverride` **to** `All` - Drupal's `.htaccess` file needs permission to override default settings. In your Apache config (typically `/etc/apache2/sites-available/000-default.conf` or a custom virtual host), update the `` block: +This shows you the ownership and permission of the `web` directory itself: - - AllowOverride All - + drwxr-xr-x 7 www-data -www-data 4096 Sep 16 22:28 web -- Then reload Apache: +This means: - sudo systemctl reload apache2 +- `www-data` owns the directory +- `www-data` is also the group +- The permissions are `drwxr-xr-x` (read/write/execute for owner, read/execute for group and others.) -- Optional: Configure a Virtual Host - For local development or multiple site setups, define a virtual host pointing to the Drupal `/web` directory: +To check ownership of a file, run: - - ServerName drupal.local - DocumentRoot /var/www/html/web + ls -l path/to/your/file (e.g., 'ls -l web/index.php') - - AllowOverride All - Require all granted - - +This tells you who the file is owned by and the group. -- Don't forget to update your `/etc/hosts` file: +{{< Tip>}} +If you need to replace incorrect ownership, rerun: - 127.0.0.1 drupal.local + sudo chown -R www-data:www-data web -- And enable the site: +And replace `www-data` with your actual web server user if different. - sudo a2ensite drupal.conf - sudo systemctl reload apache2 +#### Drupal Project Presence -## Local Testing Setup +To confirm the project was scaffolded correctly, verify the presence of key files and directories: -- Add an entry to /etc/hosts + ls composer.json + ls web/index.php + ls -d vendor/ -This maps `drupal.local` to your local machine: +{{< Note>}} +If these files are missing, drupal has not been initialized. See the next section to scaffold the project using Composer. +{{< /Note>}} - 127.0.0.1 drupal.local +Contributor-Safe Tips -- Test site in your browser +- Be sure to consider mentioning file permissions if they are relevant to your environment (e.g., `chmod`, `chown`). +- If `vendor/` is missing but `composer.json` is present, run `composer install`. -Visit http://drupal.local. If the setup is successful, you’ll see the Drupal installer or welcome screen in your browser. This confirms that Apache, PHP, and file permissions are working correctly. +If all checks pass, your infrastructure is ready for Drupal initialization and configuration. -- Troubleshooting tips (permissions, rewrite module, PHP errors) +## Initialize the Drupal Application Environment -If the site doesn't load: +After the `composer create-project` command, your environment should now include the core Drupal files and folder structure. This phase confirms that setup, prepares optional configuration scaffolding, and gets the application ready for site installation. - - Check file permissions on the `/web` directory. - - Confirm `mod_rewrite` is enabled. - - Review Apache config for `AllowOverride All`. - - Look for PHP errors in your logs (`/var/log/apache2/error.log`) +## Create Project Structure -If you see a blank page or 403 error, check that Apache is reading `.htaccess` and that PHP is installed and enabled. Run this in the terminal: +Creating the project structure sets up Drupal for modular development and secure deployment. - php -v +This step separates application logic from public content, making updates easier to manage and reduce security risks. + +{{< Note>}} +This guide assumes you're using Drupal 11.1.8 as noted earlier. +{{< /Note>}} + +### Create the Drupal project structure + +- Run the install command to scaffold (create) the Drupal 11.1.8 structure, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) and customize the "my_drupal_site" name to fit your needs: + + composer create-project drupal/recommended-project:11.1.8 my_drupal_site + +-Then change to the project folder: + + cd my_drupal_site + +- Inside the scaffolded project folder `my_drupal_site`, confirm the environment after installation with: + + ls composer.json + Result: `composer.json` confirming the metadata file exists + + ls -ld web/index.php + Response: `web/index.php` confirms the application entry point file exists. + + ls -ld vendor/ + Response:`vendor/` confirming that the `vendor/` directory was created. + +If any of these are missing or return errors, installation may have failed or been interrupted. For troubleshooting see [Installing Drupal - Getting Started Guide](https://www.drupal.org/docs/getting-started/installing-drupal). + +**Following Composer Initialization** (scaffolded Drupal Project), confirm your environment against the **Drupal Site Setup checklist**: + +- Change to the project folder. + + cd my_drupal_site + +- Copy the default settings file. + + cp web/sites/default/default.settings.php web/sites/default/settings.php + +This creates the active configuration file that Drupal reads and writes to during installation and runtime. + +### Set file permissions + +- This is for `settings.php` (allows the owner to read/write, group and others to read, and the web server to access it during installation). Make sure you are in the Drupal project root folder and then run: + + chmod 644 web/sites/default/settings.php + + *Optional: If you're on a shared host or strict environment, you may need to tighten permissions in the `settings.php` file to `640` or even `600`.* + + Also, if you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. Running `chmod 644` now avoids this. +### Create the files directory. + +Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root (`my_drupal_site`) run: + + mkdir -p web/sites/default/files + chmod 755 web/sites/default/files + +To verify that it worked, run: + + ls -ld web/sites/default/files + +The `chmod` allows owner and group read, write, and execute permissions and others read and execute rights. For stricter environments you can adjust ownership with: + + chown -R www-data web/sites/default/files + +Use your actual web server for `www-data`. A writable `files` directory allows Drupal to store uploads (i.e., images or module enablement) or generate cached assets so you don't see any errors. + +### Prepare the database. + +Before installing Drupal, follow the official guide to create a database and user for Drupal [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). + +- Once complete, confirm with a contributor-safe verification block: + + mysql -u drupal_user -p -h localhost drupal_db + +You should be able to enter the MariaDB shell without errors. +Your database used `utf8mb4` encoding: + + SHOW CREATE DATABASE drupal_db; + +- Look for `CHARACTER SET utf8mb4`. Your credentials match what you'll enter in `settings.php`: + +$databases['default']['default'] = [ -If PHP is installed, you'll see version info like this: + 'driver' => 'mysql', + 'database' => 'drupal_db', + 'username' => 'drupal_user', + 'password' => 'your_secure_password', + 'host' => 'localhost', + ]; - PHP 8.1.2 (cli) (built: ...) +This is located in `sites/default/settings.php` -If it's missing, the system will say `command not found`, and you need to install PHP and its Apache integration. Follow this [guide for Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-ubuntu-22-04) to set Apache up before continuing. +- File permissions might need to be temporarily relaxed during setup with: + + chmod 664 sites/default/settings.php + +1. Common Errors and Fixes + +| Error Message | Likely Cause | Fix | Resource | +|-------------------------------|-------------------------------|------------------------------------------|--------------------------------------------------------------------------| +| Access denied for user | Wrong username or password | Double-check credentials in `settings.php` | [Drupal.org: Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration) | +| Unknown database | Database name typo or missing | Recreate or correct name in config | [MoldStud: Avoid Common Pitfalls](https://moldstud.com/articles/p-managing-drupal-database-connection-settings-avoid-common-pitfalls) | +| Driver not found | Incorrect or missing driver | Use `'driver' => 'mysql'` for MariaDB | [Drupal.org: Database API Overview](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration) | +| Warning: count() during install | Misconfigured array structure | Ensure `$databases` array is properly nested | [Stack Overflow](https://stackoverflow.com/questions/71596215/how-can-i-set-up-my-drupal-database-correctely) (yes, there is a typo in that title s/b correctly). | + +1. Optional: Environment Variables + +Sensitive credentials can be abstracted using `.env` files or environment-specific config, see [Drupal.org's environment config practices](https://www.drupal.org/project/env). + +### CLI-based Installation + +This guide uses the CLI method for consistency, automation, and contributor safety (using Drush 11.x for CLI-based installation, matching Drupal 11/1/8). + +**Environment Validation**(Phase 1) + +| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | +|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-1ubuntu2.22` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | +| Required Extensions | Confirm required PHP modules | `php -m \| grep -E 'pdo'`|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip'` | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | +| Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | + +* Running Composer as root is discouraged. Safe for local testing, but avoid in production. + +If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): + +{{< Tip>}} +During installation, you may see a prompt like: + +`Do you want to continue?[Y/n]` + +This is a standard confirmation step. Type `Y` and press Enter to proceed. (If using a different package manager or install method, the prompt may vary slightly--but the intent is the same: confirm you want to install the listed components.) +{{< /Tip>}} + +**Installation** (Phase 2) + +Install the Drupal codebase using Composer. This sets up the recommended project scaffold. Also assumes Composer and PHP are installed and working. See Phase 1 for environment prep. + +| **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | +|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| Create Project | Scaffold Drupal site | `composer create-project drupal/recommended-project mysite` | `mysite` folder created with Drupal scaffold | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | +| Install Drush (local) | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints*, **, *** | [Drush Docs](https://www.drush.org/latest/install/) | +| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | +| Optional Global Install| Make Drush available system-wide | Download `drush.phar`, then run: + `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` + `drush --version` | `Drush version 11.5.1` from global path | If not executable, recheck permissions or path | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | + +* Confirm `composer.json` is writable and not locked by another process +** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x) +*** If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1` +**** If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. + +** Post-Install Validation** (Phase 3) + +After installation, confirm the setup is complete and ready for configuration. + +| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | +|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| Success Confirmation | Validate install completion | Review terminal output | “Project created successfully” or similar message | If error shown, rerun with `-vvv` for verbose output | [Composer Troubleshooting](https://getcomposer.org/doc/articles/troubleshooting.md) | +| Folder Structure | Confirm expected files exist | `ls mysite` | `composer.json`, `web/`, `vendor/`, etc. | If missing, check install logs or rerun install | [Drupal File Structure](https://www.drupal.org/docs/develop/structure-of-a-drupal-codebase) | +| Optional Cleanup | Remove message plugin (optional) | `composer remove drupal/core-project-message` | Plugin removed, no errors | If error, check Composer version or plugin dependencies | [Project Message Plugin](https://www.drupal.org/project/core_project_message) | + +### Launch the installer. + +Once your project structure is in place and Drush is installed, you can launch the Drupal installer using either a browser or CLI. This confirms that your environment is functional and ready for site configuration. + +| **Method** | **Purpose** | **Action / Command** | **Expected Result** | **If Output Differs** | 🔗 **Further Info** | +|-------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/my_drupal_site/web` | Drupal installer page loads | Check PHP server is running, confirm `web` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | +| CLI-based install | Install Drupal via Drush | `vendor/bin/drush site:install` | Site installed with default config | Confirm database access, Drush version, and PHP compatibility | [Drush Site Install](https://www.drush.org/latest/commands/site-install/) | + +> If using the PHP built-in server, run from your project root: +> ``` +> php -S localhost:8888 -t web +> ``` + +> If the installer page is blank or throws errors: +> - Check PHP version and extensions (`pdo`, `gd`, `mbstring`) +> - Confirm file permissions in the `web` folder +> - Ensure `index.php` exists in `web` + +### Configure the Web Server for Drupal + +Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. + +#### Summary Table + +| **Step** | **Purpose** | **Command / Config** | +|---------------------------|----------------------------------------------|--------------------------------------------------------------------------------------| +| Enable `mod_rewrite` | Support clean URLs | `sudo a2enmod rewrite`
`sudo systemctl restart apache2` | +| Set `AllowOverride All` | Allow `.htaccess` overrides | Edit Apache config file (`000-default.conf` or `drupal.conf`) | +| Reload Apache | Apply config changes | `sudo systemctl reload apache2` | +| Optional: Virtual Host | Use custom domain for local dev | Define `` block pointing to `/web` folder | +| Update `/etc/hosts` | Map custom domain to localhost | `127.0.0.1 drupal.local` | +| Enable site config | Activate virtual host | `sudo a2ensite drupal.conf`
`sudo systemctl reload apache2` | +--- + +#### Line-by-Line Walkthrough + +**1. Enable `mod_rewrite`** + +Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: + +sudo a2enmod rewrite +sudo systemctl restart apache2 + +## Local Testing Setup + +Before continuing, confirm that your local environment is serving the Drupal site correctly. This section helps validate Apache, PHP, and file permissions using a browser-based test. + +### Summary Table + +| **Step** | **Purpose** | **Command / Action** | +|---------------------------|----------------------------------------------|--------------------------------------------------------------------------------------| +| Map domain to localhost | Access site via `drupal.local` | Add `127.0.0.1 drupal.local` to `/etc/hosts` | +| Test in browser | Confirm site is served correctly | Visit `http://drupal.local` | +| Troubleshoot blank/error | Identify common issues | Check permissions, Apache config, PHP status | +| Validate PHP install | Confirm PHP is installed and active | Run `php -v` | + +--- + +### Line-by-Line Walkthrough + +**1. Add an entry to `/etc/hosts`** + +This maps `drupal.local` to your local machine: + +``` +127.0.0.1 drupal.local ## Security and Optimization @@ -145,24 +384,24 @@ This interactive tool lets you: {{< note>}} These steps help protect your Drupal site from unauthorized access and are strongly recommended for production environments. +{{< /note>}} -1. Enable SSL (Optional) +2. Enable SSL (Optional) -If deploying Drupal in a production or pubic-facing environment, configure SSL to encrypt traffic: +If deploying Drupal in a production or public-facing environment, configure SSL to encrypt traffic: - Use *Let's Encrypt* or a self-signed certificate. -- Updae your Apache virtual host to include: +- Update your Apache virtual host to include: SSLEngine on - SSLCerificateFile /path/to/cert.pem - SSLCertificateKeyFile /path/to/key.p -''' + SSLCertificateFile /path/to/cert.pem + SSLCertificateKeyFile /path/to/key.pem For local development, SSL is optional. For public sites it is essential. -1. File permissions and `.htaccess` notes +3. File permissions and `.htaccess` notes - Ensure the `/web/site/default` directory is writable by the web server during installation: @@ -178,21 +417,23 @@ For local development, SSL is optional. For public sites it is essential. - Blocking directory listings - Enforcing clean URLs -{{< Tip>}} +{{< tip>}} If `.htaccess` rules aren't being applied, double-check `AllowOverride All` in your Apache config. -{{< /Tip>}} +{{< /tip>}} -1. Security Checklist - - Databes hardened with `mysql_secure_installation` - - File permission set for install and post-install - - `.htaccess` rules active - - SSL configured (if pubic-facing) +4. Security Checklist + - **Database hardened** with `mysql_secure_installation` + - **File permission** set for install and post-install + - **`.htaccess`** rules active + - **SSL configured** (if public-facing) + +--- ## Contributor-Safe Notes: Composer-First Workflow - Legacy bridging for users coming from Drupal 8 -Drupal 9+ expects a Compower-managed workflow. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assume Composer-first setup to ensure compatibility with moder module management and depencency resolution. +Drupal 11.x expects a Composer-managed workflow. Composer is now the official and recommended method for managing Drupal core, contributed modules, and dependencies. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assumes a Composer-first setup to ensure compatibility with modern module management and depencency resolution. - Avoiding brittle installs and opaque errors @@ -200,13 +441,28 @@ Composer tracks dependencies explicitly, reducing the risk of missing extensions - Encouraging use of Drush for command-line efficiency -Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. +Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. Run Drush from you project directory: + + ./vendor/bin/drush/status + +If you see errors about missing Symfony classes or autoloading failures, double-check that: + + - You're inside the correct project folder (with `composer.json`, `vendor/`, and `web/`). + - Drush is intalled locally--not globally or in `/root/vendor`. + - You're not running Drus from outside the project root. + +To confirm you're in the right place, look for: + + ls + # Should include: composer.json, vendor/, web/ + +For official Drush installation guidance, see [Drush on Drupal.org](https://www.drupal.org/docs/develop/development-tools/drush). - /vendor/bin/drush/status +You can find additional information on [Drupal's Composer guide](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) for deeper context. ## Conclusion: What Comes Next -From here, you can begin customiaing your site: +From here, you can begin customizing your site: - Official [Drupal Documentation](https://www.drupal.org/documentation). From fa0313b52bdc58378b3c9dd1573490c6bee3c3e8 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Tue, 23 Sep 2025 15:18:34 -0700 Subject: [PATCH 04/46] Corrections to Install and Configure Drupal on Ubuntu 22-04 --- .../index.md | 164 ++++++++++-------- 1 file changed, 94 insertions(+), 70 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 153c56cb0ad..a2197536c69 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -1,7 +1,7 @@ --- -slug: install-configure-initialize-Drupal-on-ubuntu-22-04 +slug: how-to-install-and-configure-drupal-on-ubuntu-22-04 title: How to Install and Configure Drupal on Ubuntu 22.04 -titlee_meta: +title_meta: description: Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices. author: ["Diana Hoober"] contributors: ["Diana Hoober"] @@ -10,18 +10,15 @@ keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Composer] license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' --- -This guide walks through installing and configuring Drupal 11 in a contributor-safe, systems-aware environment. - -Drupal is a flexible content management system (CMS) used for structured content and scalable site architecture. While it runs in many hosting contexts, it performs especially well on Akamai’s compute instance, which supports high-traffic, content-rich deployments. - +Drupal is a flexible content management system (CMS) designed for structured content and scalable site architecture. While it runs well in many hosting environments, Akamai’s compute instance offers a particularly strong foundation for high-traffic, content-rich deployments. This guide walks through installing and configuring Drupal 11 on Ubuntu 22.04 with systems-aware practices and contributor-safe steps that hold up in real-world scenarios. ## Before You Begin -This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases--specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer. First, we'll walk through prerequisites, setup and verification to ensure a reliable install, then move into installing Drupal . +This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases--specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer. First, we'll walk through prerequisites, setup and verification to ensure a reliable install, then move into installing Drupal. ## System Prerequisites -To ensure Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure, the following prerequisites must be in place. +This guide is based on a tested configuration that ensures Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure. The following prerequisites were used for validation. - ✅ OS: Ubuntu 22.04 LTS - ✅ Apache: Version 2.4.52+ @@ -30,11 +27,11 @@ To ensure Drupal 11 installs cleanly and performs reliably within an Akamai-opti - ✅ Composer: 2.7.0+ (Drupal 11) Installed globally - ✅ Drupal: Latest stable version (11.1.8 as of Sept 2025) will be installed after the environment setup -This configuration provides a stable foundation for structured content management, contributor workflows, and integration with Akamai’s caching and security layers. +This configuration was verified to support structured content management, contributor workflows, and integration with Akamai’s caching and security layers. ## Environment Setup: Preparing to Install Drupal -This section walks through verifying system components, setting up file structure and preparing the database--everything Drupal needs before installation begins. +This section outlines the steps used to verify system components, establish the file structure, and prepare the database--everything Drupal requires prior to installation. ### Infrastructure Verification @@ -42,16 +39,16 @@ Confirm that required components are correctly installed and active to prevent s #### Check PHP Version and Extensions -Run the following commands to verifiy what extensions are installed: +Use the following commands to check what PHP extensions are available: php -v php -m | grep -E 'gd|mbstring|xml|curl|zip|mysqli|pdo_mysql|opcache' -If not all required PHP extensions are installed, you can safely add any needed extensions by running: +If any required PHP extensions are missing, install them with: - sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache (see [Troubleshooting Tips](websites\cms\drupal\how-to-install-and-configure-drupal-on-ubuntu-22-04\index.md\#troubleshooting-tips)). + sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache -Following the installation, restart Apache or Nginx to load the new extensions. +Following installation, restart Apache or Nginx to activate the new extensions. sudo systemctl restart apache2 @@ -59,29 +56,33 @@ Verify they're active: php -m | grep -E 'gd|mbstring|xml|curl|zip|mysqli|pdo_mysql|opcache' -Each one should be listed. +Each one should now be listed. #### Check Composer -If check Composer installation yields `composer` not found error, you can install it with: +If checking for Composer installation yields a `composer` not found error, you can install it with: sudo apt update && sudo apt install composer -To verify installation, run: +To verify installation: composer --version +You should see output like `Composer version 2.7.0 or higher. + +If the command fails, see [Composer Installation - Manual Download](https://getcomposer.org/doc/00-intro.md#manual-installation). + #### Verify the Web Server Before proceeding, make sure your web server has permission to interact with the Drupal environment. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), using: sudo chown -R www-data:www-data web -This step prevents permission errors during runtime and ensures that Drupal can generate files, manage uploads, and interact with modules safely. +This step prevents permission errors during runtime and ensures that Drupal can safely generate files, manage uploads, and interact with modules. -{{< Tip>}} +{{< tip >}} If you're using Nginx or a different web server, replace `www-data` with your actual server user (e.g., `nginx`, `apache`, or a custom service account). -{{< /Tip>}} +{{< /tip >}} To confirm ownership was updated, run this from the parent directory of `web`: @@ -101,15 +102,18 @@ To check ownership of a file, run: ls -l path/to/your/file (e.g., 'ls -l web/index.php') -This tells you who the file is owned by and the group. +This shows the file's owner and group. + +{{< tip >}} -{{< Tip>}} -If you need to replace incorrect ownership, rerun: +If ownership is incorrect, rerun: sudo chown -R www-data:www-data web And replace `www-data` with your actual web server user if different. +{{< /tip >}} + #### Drupal Project Presence To confirm the project was scaffolded correctly, verify the presence of key files and directories: @@ -118,9 +122,9 @@ To confirm the project was scaffolded correctly, verify the presence of key file ls web/index.php ls -d vendor/ -{{< Note>}} -If these files are missing, drupal has not been initialized. See the next section to scaffold the project using Composer. -{{< /Note>}} +{{< note >}} +If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to scaffold the project using Composer. +{{< /note >}} Contributor-Safe Tips @@ -129,25 +133,35 @@ Contributor-Safe Tips If all checks pass, your infrastructure is ready for Drupal initialization and configuration. +If `vendor/` is missing but `composer.json` is present, run: + + composer install + +- This installs required dependencies and generates the `vendor/` directory. +- If file permissions are relevant to your environment (e.g., restrictive umask settings or shared hosting), consider verifying ownership and access using `chmod` and `chown`. + +If at this point all checks pass the infrastructure is ready for Drupal initialization and configuration. + ## Initialize the Drupal Application Environment -After the `composer create-project` command, your environment should now include the core Drupal files and folder structure. This phase confirms that setup, prepares optional configuration scaffolding, and gets the application ready for site installation. +After running the `composer create-project` command, your environment should now include the core Drupal files and folder structure (`composer.json`, `web/index.php`, and `vendor/`). This phase was validated and confirms that setup succeeded, prepares optional configuration scaffolding, and gets the application ready for site installation. ## Create Project Structure Creating the project structure sets up Drupal for modular development and secure deployment. -This step separates application logic from public content, making updates easier to manage and reduce security risks. +This step separates application logic from public content, making updates easier to manage and reducing security risks. -{{< Note>}} -This guide assumes you're using Drupal 11.1.8 as noted earlier. -{{< /Note>}} +{{< note >}} +This guide was validated using Drupal 11.1.8 as noted earlier. +{{< /note >}} -### Create the Drupal project structure +### Create the Drupal Project Structure -- Run the install command to scaffold (create) the Drupal 11.1.8 structure, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) and customize the "my_drupal_site" name to fit your needs: +- Run the install command to scaffold (create) the Drupal 11.1.8 structure. Customize the "my_drupal_site" name to fit your needs. For +directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). - composer create-project drupal/recommended-project:11.1.8 my_drupal_site + composer create-project drupal/recommended-project:11.1.8 my_drupal_site -Then change to the project folder: @@ -168,17 +182,13 @@ If any of these are missing or return errors, installation may have failed or be **Following Composer Initialization** (scaffolded Drupal Project), confirm your environment against the **Drupal Site Setup checklist**: -- Change to the project folder. - - cd my_drupal_site - - Copy the default settings file. cp web/sites/default/default.settings.php web/sites/default/settings.php This creates the active configuration file that Drupal reads and writes to during installation and runtime. -### Set file permissions +### Set File Permissions - This is for `settings.php` (allows the owner to read/write, group and others to read, and the web server to access it during installation). Make sure you are in the Drupal project root folder and then run: @@ -186,7 +196,8 @@ This creates the active configuration file that Drupal reads and writes to durin *Optional: If you're on a shared host or strict environment, you may need to tighten permissions in the `settings.php` file to `640` or even `600`.* - Also, if you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. Running `chmod 644` now avoids this. +If you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. Running `chmod 644` now avoids this. + ### Create the files directory. Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root (`my_drupal_site`) run: @@ -249,14 +260,14 @@ Sensitive credentials can be abstracted using `.env` files or environment-specif ### CLI-based Installation -This guide uses the CLI method for consistency, automation, and contributor safety (using Drush 11.x for CLI-based installation, matching Drupal 11/1/8). +This guide uses the CLI method for consistency, automation, and contributor safety (leveraging Drush 11.x for CLI-based installation, matching Drupal 11/1/8). **Environment Validation**(Phase 1) | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-1ubuntu2.22` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions | Confirm required PHP modules | `php -m \| grep -E 'pdo'`|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip'` | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | +| Required Extensions | Confirm required PHP modules | php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip' | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | | Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | @@ -264,17 +275,19 @@ This guide uses the CLI method for consistency, automation, and contributor safe If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): -{{< Tip>}} +{{< tip >}} During installation, you may see a prompt like: `Do you want to continue?[Y/n]` This is a standard confirmation step. Type `Y` and press Enter to proceed. (If using a different package manager or install method, the prompt may vary slightly--but the intent is the same: confirm you want to install the listed components.) -{{< /Tip>}} +{{< /tip >}} **Installation** (Phase 2) -Install the Drupal codebase using Composer. This sets up the recommended project scaffold. Also assumes Composer and PHP are installed and working. See Phase 1 for environment prep. +Install the Drupal codebase using Composer. This sets up the recommended project scaffold. + +Composer and PHP should already be installed and working. See Phase 1 for environment prep. | **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| @@ -285,20 +298,20 @@ Install the Drupal codebase using Composer. This sets up the recommended project `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` `drush --version` | `Drush version 11.5.1` from global path | If not executable, recheck permissions or path | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | -* Confirm `composer.json` is writable and not locked by another process -** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x) -*** If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1` +* Confirm `composer.json` is writable and not locked by another process. +** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). +*** If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1`. **** If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. -** Post-Install Validation** (Phase 3) +**Post-Install Validation** (Phase 3) -After installation, confirm the setup is complete and ready for configuration. +After installation, confirm that setup completed successfully and is complete and ready for configuration. | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Success Confirmation | Validate install completion | Review terminal output | “Project created successfully” or similar message | If error shown, rerun with `-vvv` for verbose output | [Composer Troubleshooting](https://getcomposer.org/doc/articles/troubleshooting.md) | +| Success Confirmation | Validate install completion | *Review terminal output* | “Project created successfully” or similar message | If error shown, rerun with `-vvv` for verbose output | [Composer Troubleshooting](https://getcomposer.org/doc/articles/troubleshooting.md) | | Folder Structure | Confirm expected files exist | `ls mysite` | `composer.json`, `web/`, `vendor/`, etc. | If missing, check install logs or rerun install | [Drupal File Structure](https://www.drupal.org/docs/develop/structure-of-a-drupal-codebase) | -| Optional Cleanup | Remove message plugin (optional) | `composer remove drupal/core-project-message` | Plugin removed, no errors | If error, check Composer version or plugin dependencies | [Project Message Plugin](https://www.drupal.org/project/core_project_message) | +| Optional Cleanup | Remove message plugin (optional) | `composer` | Plugin removed, no errors | Check Composer version or plugin dependencies | [Project Message Plugin](https://www.drupal.org/project/core_project_message) | ### Launch the installer. @@ -306,10 +319,10 @@ Once your project structure is in place and Drush is installed, you can launch t | **Method** | **Purpose** | **Action / Command** | **Expected Result** | **If Output Differs** | 🔗 **Further Info** | |-------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/my_drupal_site/web` | Drupal installer page loads | Check PHP server is running, confirm `web` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | +| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/my_drupal_site/web` | Drupal installer page loads | Confirm PHP server is running, and `web/` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | | CLI-based install | Install Drupal via Drush | `vendor/bin/drush site:install` | Site installed with default config | Confirm database access, Drush version, and PHP compatibility | [Drush Site Install](https://www.drush.org/latest/commands/site-install/) | -> If using the PHP built-in server, run from your project root: +> Using the PHP built-in server, run: > ``` > php -S localhost:8888 -t web > ``` @@ -328,10 +341,10 @@ Apache is assumed to be installed and running. This section focuses on enabling | **Step** | **Purpose** | **Command / Config** | |---------------------------|----------------------------------------------|--------------------------------------------------------------------------------------| | Enable `mod_rewrite` | Support clean URLs | `sudo a2enmod rewrite`
`sudo systemctl restart apache2` | -| Set `AllowOverride All` | Allow `.htaccess` overrides | Edit Apache config file (`000-default.conf` or `drupal.conf`) | +| Set `AllowOverride All` | Allow `.htaccess` overrides | Edit Apache config file (`000-default.conf` or `drupal.conf`) and set:
`AllowOverride All` inside the `` block for your `/web` folder | | Reload Apache | Apply config changes | `sudo systemctl reload apache2` | -| Optional: Virtual Host | Use custom domain for local dev | Define `` block pointing to `/web` folder | -| Update `/etc/hosts` | Map custom domain to localhost | `127.0.0.1 drupal.local` | +| Optional: Virtual Host | Use custom domain for local dev | Define `` block pointing to `/web` folder in `drupal.conf` | +| Update `/etc/hosts` | Map custom domain to localhost | Add: `127.0.0.1 drupal.local` | | Enable site config | Activate virtual host | `sudo a2ensite drupal.conf`
`sudo systemctl reload apache2` | --- @@ -342,8 +355,15 @@ Apache is assumed to be installed and running. This section focuses on enabling Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: sudo a2enmod rewrite + sudo systemctl restart apache2 +This activates `mod_rewrite` and restarts Apache to apply the change. + +Success is achieved if there is no error output and Apache restarts cleanly. + +If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is alrady configured for clean URLs. + ## Local Testing Setup Before continuing, confirm that your local environment is serving the Drupal site correctly. This section helps validate Apache, PHP, and file permissions using a browser-based test. @@ -370,7 +390,9 @@ This maps `drupal.local` to your local machine: ## Security and Optimization -1. Run the MySQL hardening script to remove insecure defaults and set a root password: +1. Harden the MySQL Installation + +Run the MySQL hardening script to remove insecure defaults and set a root password: sudo mysql_secure_installation @@ -382,9 +404,9 @@ This interactive tool lets you: - Remove the test database - Reload privilege tables -{{< note>}} +{{< note >}} These steps help protect your Drupal site from unauthorized access and are strongly recommended for production environments. -{{< /note>}} +{{< /note >}} 2. Enable SSL (Optional) @@ -418,7 +440,7 @@ For local development, SSL is optional. For public sites it is essential. - Enforcing clean URLs {{< tip>}} -If `.htaccess` rules aren't being applied, double-check `AllowOverride All` in your Apache config. +If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is set in your Apache config. {{< /tip>}} 4. Security Checklist @@ -431,15 +453,15 @@ If `.htaccess` rules aren't being applied, double-check `AllowOverride All` in y ## Contributor-Safe Notes: Composer-First Workflow -- Legacy bridging for users coming from Drupal 8 +- Legacy Bridging for Users Coming From Drupal 8 Drupal 11.x expects a Composer-managed workflow. Composer is now the official and recommended method for managing Drupal core, contributed modules, and dependencies. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assumes a Composer-first setup to ensure compatibility with modern module management and depencency resolution. -- Avoiding brittle installs and opaque errors +- Avoiding brittle Installs and Opaque Errors Composer tracks dependencies explicitly, reducing the risk of missing extensions or mismatched versions. Manual installs often fail silently or introduce hard-to-trace errors. Using `composer create-project` ensures a reproducible, contributor-safe environment. -- Encouraging use of Drush for command-line efficiency +- Encouraging use of Drush for Command-Line Efficiency Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. Run Drush from you project directory: @@ -449,24 +471,26 @@ If you see errors about missing Symfony classes or autoloading failures, double- - You're inside the correct project folder (with `composer.json`, `vendor/`, and `web/`). - Drush is intalled locally--not globally or in `/root/vendor`. - - You're not running Drus from outside the project root. + - You're not running Drush from outside the project root. To confirm you're in the right place, look for: ls # Should include: composer.json, vendor/, web/ +### Contributor-Safe References + For official Drush installation guidance, see [Drush on Drupal.org](https://www.drupal.org/docs/develop/development-tools/drush). You can find additional information on [Drupal's Composer guide](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) for deeper context. ## Conclusion: What Comes Next -From here, you can begin customizing your site: +Your Drupal environment is now scaffolded, validated, and ready for customization. From here, you can begin shaping your site: -- Official [Drupal Documentation](https://www.drupal.org/documentation). +- Explore the Official [Drupal Documentation](https://www.drupal.org/documentation) for guidance on modules, configuration, and site building. -- Theme development: Create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to get a clear sense of what's possible. +- Get into theme development: create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to see hat's possible. -To see demonstrated [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) +To see inspiring real-world [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) explore how others have extended and styled their sites. From f36d08c931d2267f5eada405cd5e20deda6c9587 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Tue, 23 Sep 2025 15:58:16 -0700 Subject: [PATCH 05/46] Corrections to metadata --- .../index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index a2197536c69..d9926885bea 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -1,13 +1,13 @@ --- -slug: how-to-install-and-configure-drupal-on-ubuntu-22-04 -title: How to Install and Configure Drupal on Ubuntu 22.04 -title_meta: -description: Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices. +slug: "how-to-install-and-configure-drupal-on-ubuntu-22-04" +title: "How to Install and Configure Drupal on Ubuntu 22.04" +title_meta: "How to Install and Configure Drupal on Ubuntu 22.04" +description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices." author: ["Diana Hoober"] contributors: ["Diana Hoober"] -published: 2025-9-30 +published: 2025-09-30 keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Composer] -license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)" --- Drupal is a flexible content management system (CMS) designed for structured content and scalable site architecture. While it runs well in many hosting environments, Akamai’s compute instance offers a particularly strong foundation for high-traffic, content-rich deployments. This guide walks through installing and configuring Drupal 11 on Ubuntu 22.04 with systems-aware practices and contributor-safe steps that hold up in real-world scenarios. From 3f509ecef34fe071e0c6047b5dd9fec98e7f5af9 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Tue, 23 Sep 2025 16:05:14 -0700 Subject: [PATCH 06/46] Corrections to metadata authors --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index d9926885bea..68ade11f375 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -3,7 +3,7 @@ slug: "how-to-install-and-configure-drupal-on-ubuntu-22-04" title: "How to Install and Configure Drupal on Ubuntu 22.04" title_meta: "How to Install and Configure Drupal on Ubuntu 22.04" description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices." -author: ["Diana Hoober"] +authors: ["Diana Hoober"] contributors: ["Diana Hoober"] published: 2025-09-30 keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Composer] From 0ed50cff662c91132ac6ca18a4f1105d8440ac6a Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Tue, 23 Sep 2025 16:22:23 -0700 Subject: [PATCH 07/46] Remove tip and change to note --- .../index.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 68ade11f375..90bb586ecac 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -80,9 +80,9 @@ Before proceeding, make sure your web server has permission to interact with the This step prevents permission errors during runtime and ensures that Drupal can safely generate files, manage uploads, and interact with modules. -{{< tip >}} +{{< note >}} If you're using Nginx or a different web server, replace `www-data` with your actual server user (e.g., `nginx`, `apache`, or a custom service account). -{{< /tip >}} +{{< /note >}} To confirm ownership was updated, run this from the parent directory of `web`: @@ -104,7 +104,7 @@ To check ownership of a file, run: This shows the file's owner and group. -{{< tip >}} +{{< note >}} If ownership is incorrect, rerun: @@ -112,7 +112,7 @@ If ownership is incorrect, rerun: And replace `www-data` with your actual web server user if different. -{{< /tip >}} +{{< /note >}} #### Drupal Project Presence @@ -275,13 +275,13 @@ This guide uses the CLI method for consistency, automation, and contributor safe If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): -{{< tip >}} +{{< note >}} During installation, you may see a prompt like: `Do you want to continue?[Y/n]` This is a standard confirmation step. Type `Y` and press Enter to proceed. (If using a different package manager or install method, the prompt may vary slightly--but the intent is the same: confirm you want to install the listed components.) -{{< /tip >}} +{{< /note >}} **Installation** (Phase 2) @@ -439,9 +439,9 @@ For local development, SSL is optional. For public sites it is essential. - Blocking directory listings - Enforcing clean URLs -{{< tip>}} +{{< note >}} If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is set in your Apache config. -{{< /tip>}} +{{< /note >}} 4. Security Checklist - **Database hardened** with `mysql_secure_installation` From b183510a633b546f7774519f9f9d65b8003cc9f4 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Tue, 23 Sep 2025 16:42:39 -0700 Subject: [PATCH 08/46] Space removed --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 90bb586ecac..3e3f12c877b 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -455,7 +455,7 @@ If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is s - Legacy Bridging for Users Coming From Drupal 8 -Drupal 11.x expects a Composer-managed workflow. Composer is now the official and recommended method for managing Drupal core, contributed modules, and dependencies. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assumes a Composer-first setup to ensure compatibility with modern module management and depencency resolution. +Drupal 11.x expects Composer-managed workflow. Composer is now the official and recommended method for managing Drupal core, contributed modules, and dependencies. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assumes a Composer-first setup to ensure compatibility with modern module management and depencency resolution. - Avoiding brittle Installs and Opaque Errors From dfb2aed0e29f313792db7bba04142ae92dfe0f83 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 09:24:09 -0700 Subject: [PATCH 09/46] metadata corrections --- .../index.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 3e3f12c877b..2aca5cb5c75 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -2,12 +2,13 @@ slug: "how-to-install-and-configure-drupal-on-ubuntu-22-04" title: "How to Install and Configure Drupal on Ubuntu 22.04" title_meta: "How to Install and Configure Drupal on Ubuntu 22.04" -description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices." +description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices" authors: ["Diana Hoober"] contributors: ["Diana Hoober"] published: 2025-09-30 -keywords: [Drupal, Ubuntu 22.04, CMS, installation, contributor-safe, Composer] -license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)" +modified: 2025-09-30 +keywords: ["Drupal", "Ubuntu 22.04", "CMS", "installation", "contributor-safe", "Composer"] +license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/)" --- Drupal is a flexible content management system (CMS) designed for structured content and scalable site architecture. While it runs well in many hosting environments, Akamai’s compute instance offers a particularly strong foundation for high-traffic, content-rich deployments. This guide walks through installing and configuring Drupal 11 on Ubuntu 22.04 with systems-aware practices and contributor-safe steps that hold up in real-world scenarios. From b211f4053c979c980d9dcc256808b956825b26ca Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 09:33:46 -0700 Subject: [PATCH 10/46] metadata correction --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 2aca5cb5c75..fe65a520c6a 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -7,7 +7,7 @@ authors: ["Diana Hoober"] contributors: ["Diana Hoober"] published: 2025-09-30 modified: 2025-09-30 -keywords: ["Drupal", "Ubuntu 22.04", "CMS", "installation", "contributor-safe", "Composer"] +keywords: ["Drupal", "Ubuntu 22.04", "installation", "contributor-safe", "Composer"] license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/)" --- From 19b9f1e0d1a6ddf07e0b129b43cb37f3585170dd Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 10:47:50 -0700 Subject: [PATCH 11/46] correction --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index fe65a520c6a..546e5def948 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -363,7 +363,7 @@ This activates `mod_rewrite` and restarts Apache to apply the change. Success is achieved if there is no error output and Apache restarts cleanly. -If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is alrady configured for clean URLs. +If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is already configured for clean URLs. ## Local Testing Setup From 9eb8694ea5b91dd9eb7abecd13d9b036441a921b Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 11:35:27 -0700 Subject: [PATCH 12/46] Rearranged sectioins --- .../index.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 546e5def948..f1c27191e0b 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -143,19 +143,19 @@ If `vendor/` is missing but `composer.json` is present, run: If at this point all checks pass the infrastructure is ready for Drupal initialization and configuration. -## Initialize the Drupal Application Environment - -After running the `composer create-project` command, your environment should now include the core Drupal files and folder structure (`composer.json`, `web/index.php`, and `vendor/`). This phase was validated and confirms that setup succeeded, prepares optional configuration scaffolding, and gets the application ready for site installation. - ## Create Project Structure Creating the project structure sets up Drupal for modular development and secure deployment. This step separates application logic from public content, making updates easier to manage and reducing security risks. -{{< note >}} -This guide was validated using Drupal 11.1.8 as noted earlier. -{{< /note >}} +After you run the `composer create-project` command below, your environment will include the core Drupal files and folder structure: + +- `composer.json` +- `web/index.php` +- `vendor/`. + +This confirms that setup succeeded, prepares optional configuration scaffolding, and gets the application ready for site installation. *This guide was validated using Drupal 11.1.8 as noted earlier.* ### Create the Drupal Project Structure @@ -164,9 +164,9 @@ directory layout details, see [Drupal.org's Directory Structure guide](https://w composer create-project drupal/recommended-project:11.1.8 my_drupal_site --Then change to the project folder: +-Then change to your project folder (removing the <> symbols and replacing with your folder name): - cd my_drupal_site + cd - Inside the scaffolded project folder `my_drupal_site`, confirm the environment after installation with: From b48734f8bd6247d56c89450a799245bf14835655 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 16:26:21 -0700 Subject: [PATCH 13/46] Clarified Composer version line - resolves prior suggestion --- .../index.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index f1c27191e0b..e997d02978d 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -11,11 +11,11 @@ keywords: ["Drupal", "Ubuntu 22.04", "installation", "contributor-safe", "Compos license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/)" --- -Drupal is a flexible content management system (CMS) designed for structured content and scalable site architecture. While it runs well in many hosting environments, Akamai’s compute instance offers a particularly strong foundation for high-traffic, content-rich deployments. This guide walks through installing and configuring Drupal 11 on Ubuntu 22.04 with systems-aware practices and contributor-safe steps that hold up in real-world scenarios. +Drupal is a flexible content management system (CMS) designed for structured content and scalable site architecture. While it runs well in many hosting environments, Akamai’s compute instance provides a resilient foundation for high-traffic, content-rich deployments. This guide walks through installing and configuring Drupal 11 on Ubuntu 22.04 with systems-aware practices and contributor-safe steps that hold up in real-world scenarios. ## Before You Begin -This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases--specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer. First, we'll walk through prerequisites, setup and verification to ensure a reliable install, then move into installing Drupal. +This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. Specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer after verifying system prerequisites. ## System Prerequisites @@ -69,9 +69,9 @@ To verify installation: composer --version -You should see output like `Composer version 2.7.0 or higher. +You should see output like `Composer version 2.7.0` or higher. -If the command fails, see [Composer Installation - Manual Download](https://getcomposer.org/doc/00-intro.md#manual-installation). +If the command fails, see [Composer Installation - Manual Download](https://getcomposer.org/doc/00-intro.md#manual-installation) for fallback steps. #### Verify the Web Server @@ -89,7 +89,7 @@ To confirm ownership was updated, run this from the parent directory of `web`: ls -ld web -This shows you the ownership and permission of the `web` directory itself: +This confirms the ownership and permissions of the `web` directory: drwxr-xr-x 7 www-data -www-data 4096 Sep 16 22:28 web @@ -99,7 +99,7 @@ This means: - `www-data` is also the group - The permissions are `drwxr-xr-x` (read/write/execute for owner, read/execute for group and others.) -To check ownership of a file, run: +To verify ownership of individual files, run: ls -l path/to/your/file (e.g., 'ls -l web/index.php') From 3f8eaef1afa173c2c6748c5358a84b2ba1ee1e1c Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 24 Sep 2025 16:51:31 -0700 Subject: [PATCH 14/46] Removed duplicate vendor missing content --- .../index.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index e997d02978d..a459eeca6bb 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -132,15 +132,6 @@ Contributor-Safe Tips - Be sure to consider mentioning file permissions if they are relevant to your environment (e.g., `chmod`, `chown`). - If `vendor/` is missing but `composer.json` is present, run `composer install`. -If all checks pass, your infrastructure is ready for Drupal initialization and configuration. - -If `vendor/` is missing but `composer.json` is present, run: - - composer install - -- This installs required dependencies and generates the `vendor/` directory. -- If file permissions are relevant to your environment (e.g., restrictive umask settings or shared hosting), consider verifying ownership and access using `chmod` and `chown`. - If at this point all checks pass the infrastructure is ready for Drupal initialization and configuration. ## Create Project Structure From 0ad560a6a154ccfc69d1fbcb7428fbe6eb191a8e Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Thu, 25 Sep 2025 11:32:57 -0700 Subject: [PATCH 15/46] Update docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md Co-authored-by: DianaHoober --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index a459eeca6bb..659e625c41d 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -482,7 +482,7 @@ Your Drupal environment is now scaffolded, validated, and ready for customizatio - Explore the Official [Drupal Documentation](https://www.drupal.org/documentation) for guidance on modules, configuration, and site building. -- Get into theme development: create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to see hat's possible. +- Get into theme development: create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to see what's possible. To see inspiring real-world [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) explore how others have extended and styled their sites. From 16e80883cf905f0e3a30166dd513e96c1ec300a4 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Thu, 25 Sep 2025 11:37:29 -0700 Subject: [PATCH 16/46] Update docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md Co-authored-by: DianaHoober --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 659e625c41d..afcf6677fca 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -478,7 +478,7 @@ You can find additional information on [Drupal's Composer guide](https://www.dru ## Conclusion: What Comes Next -Your Drupal environment is now scaffolded, validated, and ready for customization. From here, you can begin shaping your site: +Your Drupal environment is now structured, validated, and ready for customization. From here, you can begin shaping your site: - Explore the Official [Drupal Documentation](https://www.drupal.org/documentation) for guidance on modules, configuration, and site building. From 791b26890b7ee12f421ef5db0512005cdecc6a64 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Thu, 25 Sep 2025 11:40:08 -0700 Subject: [PATCH 17/46] Update docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md Co-authored-by: DianaHoober --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index afcf6677fca..72c05c0e7c0 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -462,7 +462,7 @@ Drush streamlines tasks like site installation, cache clearing, and module manag If you see errors about missing Symfony classes or autoloading failures, double-check that: - You're inside the correct project folder (with `composer.json`, `vendor/`, and `web/`). - - Drush is intalled locally--not globally or in `/root/vendor`. + - Drush is installed locally--not globally or in `/root/vendor`. - You're not running Drush from outside the project root. To confirm you're in the right place, look for: From dd0c570d974ffed9fa5bee918a131845daa1a76d Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Thu, 25 Sep 2025 11:46:49 -0700 Subject: [PATCH 18/46] Apply suggestions from code review Miscellaneous corrections. Co-authored-by: DianaHoober --- .../index.md | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 72c05c0e7c0..3df7b38d07a 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -91,7 +91,7 @@ To confirm ownership was updated, run this from the parent directory of `web`: This confirms the ownership and permissions of the `web` directory: - drwxr-xr-x 7 www-data -www-data 4096 Sep 16 22:28 web + drwxr-xr-x 7 www-data www-data 4096 Sep 16 22:28 web This means: @@ -117,20 +117,23 @@ And replace `www-data` with your actual web server user if different. #### Drupal Project Presence -To confirm the project was scaffolded correctly, verify the presence of key files and directories: +To confirm the project was initialized correctly, verify the presence of key files and directories: ls composer.json ls web/index.php ls -d vendor/ {{< note >}} -If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to scaffold the project using Composer. +If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to set up the project using Composer. {{< /note >}} Contributor-Safe Tips - Be sure to consider mentioning file permissions if they are relevant to your environment (e.g., `chmod`, `chown`). -- If `vendor/` is missing but `composer.json` is present, run `composer install`. +- If `vendor/` is missing but `composer.json` is present, run: + `composer install` + - This installs required dependencies and generates the `vendor/` directory. + - If file permissions are relevant to your environment (e.g., restrictive file creation settings or shared hosting), verify ownership and access using `chmod` and `chown`. If at this point all checks pass the infrastructure is ready for Drupal initialization and configuration. @@ -140,29 +143,33 @@ Creating the project structure sets up Drupal for modular development and secure This step separates application logic from public content, making updates easier to manage and reducing security risks. -After you run the `composer create-project` command below, your environment will include the core Drupal files and folder structure: +After running the `composer create-project` command below, your environment should include the core Drupal files and folder structure: - `composer.json` - `web/index.php` -- `vendor/`. +- `vendor/` -This confirms that setup succeeded, prepares optional configuration scaffolding, and gets the application ready for site installation. *This guide was validated using Drupal 11.1.8 as noted earlier.* +These files confirm that setup succeeded, prepare optional configuration scaffolding, and get the application ready for site installation. *This guide was validated using Drupal 11.1.8 as noted earlier.* ### Create the Drupal Project Structure -- Run the install command to scaffold (create) the Drupal 11.1.8 structure. Customize the "my_drupal_site" name to fit your needs. For +- Run the install command to generate the Drupal 11.1.8 structure. Replace "my_drupal_site" with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). composer create-project drupal/recommended-project:11.1.8 my_drupal_site --Then change to your project folder (removing the <> symbols and replacing with your folder name): +-Change to your project folder (remove the angle brackets (<>) and use your actual folder name): - cd + cd my-drupal-site -- Inside the scaffolded project folder `my_drupal_site`, confirm the environment after installation with: +- Inside the newly created project folder, confirm the environment after installation: ls composer.json - Result: `composer.json` confirming the metadata file exists + ls -ld web/indes.php + ls -ld vendor/ + - `composer.json` confirms the metadata file exists + - `web/index.php` confirms the application entry point + - `vendor/` confirming that the `vendor/` directory was created. ls -ld web/index.php Response: `web/index.php` confirms the application entry point file exists. @@ -172,7 +179,7 @@ directory layout details, see [Drupal.org's Directory Structure guide](https://w If any of these are missing or return errors, installation may have failed or been interrupted. For troubleshooting see [Installing Drupal - Getting Started Guide](https://www.drupal.org/docs/getting-started/installing-drupal). -**Following Composer Initialization** (scaffolded Drupal Project), confirm your environment against the **Drupal Site Setup checklist**: +**Following Composer Initialization** (using the recommended Drupal starter template, which places core files like `index.php`, `update.php`, and `.htaccess` in their correct locations), confirm your environment against the **Drupal Site Setup checklist**: - Copy the default settings file. @@ -190,7 +197,7 @@ This creates the active configuration file that Drupal reads and writes to durin If you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. Running `chmod 644` now avoids this. -### Create the files directory. +### Create the Files Directory Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root (`my_drupal_site`) run: @@ -205,13 +212,13 @@ The `chmod` allows owner and group read, write, and execute permissions and othe chown -R www-data web/sites/default/files -Use your actual web server for `www-data`. A writable `files` directory allows Drupal to store uploads (i.e., images or module enablement) or generate cached assets so you don't see any errors. +Use your actual web server for `www-data`. A writable `files` directory allows Drupal to store uploads (i.e., images or enabled modules) or generate cached assets so you don't see any errors. ### Prepare the database. -Before installing Drupal, follow the official guide to create a database and user for Drupal [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). +Before installing Drupal, follow the official guide to create a database and user: [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). -- Once complete, confirm with a contributor-safe verification block: +- Once complete, confirm access with a contributor-safe check: mysql -u drupal_user -p -h localhost drupal_db From 1637b9aebcf02d70cabf3972ea68a00efae3f500 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Thu, 25 Sep 2025 11:55:33 -0700 Subject: [PATCH 19/46] Apply suggestions from code review Additional changes to accommodate Vale spell checker. Co-authored-by: DianaHoober --- .../index.md | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 3df7b38d07a..06eaa8d2b51 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -222,8 +222,8 @@ Before installing Drupal, follow the official guide to create a database and use mysql -u drupal_user -p -h localhost drupal_db -You should be able to enter the MariaDB shell without errors. -Your database used `utf8mb4` encoding: +Replace `drupaluser` and `drubaldb` with your database username and name. You should be able to enter the MariaDB shell without errors. +Confirm that your database uses `utf8mb4` encoding: SHOW CREATE DATABASE drupal_db; @@ -238,13 +238,13 @@ $databases['default']['default'] = [ 'host' => 'localhost', ]; -This is located in `sites/default/settings.php` +- This configuration is located in `sites/default/settings.php`. -- File permissions might need to be temporarily relaxed during setup with: +- During setup you may need to temporarily relax file permissions: chmod 664 sites/default/settings.php -1. Common Errors and Fixes +Common Errors and Fixes | Error Message | Likely Cause | Fix | Resource | |-------------------------------|-------------------------------|------------------------------------------|--------------------------------------------------------------------------| @@ -253,24 +253,24 @@ This is located in `sites/default/settings.php` | Driver not found | Incorrect or missing driver | Use `'driver' => 'mysql'` for MariaDB | [Drupal.org: Database API Overview](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration) | | Warning: count() during install | Misconfigured array structure | Ensure `$databases` array is properly nested | [Stack Overflow](https://stackoverflow.com/questions/71596215/how-can-i-set-up-my-drupal-database-correctely) (yes, there is a typo in that title s/b correctly). | -1. Optional: Environment Variables +Optional: Environment Variables -Sensitive credentials can be abstracted using `.env` files or environment-specific config, see [Drupal.org's environment config practices](https://www.drupal.org/project/env). +You can abstract sensitive credentials using `.env` files or environment-specific config, see [Drupal.org's environment config practices](https://www.drupal.org/project/env). ### CLI-based Installation -This guide uses the CLI method for consistency, automation, and contributor safety (leveraging Drush 11.x for CLI-based installation, matching Drupal 11/1/8). +This guide uses the command-line method for consistency, automation, and contributor safety (leveraging Drush 11.x for CLI-based installation, matching Drupal 11.1.8). **Environment Validation**(Phase 1) | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions | Confirm required PHP modules | php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip' | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Required Extensions | Confirm required PHP modules | php -m \| grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip' | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | | Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | -* Running Composer as root is discouraged. Safe for local testing, but avoid in production. +* Running Composer as root is discouraged. It's safe for local testing but avoid in production. If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): @@ -284,22 +284,23 @@ This is a standard confirmation step. Type `Y` and press Enter to proceed. (If u **Installation** (Phase 2) -Install the Drupal codebase using Composer. This sets up the recommended project scaffold. +Install the Drupal codebase using Composer. This sets up the recommended starter template and project structure. Composer and PHP should already be installed and working. See Phase 1 for environment prep. | **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Create Project | Scaffold Drupal site | `composer create-project drupal/recommended-project mysite` | `mysite` folder created with Drupal scaffold | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | +| Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | | Install Drush (local) | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints*, **, *** | [Drush Docs](https://www.drush.org/latest/install/) | -| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | +| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | Rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | | Optional Global Install| Make Drush available system-wide | Download `drush.phar`, then run: `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` - `drush --version` | `Drush version 11.5.1` from global path | If not executable, recheck permissions or path | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | + `drush --version` | `Drush version 11.5.1` from global path | Recheck permissions or path if not executable | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | * Confirm `composer.json` is writable and not locked by another process. ** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). -*** If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1`. +*** If you see a memory error, try: +`COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1`. **** If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. **Post-Install Validation** (Phase 3) @@ -359,7 +360,7 @@ sudo systemctl restart apache2 This activates `mod_rewrite` and restarts Apache to apply the change. -Success is achieved if there is no error output and Apache restarts cleanly. +Success: No error output and Apache restarts cleanly. If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is already configured for clean URLs. @@ -443,9 +444,9 @@ If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is s {{< /note >}} 4. Security Checklist - - **Database hardened** with `mysql_secure_installation` + - **Database hardened** using `mysql_secure_installation` - **File permission** set for install and post-install - - **`.htaccess`** rules active + - **`.htaccess`** rules active and enforced - **SSL configured** (if public-facing) --- From 268573e491aaaaae09a93bd5bdb70dae85d9e644 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Thu, 25 Sep 2025 20:06:52 +0000 Subject: [PATCH 20/46] Slug syntax --- .../index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 06eaa8d2b51..1badace2e64 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -1,5 +1,5 @@ --- -slug: "how-to-install-and-configure-drupal-on-ubuntu-22-04" +slug: how-to-install-and-configure-drupal-on-ubuntu-22-04 title: "How to Install and Configure Drupal on Ubuntu 22.04" title_meta: "How to Install and Configure Drupal on Ubuntu 22.04" description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices" From aa8314f36f41563819bbfbade35880a7ebf37c31 Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Thu, 25 Sep 2025 20:10:35 +0000 Subject: [PATCH 21/46] Change publish and modified dates --- .../index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 1badace2e64..2db41a0a6bd 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -5,8 +5,8 @@ title_meta: "How to Install and Configure Drupal on Ubuntu 22.04" description: "Step-by-step guide for installing Drupal on Ubuntu 22.04 with contributor-safe practices" authors: ["Diana Hoober"] contributors: ["Diana Hoober"] -published: 2025-09-30 -modified: 2025-09-30 +published: 2025-09-25 +modified: 2025-09-25 keywords: ["Drupal", "Ubuntu 22.04", "installation", "contributor-safe", "Composer"] license: "[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0/)" --- From f8a6fe3e85ab3f55c5d88a5a98f6d41569bca6ea Mon Sep 17 00:00:00 2001 From: Nathan Melehan Date: Fri, 26 Sep 2025 22:03:22 +0000 Subject: [PATCH 22/46] Vale fixes --- .../index.md | 41 +++++++++++-------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 2db41a0a6bd..8bb259f56a3 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -153,7 +153,7 @@ These files confirm that setup succeeded, prepare optional configuration scaffol ### Create the Drupal Project Structure -- Run the install command to generate the Drupal 11.1.8 structure. Replace "my_drupal_site" with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). +- Run the install command to generate the Drupal 11.1.8 structure. Replace `my_drupal_site` with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). composer create-project drupal/recommended-project:11.1.8 my_drupal_site @@ -218,31 +218,40 @@ Use your actual web server for `www-data`. A writable `files` directory allows D Before installing Drupal, follow the official guide to create a database and user: [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). -- Once complete, confirm access with a contributor-safe check: +1. Once complete, confirm access with a contributor-safe check: + ```command mysql -u drupal_user -p -h localhost drupal_db + ``` -Replace `drupaluser` and `drubaldb` with your database username and name. You should be able to enter the MariaDB shell without errors. -Confirm that your database uses `utf8mb4` encoding: + Replace `drupaluser` and `drubaldb` with your database username and name. You should be able to enter the MariaDB shell without errors. +1. Confirm that your database uses `utf8mb4` encoding: + + ```command SHOW CREATE DATABASE drupal_db; + ``` -- Look for `CHARACTER SET utf8mb4`. Your credentials match what you'll enter in `settings.php`: +1. Look for `CHARACTER SET utf8mb4`. Your credentials match what you'll enter in `settings.php`: -$databases['default']['default'] = [ + ```file + $databases['default']['default'] = [ - 'driver' => 'mysql', - 'database' => 'drupal_db', - 'username' => 'drupal_user', - 'password' => 'your_secure_password', - 'host' => 'localhost', - ]; + 'driver' => 'mysql', + 'database' => 'drupal_db', + 'username' => 'drupal_user', + 'password' => 'your_secure_password', + 'host' => 'localhost', + ]; + ``` -- This configuration is located in `sites/default/settings.php`. + This configuration is located in `sites/default/settings.php`. -- During setup you may need to temporarily relax file permissions: +1. During setup you may need to temporarily relax file permissions: + ```command chmod 664 sites/default/settings.php + ``` Common Errors and Fixes @@ -266,7 +275,7 @@ This guide uses the command-line method for consistency, automation, and contrib | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions | Confirm required PHP modules | php -m \| grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip' | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Required Extensions | Confirm required PHP modules | `php -m \| grep -E 'pdo\|mbstring\|xml\|json\|ctype\|tokenizer\|curl\|openssl\|zip'` | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | | Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | @@ -295,7 +304,7 @@ Composer and PHP should already be installed and working. See Phase 1 for enviro | Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | Rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | | Optional Global Install| Make Drush available system-wide | Download `drush.phar`, then run: `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` - `drush --version` | `Drush version 11.5.1` from global path | Recheck permissions or path if not executable | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | + `drush --version` | `Drush version 11.5.1` from global path | Recheck permissions or path if not executable | [Drush `.phar` Install](https://github.com/drush-ops/drush/releases) | * Confirm `composer.json` is writable and not locked by another process. ** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). From 7c581d6828bd7816eb177267a6617df31658f205 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Fri, 26 Sep 2025 15:37:07 -0700 Subject: [PATCH 23/46] Update index.md fixed occurrences of Underscores for my-drupal-site. --- .../index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 8bb259f56a3..070ea623b0c 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -153,10 +153,10 @@ These files confirm that setup succeeded, prepare optional configuration scaffol ### Create the Drupal Project Structure -- Run the install command to generate the Drupal 11.1.8 structure. Replace `my_drupal_site` with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). +- Run the install command to generate the Drupal 11.1.8 structure. Replace `my-drupal-site` with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). - composer create-project drupal/recommended-project:11.1.8 my_drupal_site + composer create-project drupal/recommended-project:11.1.8 my-drupal-site -Change to your project folder (remove the angle brackets (<>) and use your actual folder name): From 1ea984cba7a718fef71d1c93d8e5ad774fbbdcd9 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 1 Oct 2025 14:32:10 -0700 Subject: [PATCH 24/46] Fixed formatting problems that were originally missed --- .../index.md | 25 +++++++++---------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index a459eeca6bb..42839c748f2 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -117,14 +117,14 @@ And replace `www-data` with your actual web server user if different. #### Drupal Project Presence -To confirm the project was scaffolded correctly, verify the presence of key files and directories: +To confirm the project was structured correctly, verify the presence of key files and directories: ls composer.json ls web/index.php ls -d vendor/ {{< note >}} -If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to scaffold the project using Composer. +If any of these files are missing, Drupal has not been initialized. See the [Create the Drupal Project Structure](#create-the-drupal-project-structure) to scaffold the project using Composer. {{< /note >}} Contributor-Safe Tips @@ -259,11 +259,12 @@ This guide uses the CLI method for consistency, automation, and contributor safe | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions | Confirm required PHP modules | php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|zip' | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Required Extensions | Confirm required PHP modules | See command below** | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | | Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | * Running Composer as root is discouraged. Safe for local testing, but avoid in production. +** php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip' If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): @@ -285,7 +286,7 @@ Composer and PHP should already be installed and working. See Phase 1 for enviro |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | Create Project | Scaffold Drupal site | `composer create-project drupal/recommended-project mysite` | `mysite` folder created with Drupal scaffold | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | | Install Drush (local) | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints*, **, *** | [Drush Docs](https://www.drush.org/latest/install/) | -| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | +| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | | | Optional Global Install| Make Drush available system-wide | Download `drush.phar`, then run: `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` `drush --version` | `Drush version 11.5.1` from global path | If not executable, recheck permissions or path | [Drush Phar Install](https://github.com/drush-ops/drush/releases) | @@ -346,9 +347,8 @@ Apache is assumed to be installed and running. This section focuses on enabling Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: -sudo a2enmod rewrite - -sudo systemctl restart apache2 + sudo a2enmod rewrite + sudo systemctl restart apache2 This activates `mod_rewrite` and restarts Apache to apply the change. @@ -371,13 +371,12 @@ Before continuing, confirm that your local environment is serving the Drupal sit --- -### Line-by-Line Walkthrough +#### Line-by-Line Walkthrough **1. Add an entry to `/etc/hosts`** This maps `drupal.local` to your local machine: -``` 127.0.0.1 drupal.local ## Security and Optimization @@ -459,16 +458,17 @@ Drush streamlines tasks like site installation, cache clearing, and module manag ./vendor/bin/drush/status -If you see errors about missing Symfony classes or autoloading failures, double-check that: +If you see errors about missing Symfony classes or auto-loading failures, double-check that: - You're inside the correct project folder (with `composer.json`, `vendor/`, and `web/`). - - Drush is intalled locally--not globally or in `/root/vendor`. + - Drush is installed locally--not globally or in `/root/vendor`. - You're not running Drush from outside the project root. To confirm you're in the right place, look for: ls - # Should include: composer.json, vendor/, web/ + +This should list: composer.json, vendor/, web/ ### Contributor-Safe References @@ -485,4 +485,3 @@ Your Drupal environment is now scaffolded, validated, and ready for customizatio - Get into theme development: create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to see hat's possible. To see inspiring real-world [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) explore how others have extended and styled their sites. - From f2070410aa8917234dd072eb6123dd0225b94837 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Wed, 1 Oct 2025 17:59:21 -0700 Subject: [PATCH 25/46] Contributor-sfe: update .vale.ini to bypass false linting errors --- .vale.ini | 1 + 1 file changed, 1 insertion(+) diff --git a/.vale.ini b/.vale.ini index a854bd93954..921353fd4f7 100644 --- a/.vale.ini +++ b/.vale.ini @@ -21,6 +21,7 @@ WordTemplate = \s(?:%s)\s # To add another style, just add it to the `StylesPath` and update the setting # below (e.g., `BasedOnStyles = Linode, AnotherStyle`). BasedOnStyles = Linode +Vocab = vocab # Exclude `{{< file >}}`, `{{< file-excerpt >}}`, `{{< output >}}`, # and `{{< highlight ... >}}`. From a800ad29d1399f53f727908959e841c0f1c98bae Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Thu, 2 Oct 2025 11:45:49 -0700 Subject: [PATCH 26/46] Resolved conflicts and spelling errors --- .../index.md | 109 +++++++++--------- 1 file changed, 57 insertions(+), 52 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index d8638cec21d..c0a4b66db34 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -21,12 +21,12 @@ This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. This guide is based on a tested configuration that ensures Drupal 11 installs cleanly and performs reliably within an Akamai-optimized infrastructure. The following prerequisites were used for validation. -- ✅ OS: Ubuntu 22.04 LTS -- ✅ Apache: Version 2.4.52+ -- ✅ PHP: Version 8.1+ (Drupal 11 optimized for PHP 8.3) -- ✅ MariaDB 10.3.7+ or MySQL: 5.7.8 (Drupal 11) Installed and secured -- ✅ Composer: 2.7.0+ (Drupal 11) Installed globally -- ✅ Drupal: Latest stable version (11.1.8 as of Sept 2025) will be installed after the environment setup +- OS: Ubuntu 22.04 LTS +- Apache: Version 2.4.52+ +- PHP: Version 8.1+ (Drupal 11 optimized for PHP 8.3) +- Composer: 2.7.0+ (Drupal 11) Installed globally +- MariaDB 10.3.7+ or MySQL: 5.7.8 (Drupal 11) Installed and secured +- Drupal: Latest stable version (11.1.8 as of Sept 2025) will be installed after the environment setup This configuration was verified to support structured content management, contributor workflows, and integration with Akamai’s caching and security layers. @@ -106,33 +106,23 @@ To verify ownership of individual files, run: This shows the file's owner and group. {{< note >}} - If ownership is incorrect, rerun: sudo chown -R www-data:www-data web And replace `www-data` with your actual web server user if different. - {{< /note >}} #### Drupal Project Presence -<<<<<<< HEAD -To confirm the project was structured correctly, verify the presence of key files and directories: -======= To confirm the project was initialized correctly, verify the presence of key files and directories: ->>>>>>> 7c581d6828bd7816eb177267a6617df31658f205 ls composer.json ls web/index.php ls -d vendor/ {{< note >}} -<<<<<<< HEAD -If any of these files are missing, Drupal has not been initialized. See the [Create the Drupal Project Structure](#create-the-drupal-project-structure) to scaffold the project using Composer. -======= If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to set up the project using Composer. ->>>>>>> 7c581d6828bd7816eb177267a6617df31658f205 {{< /note >}} Contributor-Safe Tips @@ -164,26 +154,38 @@ These files confirm that setup succeeded, prepare optional configuration scaffol - Run the install command to generate the Drupal 11.1.8 structure. Replace `my-drupal-site` with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). +``` composer create-project drupal/recommended-project:11.1.8 my-drupal-site +``` -Change to your project folder (remove the angle brackets (<>) and use your actual folder name): +``` cd my-drupal-site +``` - Inside the newly created project folder, confirm the environment after installation: +``` ls composer.json ls -ld web/index.php ls -ld vendor/ - - `composer.json` confirms the metadata file exists - - `web/index.php` confirms the application entry point - - `vendor/` confirming that the `vendor/` directory was created. +``` + - `composer.json` confirms the metadata file exists + - `web/index.php` confirms the application entry point + - `vendor/` confirming that the `vendor/` directory was created. +``` ls -ld web/index.php - Response: `web/index.php` confirms the application entry point file exists. +``` + Response: `web/index.php` confirms the application entry point file exists. + +``` ls -ld vendor/ - Response:`vendor/` confirming that the `vendor/` directory was created. +``` + + Response:`vendor/` confirming that the `vendor/` directory was created. If any of these are missing or return errors, installation may have failed or been interrupted. For troubleshooting see [Installing Drupal - Getting Started Guide](https://www.drupal.org/docs/getting-started/installing-drupal). @@ -191,15 +193,19 @@ If any of these are missing or return errors, installation may have failed or be - Copy the default settings file. +``` cp web/sites/default/default.settings.php web/sites/default/settings.php +``` This creates the active configuration file that Drupal reads and writes to during installation and runtime. ### Set File Permissions -- This is for `settings.php` (allows the owner to read/write, group and others to read, and the web server to access it during installation). Make sure you are in the Drupal project root folder and then run: +This is for `settings.php` (allows the owner to read/write, group and others to read, and the web server to access it during installation). Make sure you are in the Drupal project root folder and then run: +``` chmod 644 web/sites/default/settings.php +``` *Optional: If you're on a shared host or strict environment, you may need to tighten permissions in the `settings.php` file to `640` or even `600`.* @@ -284,19 +290,13 @@ This guide uses the command-line method for consistency, automation, and contrib |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | <<<<<<< HEAD -| Required Extensions | Confirm required PHP modules | See command below** | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | -| Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | -| Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | - -* Running Composer as root is discouraged. Safe for local testing, but avoid in production. -** php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip' -======= -| Required Extensions | Confirm required PHP modules | `php -m \| grep -E 'pdo\|mbstring\|xml\|json\|ctype\|tokenizer\|curl\|openssl\|zip'` | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | -| Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings* | [Composer Docs](https://getcomposer.org/doc/) | +| Required Extensions | Confirm required PHP modules | See command below* | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings** | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | +--- -* Running Composer as root is discouraged. It's safe for local testing but avoid in production. ->>>>>>> 7c581d6828bd7816eb177267a6617df31658f205 +[^*] php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip' +[^**] Running Composer as root is discouraged. Safe for local testing, but avoid in production. If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): @@ -318,20 +318,14 @@ Composer and PHP should already be installed and working. See Phase 1 for enviro |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | | Install Drush (local) | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints*, **, *** | [Drush Docs](https://www.drush.org/latest/install/) | -<<<<<<< HEAD | Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | | -======= -| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | Rerun install or check PHP/Composer compatibility**** | [Drush Troubleshooting](https://www.drush.org/latest/install/#troubleshooting) | ->>>>>>> 7c581d6828bd7816eb177267a6617df31658f205 -| Optional Global Install| Make Drush available system-wide | Download `drush.phar`, then run: - `chmod +x drush.phar` and `mv drush.phar /usr/local/bin/drush` - `drush --version` | `Drush version 11.5.1` from global path | Recheck permissions or path if not executable | [Drush `.phar` Install](https://github.com/drush-ops/drush/releases) | - -* Confirm `composer.json` is writable and not locked by another process. -** Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). -*** If you see a memory error, try: +--- + +[^*] Confirm `composer.json` is writable and not locked by another process. +[^**] Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). +[^***] If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1`. -**** If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. +[^****] If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. **Post-Install Validation** (Phase 3) @@ -351,6 +345,7 @@ Once your project structure is in place and Drush is installed, you can launch t |-------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/my_drupal_site/web` | Drupal installer page loads | Confirm PHP server is running, and `web/` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | | CLI-based install | Install Drupal via Drush | `vendor/bin/drush site:install` | Site installed with default config | Confirm database access, Drush version, and PHP compatibility | [Drush Site Install](https://www.drush.org/latest/commands/site-install/) | +--- > Using the PHP built-in server, run: > ``` @@ -380,12 +375,14 @@ Apache is assumed to be installed and running. This section focuses on enabling #### Line-by-Line Walkthrough -**1. Enable `mod_rewrite`** +**Enable `mod_rewrite`** Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: +``` sudo a2enmod rewrite sudo systemctl restart apache2 +``` This activates `mod_rewrite` and restarts Apache to apply the change. @@ -422,7 +419,9 @@ This maps `drupal.local` to your local machine: Run the MySQL hardening script to remove insecure defaults and set a root password: +``` sudo mysql_secure_installation +``` This interactive tool lets you: @@ -455,11 +454,15 @@ For local development, SSL is optional. For public sites it is essential. - Ensure the `/web/site/default` directory is writable by the web server during installation: +``` sudo chown -R www-data:www-data web/sites/default +``` - After installation, lock down permissions: +``` sudo chmod 444 web/sites/default/settings.php +``` - Drupal relies on `.htaccess` for security rules like: @@ -477,23 +480,23 @@ If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is s - **`.htaccess`** rules active and enforced - **SSL configured** (if public-facing) ---- - ## Contributor-Safe Notes: Composer-First Workflow -- Legacy Bridging for Users Coming From Drupal 8 +**Legacy Bridging for Users Coming From Drupal 8** Drupal 11.x expects Composer-managed workflow. Composer is now the official and recommended method for managing Drupal core, contributed modules, and dependencies. Contributors familiar with manual installs or `.tar.gz` packages from Drupal 8 may encounter unexpected behavior. This guide assumes a Composer-first setup to ensure compatibility with modern module management and dependency resolution. -- Avoiding brittle Installs and Opaque Errors +**Avoiding brittle Installs and Opaque Errors** Composer tracks dependencies explicitly, reducing the risk of missing extensions or mismatched versions. Manual installs often fail silently or introduce hard-to-trace errors. Using `composer create-project` ensures a reproducible, contributor-safe environment. -- Encouraging use of Drush for Command-Line Efficiency +**Encouraging use of Drush for Command-Line Efficiency** Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. Run Drush from you project directory: +``` ./vendor/bin/drush/status +``` If you see errors about missing Symfony classes or auto-loading failures, double-check that: @@ -503,7 +506,9 @@ If you see errors about missing Symfony classes or auto-loading failures, double To confirm you're in the right place, look for: +``` ls +``` This should list: composer.json, vendor/, web/ @@ -511,7 +516,7 @@ This should list: composer.json, vendor/, web/ For official Drush installation guidance, see [Drush on Drupal.org](https://www.drupal.org/docs/develop/development-tools/drush). -You can find additional information on [Drupal's Composer guide](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) for deeper context. +You can find additional information in [Drupal's Composer guide](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) for deeper context. ## Conclusion: What Comes Next From 07e322cd454914e10d239592599308025941848b Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Thu, 2 Oct 2025 12:59:27 -0700 Subject: [PATCH 27/46] Refactored footnotes and table formatting for Hugo/Vale compatibility --- .../index.md | 52 +++++++++++-------- 1 file changed, 29 insertions(+), 23 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index c0a4b66db34..d21aaad0b85 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -288,15 +288,13 @@ This guide uses the command-line method for consistency, automation, and contrib | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2-` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -<<<<<<< HEAD -| Required Extensions | Confirm required PHP modules | See command below* | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | -| Composer Health Check | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings** | [Composer Docs](https://getcomposer.org/doc/) | +| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | +| Required Extensions[^exts] | Confirm required PHP modules | See command below | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Composer Health Check[^root] | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | ---- -[^*] php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip' -[^**] Running Composer as root is discouraged. Safe for local testing, but avoid in production. +[^exts]: Run `php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip'` to confirm required extensions. +[^root]: Running Composer as root is discouraged. Safe for local testing, but avoid in production. If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): @@ -316,16 +314,18 @@ Composer and PHP should already be installed and working. See Phase 1 for enviro | **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | -| Install Drush (local) | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints*, **, *** | [Drush Docs](https://www.drush.org/latest/install/) | -| Validate Drush | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility**** | | ---- +| Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | +| Install Drush (local)[^drush-install] | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints | [Drush Docs](https://www.drush.org/latest/install/) | +| Validate Drush[^drush-validate] | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility | [Drush Usage Guide](https://www.drush.org/latest/usage/) | -[^*] Confirm `composer.json` is writable and not locked by another process. -[^**] Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). -[^***] If you see a memory error, try: -`COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1`. -[^****] If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. +[^drush-install]: +- Confirm `composer.json` is writable and not locked by another process. +- Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). +- If you see a memory error, try: + `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1` + +[^drush-validate]: +If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. **Post-Install Validation** (Phase 3) @@ -492,25 +492,31 @@ Composer tracks dependencies explicitly, reducing the risk of missing extensions **Encouraging use of Drush for Command-Line Efficiency** -Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory. Run Drush from you project directory: +Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory.Check Drush status: ``` ./vendor/bin/drush/status ``` -If you see errors about missing Symfony classes or auto-loading failures, double-check that: +If you get errors like missing "Symfony" classes or auto-load failures, check that you're in the correct project folder containing: + +``` + `composer.json`, `vendor/`, and `web/` +``` - - You're inside the correct project folder (with `composer.json`, `vendor/`, and `web/`). - - Drush is installed locally--not globally or in `/root/vendor`. - - You're not running Drush from outside the project root. +- Drush is installed locally--not globally in `vendor/`. +- You're running Drush from the project root--not from a parent or nested directory. -To confirm you're in the right place, look for: +To confirm you're in the right directory, run: ``` ls ``` -This should list: composer.json, vendor/, web/ +Expected output: +``` + composer.json, vendor/, web/ +``` ### Contributor-Safe References From 6c4a71ea082bcadaca4799bfc021fb180cf85a6c Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Thu, 2 Oct 2025 14:34:18 -0700 Subject: [PATCH 28/46] Fix .vale.ini config and restructured footnotes for Hugo compatibility --- .../index.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index d21aaad0b85..6a822a9c790 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -158,7 +158,7 @@ directory layout details, see [Drupal.org's Directory Structure guide](https://w composer create-project drupal/recommended-project:11.1.8 my-drupal-site ``` --Change to your project folder (remove the angle brackets (<>) and use your actual folder name): +- Change to your project folder (remove the angle brackets (<>) and use your actual folder name): ``` cd my-drupal-site @@ -284,17 +284,17 @@ You can abstract sensitive credentials using `.env` files or environment-specifi This guide uses the command-line method for consistency, automation, and contributor safety (leveraging Drush 11.x for CLI-based installation, matching Drupal 11.1.8). -**Environment Validation**(Phase 1) +**Environment Validation** (Phase 1) | **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions[^exts] | Confirm required PHP modules | See command below | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | -| Composer Health Check[^root] | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings | [Composer Docs](https://getcomposer.org/doc/) | +| Required Extensions (see exts below) | Confirm required PHP modules | see (exts) command below | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Composer Health Check see (root) below | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings | [Composer Docs](https://getcomposer.org/doc/) | | Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | -[^exts]: Run `php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip'` to confirm required extensions. -[^root]: Running Composer as root is discouraged. Safe for local testing, but avoid in production. +(exts): Run `php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip'` to confirm required extensions. +(root): Running Composer as root is discouraged. Safe for local testing, but avoid in production. If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): @@ -315,16 +315,16 @@ Composer and PHP should already be installed and working. See Phase 1 for enviro | **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | |------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| | Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | -| Install Drush (local)[^drush-install] | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints | [Drush Docs](https://www.drush.org/latest/install/) | -| Validate Drush[^drush-validate] | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility | [Drush Usage Guide](https://www.drush.org/latest/usage/) | +| Install Drush (local) see (drush-install) below | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints | [Drush Docs](https://www.drush.org/latest/install/) | +| Validate Drush see (drush-validate) below | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility | [Drush Usage Guide](https://www.drush.org/latest/usage/) | -[^drush-install]: +(drush-install): - Confirm `composer.json` is writable and not locked by another process. - Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). - If you see a memory error, try: `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1` -[^drush-validate]: +(drush-validate): If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. **Post-Install Validation** (Phase 3) From de616cceebf9fd8dcb98cc3b01f127e571874c13 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Thu, 2 Oct 2025 14:37:24 -0700 Subject: [PATCH 29/46] Fix .vale.ini config and restructured footnotes for Hugo compatibility --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 921353fd4f7..d782e5358ff 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,4 +1,5 @@ StylesPath = ci/vale/styles +Vocab = vocab # The minimum alert level to display (suggestion, warning, or error). # @@ -21,7 +22,6 @@ WordTemplate = \s(?:%s)\s # To add another style, just add it to the `StylesPath` and update the setting # below (e.g., `BasedOnStyles = Linode, AnotherStyle`). BasedOnStyles = Linode -Vocab = vocab # Exclude `{{< file >}}`, `{{< file-excerpt >}}`, `{{< output >}}`, # and `{{< highlight ... >}}`. From e96e8619f0f3473454944d13305da215bc27f504 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Thu, 2 Oct 2025 14:51:39 -0700 Subject: [PATCH 30/46] Fix .vale.ini config and restructured footnotes for Hugo compatibility and used placeholder for my drupal site --- .../index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 6a822a9c790..9f8ca82315d 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -213,7 +213,7 @@ If you skip this step and Drupal can't write to the file, the installer will fai ### Create the Files Directory -Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root (`my_drupal_site`) run: +Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root ({{< placeholder "my_drupal_site" >}}) run: mkdir -p web/sites/default/files chmod 755 web/sites/default/files @@ -343,7 +343,7 @@ Once your project structure is in place and Drush is installed, you can launch t | **Method** | **Purpose** | **Action / Command** | **Expected Result** | **If Output Differs** | 🔗 **Further Info** | |-------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/my_drupal_site/web` | Drupal installer page loads | Confirm PHP server is running, and `web/` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | +| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/{{< placeholder "my_drupal_site" >}}/web` | Drupal installer page loads | Confirm PHP server is running, and `web/` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | | CLI-based install | Install Drupal via Drush | `vendor/bin/drush site:install` | Site installed with default config | Confirm database access, Drush version, and PHP compatibility | [Drush Site Install](https://www.drush.org/latest/commands/site-install/) | --- From b941e31b86b54e0b61d6379140f53e12fc498bb5 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Fri, 3 Oct 2025 17:13:41 -0700 Subject: [PATCH 31/46] Update index.md Fully reorganized content to flow in the order it happens. Fixed several formatting issues. --- .../index.md | 555 +++++++++++------- 1 file changed, 334 insertions(+), 221 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 9f8ca82315d..37d6dd2acac 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -15,7 +15,9 @@ Drupal is a flexible content management system (CMS) designed for structured con ## Before You Begin -This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. Specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer after verifying system prerequisites. +This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. Specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer after verifying system prerequisites. + +**Coming from Drupal 8 or new to Composer-based workflows?** See [Contributor-Safe Notes](#contributor-safe-notes) for context on modern Drupal workflows and what's changed since earlier versions. ## System Prerequisites @@ -30,132 +32,184 @@ This guide is based on a tested configuration that ensures Drupal 11 installs cl This configuration was verified to support structured content management, contributor workflows, and integration with Akamai’s caching and security layers. -## Environment Setup: Preparing to Install Drupal +### Configure the Web Server for Drupal -This section outlines the steps used to verify system components, establish the file structure, and prepare the database--everything Drupal requires prior to installation. +Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. -### Infrastructure Verification +#### Summary Table -Confirm that required components are correctly installed and active to prevent silent failures during setup. +| **Step** | **Purpose** | **Command / Config** | +|---------------------------|----------------------------------------------|--------------------------------------------------------------------------------------| +| Enable `mod_rewrite` | Support clean URLs | `sudo a2enmod rewrite`
`sudo systemctl restart apache2` | +| Set `AllowOverride All` | Allow `.htaccess` overrides | Edit Apache config file (`000-default.conf` or `drupal.conf`) and set:
`AllowOverride All` inside the `` block for your `/web` folder | +| Reload Apache | Apply config changes | `sudo systemctl reload apache2` | +| Optional: Virtual Host | Use custom domain for local dev | Define `` block pointing to `/web` folder in `drupal.conf` | +| Update `/etc/hosts` | Map custom domain to localhost | Add: `127.0.0.1 drupal.local` | +| Enable site config | Activate virtual host | `sudo a2ensite drupal.conf`
`sudo systemctl reload apache2` | +--- -#### Check PHP Version and Extensions +#### Line-by-Line Walkthrough -Use the following commands to check what PHP extensions are available: +**Enable `mod_rewrite`** - php -v - php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' +Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: -If any required PHP extensions are missing, install them with: +``` + sudo a2enmod rewrite + sudo systemctl restart apache2 +``` - sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache +This activates `mod_rewrite` and restarts Apache to apply the change. -Following installation, restart Apache or Nginx to activate the new extensions. +Success: No error output and Apache restarts cleanly. - sudo systemctl restart apache2 +If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is already configured for clean URLs. -Verify they're active: +**Set AllowOverride All** - php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' +Edit your Apache configuration file (typically `/etc/apache2/sites-available/000-default.conf` or a custom `drupal.conf`). Locate or add the `` block for your Drupal web root and ensure it includes: -Each one should now be listed. +``` + + AllowOverride All + +``` -#### Check Composer +This allows Drupal's `.htaccess` file to apply security rules and URL rewrites. +After editing, reload Apache: -If checking for Composer installation yields a `composer` not found error, you can install it with: +``` +sudo systemctl reload apache2 +``` - sudo apt update && sudo apt install composer +If the reload command fails or changes don't apply, see the [Troubleshooting](#troubleshooting) section for Apache configuration issues. -To verify installation: +*Optional: Set Up a Virtual Host* - composer --version +For local development using a custom domain (e.g., `drupal.local`): -You should see output like `Composer version 2.7.0` or higher. +1. Create or edit `/etc/apache2/sites-available/drupal.conf`: -If the command fails, see [Composer Installation - Manual Download](https://getcomposer.org/doc/00-intro.md#manual-installation) for fallback steps. +``` + + ServerName drupal.local + DocumentRoot /var/www/html/my-drupal-site/web + + + AllowOverride All + Require all granted + + + ErrorLog ${APACHE_LOG_DIR}/drupal-error.log + CustomLog ${APACHE_LOG_DIR}/drupal-access.log combined + +``` -#### Verify the Web Server +2. Add an entry to `/etc/hosts`: -Before proceeding, make sure your web server has permission to interact with the Drupal environment. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), using: +``` + 127.0.0.1 drupal.local +``` - sudo chown -R www-data:www-data web +This maps `drupal.local` to your local machine. -This step prevents permission errors during runtime and ensures that Drupal can safely generate files, manage uploads, and interact with modules. +3. Enable the site configuration: +``` +sudo a2ensite drupal.conf +sudo systemctl reload apache2 +``` -{{< note >}} -If you're using Nginx or a different web server, replace `www-data` with your actual server user (e.g., `nginx`, `apache`, or a custom service account). -{{< /note >}} +This guide uses Drush 11.x to install Drupal 11.1.8 via the command line. The CLI method ensures consistent results and avoids exposing database credentials in the browser during installation. -To confirm ownership was updated, run this from the parent directory of `web`: +### Environment Validation (Phase 1) - ls -ld web +| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | +|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | +| Required Extensions (see exts below) | Confirm required PHP modules | see **(exts)** command below | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | +| Composer Health Check see **(root)** below | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings | [Composer Docs](https://getcomposer.org/doc/) | +| Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | -This confirms the ownership and permissions of the `web` directory: +**(exts)**: Run `php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip'` to confirm required extensions. - drwxr-xr-x 7 www-data www-data 4096 Sep 16 22:28 web +**(root)**: Running Composer as root is discouraged. Safe for local testing, but avoid in production. -This means: +If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): -- `www-data` owns the directory -- `www-data` is also the group -- The permissions are `drwxr-xr-x` (read/write/execute for owner, read/execute for group and others.) +{{< note >}} +During installation, you may see a prompt like: -To verify ownership of individual files, run: +`Do you want to continue?[Y/n]` - ls -l path/to/your/file (e.g., 'ls -l web/index.php') +This is a standard confirmation step. Type `Y` and press Enter to proceed. (If using a different package manager or install method, the prompt may vary slightly--but the intent is the same: confirm you want to install the listed components.) +{{< /note >}} -This shows the file's owner and group. +#### Infrastructure Verification -{{< note >}} -If ownership is incorrect, rerun: +This section outlines the steps used to verify system components, establish the file structure, and prepare the database--everything Drupal requires prior to installation. - sudo chown -R www-data:www-data web +#### Check PHP Version and Extensions -And replace `www-data` with your actual web server user if different. -{{< /note >}} +Use the following commands to check what PHP extensions are available: -#### Drupal Project Presence + php -v + php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' + +If any required PHP extensions are missing, install them with: +``` + sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache +``` +Following installation, restart Apache or Nginx to activate the new extensions. +``` + sudo systemctl restart apache2 +``` +Verify they're active: +``` + php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' +``` +Each one should now be listed. -To confirm the project was initialized correctly, verify the presence of key files and directories: +[TROUBLESHOOTING NOTE] This section could benefit from troubleshooting links if PHP extensions fail to install or if the grep command returns no results. - ls composer.json - ls web/index.php - ls -d vendor/ +#### Check Composer -{{< note >}} -If any of these files are missing, Drupal has not been initialized. See the Initialize the Drupal Application Environment section to set up the project using Composer. -{{< /note >}} +If checking for Composer installation yields a `composer` not found error, you can install it with: -Contributor-Safe Tips + sudo apt update && sudo apt install composer -- Be sure to consider mentioning file permissions if they are relevant to your environment (e.g., `chmod`, `chown`). -- If `vendor/` is missing but `composer.json` is present, run: - `composer install` - - This installs required dependencies and generates the `vendor/` directory. - - If file permissions are relevant to your environment (e.g., restrictive file creation settings or shared hosting), verify ownership and access using `chmod` and `chown`. +To verify installation: -If at this point all checks pass the infrastructure is ready for Drupal initialization and configuration. + composer --version -## Create Project Structure +You should see output like `Composer version 2.7.0` or higher. +If the command fails, see [Composer Installation - Manual Download](https://getcomposer.org/doc/00-intro.md#manual-installation) for fallback steps. + +### Installation (Phase2) + +Install the Drupal codebase using Composer. This sets up the recommended starter template and project structure. + +Composer and PHP must be working to proceed. To confirm this, complete Environment Validation (Phase 1). + +#### Create Project Structure Creating the project structure sets up Drupal for modular development and secure deployment. This step separates application logic from public content, making updates easier to manage and reducing security risks. -After running the `composer create-project` command below, your environment should include the core Drupal files and folder structure: +After running the composer create-project command below, your environment should include the core Drupal files and folder structure: -- `composer.json` -- `web/index.php` -- `vendor/` +composer.json +web/index.php +vendor/ -These files confirm that setup succeeded, prepare optional configuration scaffolding, and get the application ready for site installation. *This guide was validated using Drupal 11.1.8 as noted earlier.* +These files confirm that setup succeeded, prepare optional configuration scaffolding, and get the application ready for site installation. This guide was validated using Drupal 11.1.8 as noted earlier. -### Create the Drupal Project Structure +**Create the Drupal Project Structure** -- Run the install command to generate the Drupal 11.1.8 structure. Replace `my-drupal-site` with your desired folder name. For directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). -directory layout details, see [Drupal.org's Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure). +Run the install command to generate the Drupal 11.1.8 structure. Replace {{< placeholder "my_drupal_site" >}} with your desired folder name. For directory layout details, see Drupal.org's [Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) ``` - composer create-project drupal/recommended-project:11.1.8 my-drupal-site + composer create-project drupal/recommended-project:11.1.8 {{< placeholder "my_drupal_site" >}} ``` - Change to your project folder (remove the angle brackets (<>) and use your actual folder name): @@ -164,77 +218,147 @@ directory layout details, see [Drupal.org's Directory Structure guide](https://w cd my-drupal-site ``` -- Inside the newly created project folder, confirm the environment after installation: +#### Install Drush -``` - ls composer.json - ls -ld web/index.php - ls -ld vendor/ -``` - - `composer.json` confirms the metadata file exists - - `web/index.php` confirms the application entry point - - `vendor/` confirming that the `vendor/` directory was created. +Add Drush to your project via Composer: ``` - ls -ld web/index.php +composer require drush/drush:11.5.1 ``` - Response: `web/index.php` confirms the application entry point file exists. +Drush will be installed in `vendor/bin/`. + +**Validate Drush Installation** + +Confirm Drush is working: ``` - ls -ld vendor/ +vendor/bin/drush --version ``` - Response:`vendor/` confirming that the `vendor/` directory was created. +Expected output: `Drush version 11.5.1` or similar. -If any of these are missing or return errors, installation may have failed or been interrupted. For troubleshooting see [Installing Drupal - Getting Started Guide](https://www.drupal.org/docs/getting-started/installing-drupal). +If you encounter errors, see the [Troubleshooting](#troubleshooting) section. -**Following Composer Initialization** (using the recommended Drupal starter template, which places core files like `index.php`, `update.php`, and `.htaccess` in their correct locations), confirm your environment against the **Drupal Site Setup checklist**: +**Troubleshooting Notes:** -- Copy the default settings file. +*(drush-install)*: +- Confirm `composer.json` is writable and not locked by another process. +- Make sure your PHP version meets Drush's minimum requirement (PHP 8.1+ for Drush 11.x). +- If you see a memory error, try: ``` - cp web/sites/default/default.settings.php web/sites/default/settings.php +COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1 ``` +*(drush-validate)*: If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. + + +#### Copy the Default Settings File + This creates the active configuration file that Drupal reads and writes to during installation and runtime. -### Set File Permissions +``` +cp web/sites/default/default.settings.php web/sites/default/settings.php +``` + +#### Set File Permissions -This is for `settings.php` (allows the owner to read/write, group and others to read, and the web server to access it during installation). Make sure you are in the Drupal project root folder and then run: +Before running the Drupal installer, you need to make settings.php writable so Drupal can configure it during installation. Make sure you are in the Drupal project root folder and then run: ``` - chmod 644 web/sites/default/settings.php +chmod 644 web/sites/default/settings.php ``` - *Optional: If you're on a shared host or strict environment, you may need to tighten permissions in the `settings.php` file to `640` or even `600`.* +This sets permissions to allow the owner to read/write and the web server to access the file during installation. -If you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. Running `chmod 644` now avoids this. +*Optional: If you're on a shared host or strict environment, you may need to tighten permissions after installation to 640 or even 600.* -### Create the Files Directory +If you skip this step and Drupal can't write to the file, the installer will fail with a permissions error. + +#### Create the Files Directory Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root ({{< placeholder "my_drupal_site" >}}) run: +``` mkdir -p web/sites/default/files chmod 755 web/sites/default/files +``` To verify that it worked, run: +``` ls -ld web/sites/default/files +``` The `chmod` allows owner and group read, write, and execute permissions and others read and execute rights. For stricter environments you can adjust ownership with: +``` chown -R www-data web/sites/default/files +``` Use your actual web server for `www-data`. A writable `files` directory allows Drupal to store uploads (i.e., images or enabled modules) or generate cached assets so you don't see any errors. -### Prepare the database. + +[TROUBLESHOOTING NOTE] - The file permissions sections could benefit from troubleshooting entries for permission denied errors. + +#### Verify the Web Server + +Before proceeding, make sure your web server has permission to interact with the Drupal environment. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), using: + +``` + sudo chown -R www-data:www-data web +``` + +This step prevents permission errors during runtime and ensures that Drupal can safely generate files, manage uploads, and interact with modules. + +{{< note >}} +If you're using Nginx or a different web server, replace `www-data` with your actual server user (e.g., `nginx`, `apache`, or a custom service account). +{{< /note >}} + +To confirm ownership was updated, run this from the parent directory of `web`: + +``` + ls -ld web +``` + +This confirms the ownership and permissions of the `web` directory: + + drwxr-xr-x 7 www-data www-data 4096 Sep 16 22:28 web + +This means: + +- `www-data` owns the directory +- `www-data` is also the group +- The permissions are `drwxr-xr-x` (read/write/execute for owner, read/execute for group and others.) + +To verify ownership of individual files, run: + +``` + ls -l path/to/your/file (for example: `ls -l web/index.php`) +``` + +This shows the file's owner and group. + +{{< note >}} +If ownership is incorrect, rerun: + +``` + sudo chown -R www-data:www-data web +``` + +And replace `www-data` with your actual web server user if different. +{{< /note >}} + +[TROUBLESHOOTING NOTE] - Could add troubleshooting for permission denied errors when running chown command. + +#### Prepare the Database Before installing Drupal, follow the official guide to create a database and user: [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). 1. Once complete, confirm access with a contributor-safe check: - ```command + ``` mysql -u drupal_user -p -h localhost drupal_db ``` @@ -242,15 +366,16 @@ Before installing Drupal, follow the official guide to create a database and use 1. Confirm that your database uses `utf8mb4` encoding: - ```command + ``` SHOW CREATE DATABASE drupal_db; ``` -1. Look for `CHARACTER SET utf8mb4`. Your credentials match what you'll enter in `settings.php`: +1. Look for `CHARACTER SET utf8mb4` in the output. If it's missing, you may need to recreate the database with the correct encoding or convert it. - ```file - $databases['default']['default'] = [ +1. Your database credentials should match what you'll enter in `settings.php`: + ``` + $databases['default']['default'] = [ 'driver' => 'mysql', 'database' => 'drupal_db', 'username' => 'drupal_user', @@ -259,7 +384,7 @@ Before installing Drupal, follow the official guide to create a database and use ]; ``` - This configuration is located in `sites/default/settings.php`. +This configuration is located in `sites/default/settings.php`. 1. During setup you may need to temporarily relax file permissions: @@ -267,7 +392,7 @@ Before installing Drupal, follow the official guide to create a database and use chmod 664 sites/default/settings.php ``` -Common Errors and Fixes +**Common Errors and Fixes** | Error Message | Likely Cause | Fix | Resource | |-------------------------------|-------------------------------|------------------------------------------|--------------------------------------------------------------------------| @@ -276,121 +401,79 @@ Common Errors and Fixes | Driver not found | Incorrect or missing driver | Use `'driver' => 'mysql'` for MariaDB | [Drupal.org: Database API Overview](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration) | | Warning: count() during install | Misconfigured array structure | Ensure `$databases` array is properly nested | [Stack Overflow](https://stackoverflow.com/questions/71596215/how-can-i-set-up-my-drupal-database-correctely) (yes, there is a typo in that title s/b correctly). | -Optional: Environment Variables +*Optional: Environment Variables* You can abstract sensitive credentials using `.env` files or environment-specific config, see [Drupal.org's environment config practices](https://www.drupal.org/project/env). -### CLI-based Installation +#### Launch the Installer -This guide uses the command-line method for consistency, automation, and contributor safety (leveraging Drush 11.x for CLI-based installation, matching Drupal 11.1.8). +Once your project structure is in place and Drush is installed, you can launch the Drupal installer using either a browser or CLI. -**Environment Validation** (Phase 1) +**Method 1: Browser-Based Installation** -| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | -|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| PHP Version | Ensure PHP 8.1+ is installed | `php -v` | `PHP 8.1.2` or higher | Upgrade PHP or switch environments | [PHP Docs](https://www.php.net/manual/en/) | -| Required Extensions (see exts below) | Confirm required PHP modules | see (exts) command below | All listed extensions appear | Install missing modules via `apt`, `dnf`, or `brew` | [Drupal Requirements](https://www.drupal.org/docs/system-requirements) | -| Composer Health Check see (root) below | Validate Composer setup | `composer diagnose` | All checks return `OK` or `WARNING` (non-blocking) | Type `yes` if prompted about root; note any warnings | [Composer Docs](https://getcomposer.org/doc/) | -| Composer Version | Ensure Composer 2.x is installed | `composer --version` | `Composer version 2.x.x` | Upgrade Composer if version is < 2 | [Composer Install Guide](https://getcomposer.org/download/) | +Using the PHP built-in server, run: -(exts): Run `php -m | grep -E 'pdo|mbstring|xml|json|ctype|tokenizer|curl|openssl|gd|dom|simplexml|zip'` to confirm required extensions. -(root): Running Composer as root is discouraged. Safe for local testing, but avoid in production. +``` +php -S localhost:8888 -t web +``` -If you experience silent failures during verification and need to install missing components (e.g., PHP extensions): +Then visit `http://localhost:8888` in your browser. The Drupal installer page should load. -{{< note >}} -During installation, you may see a prompt like: +If the installer page is blank or throws errors: +- Check PHP version and extensions (`pdo`, `gd`, `mbstring`) +- Confirm file permissions in the `web` folder +- Ensure `index.php` exists in `web` -`Do you want to continue?[Y/n]` - -This is a standard confirmation step. Type `Y` and press Enter to proceed. (If using a different package manager or install method, the prompt may vary slightly--but the intent is the same: confirm you want to install the listed components.) -{{< /note >}} +**Method 2: CLI-Based Installation (Recommended)** -**Installation** (Phase 2) +Install Drupal via Drush: -Install the Drupal codebase using Composer. This sets up the recommended starter template and project structure. - -Composer and PHP should already be installed and working. See Phase 1 for environment prep. - -| **Step** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | -|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Create Project | Set up Drupal starter template | `composer` | `mysite` folder created with Drupal structure | Rename or delete existing folder before retry | [Drupal Install Guide](https://www.drupal.org/docs/installing-drupal) | -| Install Drush (local) see (drush-install) below | Add Drush to project via Composer | `composer require drush/drush:11.5.1` | Drush installed in `vendor/bin/` | If error, check Composer version or package constraints | [Drush Docs](https://www.drush.org/latest/install/) | -| Validate Drush see (drush-validate) below | Confirm Drush is working | `vendor/bin/drush --version` | `Drush version 11.5.1` or similar | If error, rerun install or check PHP/Composer compatibility | [Drush Usage Guide](https://www.drush.org/latest/usage/) | +``` +vendor/bin/drush site:install +``` -(drush-install): -- Confirm `composer.json` is writable and not locked by another process. -- Make sure your PHP version meets Drush’s minimum requirement (PHP 8.1+ for Drush 11.x). -- If you see a memory error, try: - `COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1` +The site will be installed with default configuration. -(drush-validate): -If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. +If the installation fails: +- Confirm database access and credentials +- Verify Drush version compatibility +- Check PHP version meets requirements -**Post-Install Validation** (Phase 3) +### Post-Install Validation (Phase 3) After installation, confirm that setup completed successfully and is complete and ready for configuration. -| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | -|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Success Confirmation | Validate install completion | *Review terminal output* | “Project created successfully” or similar message | If error shown, rerun with `-vvv` for verbose output | [Composer Troubleshooting](https://getcomposer.org/doc/articles/troubleshooting.md) | -| Folder Structure | Confirm expected files exist | `ls mysite` | `composer.json`, `web/`, `vendor/`, etc. | If missing, check install logs or rerun install | [Drupal File Structure](https://www.drupal.org/docs/develop/structure-of-a-drupal-codebase) | -| Optional Cleanup | Remove message plugin (optional) | `composer` | Plugin removed, no errors | Check Composer version or plugin dependencies | [Project Message Plugin](https://www.drupal.org/project/core_project_message) | - -### Launch the installer. +#### Verify Project Structure -Once your project structure is in place and Drush is installed, you can launch the Drupal installer using either a browser or CLI. This confirms that your environment is functional and ready for site configuration. +Confirm the project was initialized correctly: -| **Method** | **Purpose** | **Action / Command** | **Expected Result** | **If Output Differs** | 🔗 **Further Info** | -|-------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| -| Browser-based install | Begin visual site setup via browser | Visit `http://localhost:8888` or `http://localhost/{{< placeholder "my_drupal_site" >}}/web` | Drupal installer page loads | Confirm PHP server is running, and `web/` folder exists | [Drupal Installer Guide](https://www.drupal.org/docs/installing-drupal) | -| CLI-based install | Install Drupal via Drush | `vendor/bin/drush site:install` | Site installed with default config | Confirm database access, Drush version, and PHP compatibility | [Drush Site Install](https://www.drush.org/latest/commands/site-install/) | ---- +``` +ls composer.json +ls -ld web/index.php +ls -ld vendor/ +``` -> Using the PHP built-in server, run: -> ``` -> php -S localhost:8888 -t web -> ``` +Expected results: -> If the installer page is blank or throws errors: -> - Check PHP version and extensions (`pdo`, `gd`, `mbstring`) -> - Confirm file permissions in the `web` folder -> - Ensure `index.php` exists in `web` +- composer.json confirms the metadata file exists +- web/index.php confirms the application entry point exists +- vendor/ confirms dependencies were installed -### Configure the Web Server for Drupal +If any of these files are missing or return errors, installation may have failed or been interrupted. For troubleshooting see Installing Drupal - [Getting Started Guide](https://www.drupal.org/docs/getting-started). -Apache is assumed to be installed and running. This section focuses on enabling the modules and configuration settings Drupal relies on for clean URLs, secure access, and flexible routing. +If any are missing: -#### Summary Table +If `vendor/` is missing but `composer.json` exists, run: `composer install` +If all are missing, the project wasn't created. Return to Phase 2. -| **Step** | **Purpose** | **Command / Config** | -|---------------------------|----------------------------------------------|--------------------------------------------------------------------------------------| -| Enable `mod_rewrite` | Support clean URLs | `sudo a2enmod rewrite`
`sudo systemctl restart apache2` | -| Set `AllowOverride All` | Allow `.htaccess` overrides | Edit Apache config file (`000-default.conf` or `drupal.conf`) and set:
`AllowOverride All` inside the `` block for your `/web` folder | -| Reload Apache | Apply config changes | `sudo systemctl reload apache2` | -| Optional: Virtual Host | Use custom domain for local dev | Define `` block pointing to `/web` folder in `drupal.conf` | -| Update `/etc/hosts` | Map custom domain to localhost | Add: `127.0.0.1 drupal.local` | -| Enable site config | Activate virtual host | `sudo a2ensite drupal.conf`
`sudo systemctl reload apache2` | +| **Check** | **Purpose** | **Command** | **Expected Output** | **If Output Differs** | 🔗 **Further Info** | +|------------------------|------------------------------------------|------------------------------------------------------------|--------------------------------------------------------|------------------------------------------------------------|---------------------| +| Success Confirmation | Validate install completion | *Review terminal output* | “Project created successfully” or similar message | If error shown, rerun with `-vvv` for verbose output | [Composer Troubleshooting](https://getcomposer.org/doc/articles/troubleshooting.md) | +| Folder Structure | Confirm expected files exist | `ls mysite` | `composer.json`, `web/`, `vendor/`, etc. | If missing, check install logs or rerun install | [Drupal File Structure](https://www.drupal.org/docs/develop/structure-of-a-drupal-codebase) | +| Optional Cleanup | Remove message plugin (optional) | `composer` | Plugin removed, no errors | Check Composer version or plugin dependencies | [Project Message Plugin](https://www.drupal.org/project/core_project_message) | --- -#### Line-by-Line Walkthrough - -**Enable `mod_rewrite`** - -Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: - -``` - sudo a2enmod rewrite - sudo systemctl restart apache2 -``` - -This activates `mod_rewrite` and restarts Apache to apply the change. - -Success: No error output and Apache restarts cleanly. - -If you see an error like `Module rewrite already enabled`, it's safe to proceed--Apache is already configured for clean URLs. - -## Local Testing Setup +#### Local Testing Setup Before continuing, confirm that your local environment is serving the Drupal site correctly. This section helps validate Apache, PHP, and file permissions using a browser-based test. @@ -411,13 +494,27 @@ Before continuing, confirm that your local environment is serving the Drupal sit This maps `drupal.local` to your local machine: +``` 127.0.0.1 drupal.local +``` -## Security and Optimization +**2. Test in browser** -1. Harden the MySQL Installation +Visit `http://drupal.local` in your browser. The Drupal site should load. + +**3. Troubleshoot blank pae or errors** + +If the page i blank or shows errors: + +- Check file permissions in the `web` folder. +- Verify Apache configuration (ensure `AllowOverride All` is set). +- Confirm PHP is running: `php -v`. -Run the MySQL hardening script to remove insecure defaults and set a root password: +## Security and Optimization (Post-Install) + +After your Drupal site is installed and validate, take these steps to harden security and optimize perfomance. + +1. Harden the MySQL Installation ``` sudo mysql_secure_installation @@ -435,36 +532,22 @@ This interactive tool lets you: These steps help protect your Drupal site from unauthorized access and are strongly recommended for production environments. {{< /note >}} -2. Enable SSL (Optional) - -If deploying Drupal in a production or public-facing environment, configure SSL to encrypt traffic: +2. Lock Down File Permissions -- Use *Let's Encrypt* or a self-signed certificate. -- Update your Apache virtual host to include: - - - SSLEngine on - SSLCertificateFile /path/to/cert.pem - SSLCertificateKeyFile /path/to/key.pem - - -For local development, SSL is optional. For public sites it is essential. - -3. File permissions and `.htaccess` notes - -- Ensure the `/web/site/default` directory is writable by the web server during installation: +Ensure the `web/sites/default` directory is writable by the web server during installation: ``` sudo chown -R www-data:www-data web/sites/default ``` - -- After installation, lock down permissions: +After installation, lock down permissions: ``` - sudo chmod 444 web/sites/default/settings.php + sudo dhmod 444 web/sites/default/settings.php ``` -- Drupal relies on `.htaccess` for security rules like: +3. Verify .htaccess Rules + +Drupal relies on `.htaccess` for security rules like: - Preventing access to sensitive files - Blocking directory listings @@ -472,15 +555,33 @@ For local development, SSL is optional. For public sites it is essential. {{< note >}} If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is set in your Apache config. -{{< /note >}} -4. Security Checklist - - **Database hardened** using `mysql_secure_installation` - - **File permission** set for install and post-install - - **`.htaccess`** rules active and enforced - - **SSL configured** (if public-facing) +4. Enable SSL (Optional) -## Contributor-Safe Notes: Composer-First Workflow +If deploying Drupal in a production or public-facing environment, configure SSL to encrypt traffic: + +- Use Let's Encrypt or a self-signed certificate. +- Update your Apache virtual host to include: + + ``` + + SSLEngine on + SSLCertificateFile /path/to/cert.pem + SSLCertificateKeyFile /path/to/key.pem + ``` + +For local development, SSL is optional. For public sites it is essential. + +5. Security Checklist + +- Database hardened using mysql_secure_installation +- File permissions set for install and post-install +- `.htaccess` rules active and enforced +- SSL configured (if public-facing) + +## Next Steps and Resources + +### Contributor-Safe Notes: Composer-First Workflow **Legacy Bridging for Users Coming From Drupal 8** @@ -524,7 +625,7 @@ For official Drush installation guidance, see [Drush on Drupal.org](https://www. You can find additional information in [Drupal's Composer guide](https://www.drupal.org/docs/develop/using-composer/using-composer-with-drupal) for deeper context. -## Conclusion: What Comes Next +### Conclusion: What Comes Next Your Drupal environment is now structured, validated, and ready for customization. From here, you can begin shaping your site: @@ -533,3 +634,15 @@ Your Drupal environment is now structured, validated, and ready for customizatio - Get into theme development: create or install themes to control layout and styling. Browse the [Drupal Themes Directory](https://www.drupal.org/project/project_theme) to see what's possible. To see inspiring real-world [Drupal Websites](https://htmlburger.com/blog/drupal-websites-examples/) explore how others have extended and styled their sites. + +## Troubleshooting + +Apache reload/restart + +| **Issue** | **Possible Cause** | **Resolution** | +|-----------|-------------------|----------------| +| Apache reload fails with "control process exited with error code" | Syntax error in config file | [Apache Configuration Test](https://httpd.apache.org/docs/2.4/configuring.html) | +| Permission denied on reload | Not running with sudo | [Apache Service Management](https://httpd.apache.org/docs/2.4/stopping.html) | +| "Unit apache2.service not loaded" | Apache not installed or started | [Apache Installation Guide](https://httpd.apache.org/docs/2.4/install.html) | +| No error but .htaccess rules don't apply | Wrong config file edited or incorrect Directory path | [Apache Virtual Host Documentation](https://httpd.apache.org/docs/2.4/vhosts/) | +--- From 4084aaa6834341463c242c34f1fce9bc62a2af53 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 3 Oct 2025 18:08:07 -0700 Subject: [PATCH 32/46] Add Vale vocabulary for technical terms --- ci/vale/styles/vocab/accept.txt | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 ci/vale/styles/vocab/accept.txt diff --git a/ci/vale/styles/vocab/accept.txt b/ci/vale/styles/vocab/accept.txt new file mode 100644 index 00000000000..c8c56177710 --- /dev/null +++ b/ci/vale/styles/vocab/accept.txt @@ -0,0 +1,13 @@ +mbstring +opcache +ctype +simplexml +ensite +enmod +Hoober +utf8mb4 +MariaDB +Drush +Drupal +drupal +Akamai \ No newline at end of file From 8ad0396a380645c701b96f8abfaec18b0f93f0b0 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 3 Oct 2025 18:17:18 -0700 Subject: [PATCH 33/46] Fix trailing whitespace and spelling errors --- .../index.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 37d6dd2acac..5df8cba84e4 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -15,7 +15,7 @@ Drupal is a flexible content management system (CMS) designed for structured con ## Before You Begin -This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. Specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer after verifying system prerequisites. +This guide uses Drupal 11.1.8 to avoid known packaging issues in newer releases. Specifically a syntax error in `drupal/core-recipe-unpack` introduced in 11.2.x (see [Drupal issue #3536487](https://www.drupal.org/project/drupal/issues/3536487)). You'll install the stable version later using Composer after verifying system prerequisites. **Coming from Drupal 8 or new to Composer-based workflows?** See [Contributor-Safe Notes](#contributor-safe-notes) for context on modern Drupal workflows and what's changed since earlier versions. @@ -94,12 +94,12 @@ For local development using a custom domain (e.g., `drupal.local`): ServerName drupal.local DocumentRoot /var/www/html/my-drupal-site/web - + AllowOverride All Require all granted - + ErrorLog ${APACHE_LOG_DIR}/drupal-error.log CustomLog ${APACHE_LOG_DIR}/drupal-access.log combined @@ -512,7 +512,7 @@ If the page i blank or shows errors: ## Security and Optimization (Post-Install) -After your Drupal site is installed and validate, take these steps to harden security and optimize perfomance. +After your Drupal site is installed and validate, take these steps to harden security and optimize performance. 1. Harden the MySQL Installation @@ -542,7 +542,7 @@ Ensure the `web/sites/default` directory is writable by the web server during in After installation, lock down permissions: ``` - sudo dhmod 444 web/sites/default/settings.php + sudo chmod 444 web/sites/default/settings.php ``` 3. Verify .htaccess Rules @@ -555,6 +555,7 @@ Drupal relies on `.htaccess` for security rules like: {{< note >}} If `.htaccess` rules aren't being applied, double-check `AllowOverride All` is set in your Apache config. +{{< /note >}} 4. Enable SSL (Optional) @@ -569,7 +570,7 @@ If deploying Drupal in a production or public-facing environment, configure SSL SSLCertificateFile /path/to/cert.pem SSLCertificateKeyFile /path/to/key.pem ``` - + For local development, SSL is optional. For public sites it is essential. 5. Security Checklist From c4f5a6a0c1fd03091b1a38f26a314a0775d6962a Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 3 Oct 2025 18:36:55 -0700 Subject: [PATCH 34/46] Move vocab file to correct Linode styles location --- .vale.ini | 1 - ci/vale/styles/{ => Linode}/vocab/accept.txt | 0 2 files changed, 1 deletion(-) rename ci/vale/styles/{ => Linode}/vocab/accept.txt (100%) diff --git a/.vale.ini b/.vale.ini index d782e5358ff..a854bd93954 100644 --- a/.vale.ini +++ b/.vale.ini @@ -1,5 +1,4 @@ StylesPath = ci/vale/styles -Vocab = vocab # The minimum alert level to display (suggestion, warning, or error). # diff --git a/ci/vale/styles/vocab/accept.txt b/ci/vale/styles/Linode/vocab/accept.txt similarity index 100% rename from ci/vale/styles/vocab/accept.txt rename to ci/vale/styles/Linode/vocab/accept.txt From a6c636295e6c4a48eee76ef4e768682acb68b942 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 3 Oct 2025 18:59:24 -0700 Subject: [PATCH 35/46] Add placeholder to Vale ignore patterns and update vocabulary --- .vale.ini | 1 + ci/vale/styles/Linode/vocab/accept.txt | 4 +++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index a854bd93954..af00c21ba52 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,6 +30,7 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ +(?s) *({{< placeholder .*? >}}), \ (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) diff --git a/ci/vale/styles/Linode/vocab/accept.txt b/ci/vale/styles/Linode/vocab/accept.txt index c8c56177710..d47601981bd 100644 --- a/ci/vale/styles/Linode/vocab/accept.txt +++ b/ci/vale/styles/Linode/vocab/accept.txt @@ -10,4 +10,6 @@ MariaDB Drush Drupal drupal -Akamai \ No newline at end of file +Akamai +exts +SSLEngine \ No newline at end of file From 91775d7136d04b6e029f9593881b2963bed231df Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 3 Oct 2025 19:08:14 -0700 Subject: [PATCH 36/46] Added exts and SSLEngine to vocabulary --- ci/vale/styles/Linode/vocab/accept.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/vale/styles/Linode/vocab/accept.txt b/ci/vale/styles/Linode/vocab/accept.txt index d47601981bd..225a874d7d0 100644 --- a/ci/vale/styles/Linode/vocab/accept.txt +++ b/ci/vale/styles/Linode/vocab/accept.txt @@ -12,4 +12,4 @@ Drupal drupal Akamai exts -SSLEngine \ No newline at end of file +SSLEngine From c57686d18d2f8a1f2b0354de733f4848108619e1 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Mon, 6 Oct 2025 11:23:24 -0700 Subject: [PATCH 37/46] Remove vocab/accept.txt and add terms to dictionary.txt --- ci/vale/dictionary.txt | 8 ++++++++ ci/vale/styles/Linode/vocab/accept.txt | 15 --------------- 2 files changed, 8 insertions(+), 15 deletions(-) delete mode 100644 ci/vale/styles/Linode/vocab/accept.txt diff --git a/ci/vale/dictionary.txt b/ci/vale/dictionary.txt index 5527a912c55..e064c32f082 100644 --- a/ci/vale/dictionary.txt +++ b/ci/vale/dictionary.txt @@ -458,6 +458,7 @@ csv CTAs ctools ctrl +ctype ctx cuda curlie @@ -675,6 +676,8 @@ EMTs ender enduser enix +enmod +ensite entra enum env @@ -718,6 +721,7 @@ exploitability ext2 ext3 ext4 +exts facter facto fail2ban @@ -1475,6 +1479,7 @@ mBlock mbox Mbps MBps +mbstring mbstrings mcrypt mcy @@ -2347,6 +2352,7 @@ sidekiq sievers signup Simula +simplexml singapore sintra siri @@ -2412,6 +2418,7 @@ sshing sshpass ssi ssl +sslengine stackhawk stackscript stackscripts @@ -2743,6 +2750,7 @@ usermod usersor usr ust +utf8mb4 utils UTunnel uuid diff --git a/ci/vale/styles/Linode/vocab/accept.txt b/ci/vale/styles/Linode/vocab/accept.txt deleted file mode 100644 index 225a874d7d0..00000000000 --- a/ci/vale/styles/Linode/vocab/accept.txt +++ /dev/null @@ -1,15 +0,0 @@ -mbstring -opcache -ctype -simplexml -ensite -enmod -Hoober -utf8mb4 -MariaDB -Drush -Drupal -drupal -Akamai -exts -SSLEngine From 7aacde104eb96fd3cfc4d0669390f25843d13c91 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 10:19:53 -0700 Subject: [PATCH 38/46] Add placeholder shortcode to Vale ignore patterns --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index af00c21ba52..3fbcf665690 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,7 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ -(?s) *({{< placeholder .*? >}}), \ +(?s) *({{< placeholder [^]* >}}), \ (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) From d538b6dd5a770a5c8faeea3e2f9580f7065f3687 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 10:44:49 -0700 Subject: [PATCH 39/46] Fixed regex syntax error for placeholder --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 3fbcf665690..f62fb3e73cb 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,7 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ -(?s) *({{< placeholder [^]* >}}), \ +(?s) *({{< placeholder [^>]* >}}), \ (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) From 74eeb2548f7d2318bf0af2ae7e836dd1f1cee64c Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 10:58:39 -0700 Subject: [PATCH 40/46] Update plaeholder pattern to handle whitespace --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index f62fb3e73cb..d614c12cca5 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,7 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ -(?s) *({{< placeholder [^>]* >}}), \ +(?s) *({{<\s*placeholder\s+[^>]+>}}), \ (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) From 488697e99e5c607976457a82e6ba946a28b42973 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 11:16:38 -0700 Subject: [PATCH 41/46] Removed backslash --- .vale.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index d614c12cca5..6725a18d9b9 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,7 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ -(?s) *({{<\s*placeholder\s+[^>]+>}}), \ +(?s) *({{< placeholder .*? >}}) (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) From ec5d3a9155ab4550874798c3c8474121a7469899 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 11:29:29 -0700 Subject: [PATCH 42/46] Removed vale ini changes --- .vale.ini | 1 - 1 file changed, 1 deletion(-) diff --git a/.vale.ini b/.vale.ini index 6725a18d9b9..a854bd93954 100644 --- a/.vale.ini +++ b/.vale.ini @@ -30,7 +30,6 @@ BasedOnStyles = Linode IgnorePatterns = (?s) *({{< output >}}.*?{{< ?/ ?output >}}), \ (?s) *({{< ?file [^>]* ?>}}.*?{{< ?/ ?file ?>}}), \ (?s) *({{< highlight [^>]* ?>}}.*?{{< ?/ ?highlight >}}), \ -(?s) *({{< placeholder .*? >}}) (?s) *({{< image .*? >}}), \ (?s) *({{< content .*? >}}), \ (?s) *({{% content .*? %}}) From c75b39e1aa5bcb7e1d9b89246ba2dca7244cee5c Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 12:38:26 -0700 Subject: [PATCH 43/46] Removed underscores causing Vale problems --- .../index.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 5df8cba84e4..e888e1f2e3c 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -206,10 +206,10 @@ These files confirm that setup succeeded, prepare optional configuration scaffol **Create the Drupal Project Structure** -Run the install command to generate the Drupal 11.1.8 structure. Replace {{< placeholder "my_drupal_site" >}} with your desired folder name. For directory layout details, see Drupal.org's [Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) +Run the install command to generate the Drupal 11.1.8 structure. Replace my-drupal-site with your desired folder name. For directory layout details, see Drupal.org's [Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) ``` - composer create-project drupal/recommended-project:11.1.8 {{< placeholder "my_drupal_site" >}} + composer create-project drupal/recommended-project:11.1.8 my-drupal-site ``` - Change to your project folder (remove the angle brackets (<>) and use your actual folder name): @@ -278,7 +278,7 @@ If you skip this step and Drupal can't write to the file, the installer will fai #### Create the Files Directory -Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root ({{< placeholder "my_drupal_site" >}}) run: +Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root ({{< placeholder "my-drupal-site" >}}) run: ``` mkdir -p web/sites/default/files From 613e2d58502d3712ef17f7a599d9aee190a54fa4 Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 17 Oct 2025 12:55:13 -0700 Subject: [PATCH 44/46] Added formatting --- .../index.md | 111 +++++++++--------- 1 file changed, 55 insertions(+), 56 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index e888e1f2e3c..765cd7c2540 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -54,7 +54,7 @@ Apache is assumed to be installed and running. This section focuses on enabling Drupal uses clean URLs, which depend on Apache’s rewrite module. Enable it with: -``` +```command sudo a2enmod rewrite sudo systemctl restart apache2 ``` @@ -69,7 +69,7 @@ If you see an error like `Module rewrite already enabled`, it's safe to proceed- Edit your Apache configuration file (typically `/etc/apache2/sites-available/000-default.conf` or a custom `drupal.conf`). Locate or add the `` block for your Drupal web root and ensure it includes: -``` +```command AllowOverride All @@ -78,7 +78,7 @@ Edit your Apache configuration file (typically `/etc/apache2/sites-available/000 This allows Drupal's `.htaccess` file to apply security rules and URL rewrites. After editing, reload Apache: -``` +```command sudo systemctl reload apache2 ``` @@ -107,14 +107,14 @@ For local development using a custom domain (e.g., `drupal.local`): 2. Add an entry to `/etc/hosts`: -``` +```command 127.0.0.1 drupal.local ``` This maps `drupal.local` to your local machine. 3. Enable the site configuration: -``` +```command sudo a2ensite drupal.conf sudo systemctl reload apache2 ``` @@ -152,19 +152,20 @@ This section outlines the steps used to verify system components, establish the Use the following commands to check what PHP extensions are available: +```command php -v php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' If any required PHP extensions are missing, install them with: -``` +```command sudo apt install php-gd php-mbstring php-xml php-curl php-zip php-mysql php-opcache ``` Following installation, restart Apache or Nginx to activate the new extensions. -``` +```command sudo systemctl restart apache2 ``` Verify they're active: -``` +```command php -m | grep -E 'gd|mbstring|xml|curl|zip|mysql|pdo_mysql|opcache' ``` Each one should now be listed. @@ -174,12 +175,14 @@ Each one should now be listed. #### Check Composer If checking for Composer installation yields a `composer` not found error, you can install it with: - +```command sudo apt update && sudo apt install composer +``` To verify installation: - +```command composer --version +``` You should see output like `Composer version 2.7.0` or higher. @@ -208,13 +211,13 @@ These files confirm that setup succeeded, prepare optional configuration scaffol Run the install command to generate the Drupal 11.1.8 structure. Replace my-drupal-site with your desired folder name. For directory layout details, see Drupal.org's [Directory Structure guide](https://www.drupal.org/docs/getting-started/understanding-drupal/directory-structure) -``` +```command composer create-project drupal/recommended-project:11.1.8 my-drupal-site ``` - Change to your project folder (remove the angle brackets (<>) and use your actual folder name): -``` +```command cd my-drupal-site ``` @@ -222,8 +225,8 @@ Run the install command to generate the Drupal 11.1.8 structure. Replace my-drup Add Drush to your project via Composer: -``` -composer require drush/drush:11.5.1 +```command + composer require drush/drush:11.5.1 ``` Drush will be installed in `vendor/bin/`. @@ -232,8 +235,8 @@ Drush will be installed in `vendor/bin/`. Confirm Drush is working: -``` -vendor/bin/drush --version +```command + vendor/bin/drush --version ``` Expected output: `Drush version 11.5.1` or similar. @@ -247,8 +250,8 @@ If you encounter errors, see the [Troubleshooting](#troubleshooting) section. - Make sure your PHP version meets Drush's minimum requirement (PHP 8.1+ for Drush 11.x). - If you see a memory error, try: -``` -COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1 +```command + COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1 ``` *(drush-validate)*: If Drush throws a `NotFoundHttpException`, it was likely run outside a valid Drupal project root. Navigate to the directory containing `composer.json` before running Drush commands. See: [Drush Usage Guide](https://www.drush.org/latest/usage/) for valid command contexts. @@ -258,16 +261,16 @@ COMPOSER_MEMORY_LIMIT=-1 composer require drush/drush:11.5.1 This creates the active configuration file that Drupal reads and writes to during installation and runtime. -``` -cp web/sites/default/default.settings.php web/sites/default/settings.php +```command + cp web/sites/default/default.settings.php web/sites/default/settings.php ``` #### Set File Permissions Before running the Drupal installer, you need to make settings.php writable so Drupal can configure it during installation. Make sure you are in the Drupal project root folder and then run: -``` -chmod 644 web/sites/default/settings.php +```command + chmod 644 web/sites/default/settings.php ``` This sets permissions to allow the owner to read/write and the web server to access the file during installation. @@ -280,33 +283,30 @@ If you skip this step and Drupal can't write to the file, the installer will fai Drupal uses a writable `files` directory to store uploaded content, temporary files, and other runtime assets. From your project root ({{< placeholder "my-drupal-site" >}}) run: -``` +```command mkdir -p web/sites/default/files chmod 755 web/sites/default/files ``` To verify that it worked, run: -``` +```command ls -ld web/sites/default/files ``` The `chmod` allows owner and group read, write, and execute permissions and others read and execute rights. For stricter environments you can adjust ownership with: -``` +```command chown -R www-data web/sites/default/files ``` Use your actual web server for `www-data`. A writable `files` directory allows Drupal to store uploads (i.e., images or enabled modules) or generate cached assets so you don't see any errors. - -[TROUBLESHOOTING NOTE] - The file permissions sections could benefit from troubleshooting entries for permission denied errors. - #### Verify the Web Server Before proceeding, make sure your web server has permission to interact with the Drupal environment. Set the `/web` directory and its contents to be owned by `www-data` (or your system’s web server user), using: -``` +```command sudo chown -R www-data:www-data web ``` @@ -318,7 +318,7 @@ If you're using Nginx or a different web server, replace `www-data` with your ac To confirm ownership was updated, run this from the parent directory of `web`: -``` +```command ls -ld web ``` @@ -334,7 +334,7 @@ This means: To verify ownership of individual files, run: -``` +```command ls -l path/to/your/file (for example: `ls -l web/index.php`) ``` @@ -343,7 +343,7 @@ This shows the file's owner and group. {{< note >}} If ownership is incorrect, rerun: -``` +```command sudo chown -R www-data:www-data web ``` @@ -358,23 +358,22 @@ Before installing Drupal, follow the official guide to create a database and use 1. Once complete, confirm access with a contributor-safe check: - ``` +```command mysql -u drupal_user -p -h localhost drupal_db - ``` +``` Replace `drupaluser` and `drubaldb` with your database username and name. You should be able to enter the MariaDB shell without errors. 1. Confirm that your database uses `utf8mb4` encoding: - ``` +```command SHOW CREATE DATABASE drupal_db; - ``` +``` 1. Look for `CHARACTER SET utf8mb4` in the output. If it's missing, you may need to recreate the database with the correct encoding or convert it. 1. Your database credentials should match what you'll enter in `settings.php`: - - ``` +```command $databases['default']['default'] = [ 'driver' => 'mysql', 'database' => 'drupal_db', @@ -382,15 +381,15 @@ Before installing Drupal, follow the official guide to create a database and use 'password' => 'your_secure_password', 'host' => 'localhost', ]; - ``` +``` This configuration is located in `sites/default/settings.php`. 1. During setup you may need to temporarily relax file permissions: - ```command +```command chmod 664 sites/default/settings.php - ``` +``` **Common Errors and Fixes** @@ -413,8 +412,8 @@ Once your project structure is in place and Drush is installed, you can launch t Using the PHP built-in server, run: -``` -php -S localhost:8888 -t web +```command + php -S localhost:8888 -t web ``` Then visit `http://localhost:8888` in your browser. The Drupal installer page should load. @@ -428,8 +427,8 @@ If the installer page is blank or throws errors: Install Drupal via Drush: -``` -vendor/bin/drush site:install +```command + vendor/bin/drush site:install ``` The site will be installed with default configuration. @@ -447,10 +446,10 @@ After installation, confirm that setup completed successfully and is complete an Confirm the project was initialized correctly: -``` -ls composer.json -ls -ld web/index.php -ls -ld vendor/ +```command + ls composer.json + ls -ld web/index.php + ls -ld vendor/ ``` Expected results: @@ -495,7 +494,7 @@ Before continuing, confirm that your local environment is serving the Drupal sit This maps `drupal.local` to your local machine: ``` -127.0.0.1 drupal.local + 127.0.0.1 drupal.local ``` **2. Test in browser** @@ -516,7 +515,7 @@ After your Drupal site is installed and validate, take these steps to harden sec 1. Harden the MySQL Installation -``` +```command sudo mysql_secure_installation ``` @@ -536,12 +535,12 @@ These steps help protect your Drupal site from unauthorized access and are stron Ensure the `web/sites/default` directory is writable by the web server during installation: -``` +```command sudo chown -R www-data:www-data web/sites/default ``` After installation, lock down permissions: -``` +```command sudo chmod 444 web/sites/default/settings.php ``` @@ -595,14 +594,14 @@ Composer tracks dependencies explicitly, reducing the risk of missing extensions **Encouraging use of Drush for Command-Line Efficiency** Drush streamlines tasks like site installation, cache clearing, and module management. Once installed via Composer, it becomes available in the project’s `/vendor/bin` directory.Check Drush status: - +command ``` ./vendor/bin/drush/status ``` If you get errors like missing "Symfony" classes or auto-load failures, check that you're in the correct project folder containing: -``` +```command `composer.json`, `vendor/`, and `web/` ``` @@ -611,7 +610,7 @@ If you get errors like missing "Symfony" classes or auto-load failures, check th To confirm you're in the right directory, run: -``` +```command ls ``` From 511c9581546105b72b0a1da5b3910d4d39a19b06 Mon Sep 17 00:00:00 2001 From: DHBR2 Date: Wed, 22 Oct 2025 11:12:43 -0700 Subject: [PATCH 45/46] Remove troubleshooting notes from Drupal installation guide Removed suggested troubleshooting notes regarding PHP extensions and permission errors. --- .../index.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 765cd7c2540..73f6c928e1f 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -170,8 +170,6 @@ Verify they're active: ``` Each one should now be listed. -[TROUBLESHOOTING NOTE] This section could benefit from troubleshooting links if PHP extensions fail to install or if the grep command returns no results. - #### Check Composer If checking for Composer installation yields a `composer` not found error, you can install it with: @@ -350,8 +348,6 @@ If ownership is incorrect, rerun: And replace `www-data` with your actual web server user if different. {{< /note >}} -[TROUBLESHOOTING NOTE] - Could add troubleshooting for permission denied errors when running chown command. - #### Prepare the Database Before installing Drupal, follow the official guide to create a database and user: [Database Configuration](https://www.drupal.org/docs/drupal-apis/database-api/database-configuration). From 54eafd4c317a1f4c55ab15cb2afdab78b672e0bd Mon Sep 17 00:00:00 2001 From: Dianna Hoober Date: Fri, 24 Oct 2025 10:46:32 -0700 Subject: [PATCH 46/46] Spelling mistakes corrected --- .../index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md index 73f6c928e1f..95395ebaeab 100644 --- a/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md +++ b/docs/guides/websites/cms/drupal/how-to-install-and-configure-drupal-on-ubuntu-22-04/index.md @@ -499,7 +499,7 @@ Visit `http://drupal.local` in your browser. The Drupal site should load. **3. Troubleshoot blank pae or errors** -If the page i blank or shows errors: +If the page is blank or shows errors: - Check file permissions in the `web` folder. - Verify Apache configuration (ensure `AllowOverride All` is set). @@ -507,7 +507,7 @@ If the page i blank or shows errors: ## Security and Optimization (Post-Install) -After your Drupal site is installed and validate, take these steps to harden security and optimize performance. +After your Drupal site is installed and validated, take these steps to harden security and optimize performance. 1. Harden the MySQL Installation