(#5046) Implement DDev

[bryanpizzillo]

This updates the tech stack to use MySQL 8, but also it is a refresh of the dev stack to be easier to use.

Closes #5046

Notes

DB Persistence

The DB contents survive on restart and rebuild.

Addons

With DDev, most add-ons seem to be separate services, OR, maybe better put, what one might think should be installed in the web service might not be done that way, but added as a separate service.

• ddev-selenium-standalone-chrome is a perfect example of this. It is an add-on for installing selenium and chrome, but it actually is a headless chrome browser running in a separate container. This add-on sets up everything for drupal testing. (Kernel, Functional, Functional Javascript, and Nightwatch.
  • This means requests actually hit the web service from another container, which required some slight changes to a js_app_module test.
• There is a lovely addon for cypress, https://github.com/ddev/ddev-cypress
  • but it does not do what we want:
    1. It just mounts the e2e folder into a cypress service, which does not allow for our setup. (plugins and support)
    2. It adds in a separate service/container with preinstalled software, so no cypress-parallel.
  • It does have hints on how to run cypress interactively though...

Mutagen

DDev by default uses mutagen to handle file synchronization. It is supposed to be faster than normal bind mounting. In fact an install took like 4:30 on my M1.
There is a major downside that we need to evaluate: if you switch branches or make other edits when the container is down, upon restart, the files in the container are synchronized back to the host. I can see this cause all kinds of issues.

[bryanpizzillo]

@blairlearn to test:

• Does the old stack run? (Yes, with notes
• Can you XDebug? (Also yes, with notes)

[Copilot]

Pull request overview

Implements a DDEV-based local development stack and updates supporting configuration to align with a MySQL 8 / PHP 8.3 workflow, including Drupal settings integration and updated browser-testing container wiring.

Changes:

• Add DDEV configuration (core config, mounts, hooks, selenium-chrome addon configs, helper command, and web-build customization).
• Adjust Drupal settings layering to load DDEV settings via Acquia Recommended Settings/global includes.
• Update a functional test to tolerate different SIMPLETEST_BASE_URL hosts, and adjust PHPUnit output printer.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
phpunit.xml	Switch PHPUnit result printer implementation.
docroot/sites/settings/global.settings.php	Load settings.ddev.php from a global settings include when running under DDEV.
docroot/sites/default/settings/default.local.settings.php	Refresh local settings template and adjust paths/assertion handling.
docroot/sites/default/settings/default.includes.settings.php	Update guidance/comments and add phpcs:ignore for requires.
docroot/sites/default/settings.php	Add an early return; to prevent DDEV from re-injecting its include; relies on global include instead.
docroot/sites/default/settings.ddev.php	Add DDEV-managed Drupal settings (DB config, logging, mail transport overrides, etc.).
docroot/modules/custom/cgov_js_app_module/tests/src/Functional/JSOnlyAppModulePluginBuildTest.php	Normalize expected config output across varying base URLs.
.ddev/web-build/pre.Dockerfile.certificates	Attempt to install NIH root certs during web image build.
.ddev/docker-compose.selenium-chrome_extras.yaml	DDEV selenium-chrome routing/external link wiring.
.ddev/docker-compose.selenium-chrome.yaml	Add selenium standalone chromium service and link it to web.
.ddev/docker-compose.mounts.yml	Mount host auth files into the web container for npm/composer.
.ddev/config.yaml	Define DDEV project config, hooks, MySQL 8, PHP 8.3, node version, and extra packages.
.ddev/config.selenium-standalone-chrome.yaml	Provide environment variables for Drupal browser testing via selenium container.
.ddev/commands/web/blt	Add a ddev blt helper command.
.ddev/addon-metadata/ddev-selenium-standalone-chrome/manifest.yaml	Track installed DDEV addon metadata.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Typo in comment: "iss." → "is."

Suggested change

	## iss. (For read-only don't follow the npm login steps)
	## is. (For read-only don't follow the npm login steps)

[blairlearn]

On my system, CyLance (antivirus) blocks attempts to install certificates with mkcert.
To work around this:

1. In the .ddev directory, create config.local.yaml. Settings in this file override those in config.yaml.
2. Add the line outer_https_port: "".
   • This prevents ddev from attempting to use HTTPS and port 443.
   • There will still be a warning that mkcert has not been installed.
3. When you run ddev, sites will be available using http:// instead of https://.

[blairlearn]

Does the old stack run?

Yes. With some hacking.

These steps assume you have NOT run any ddev commands.

1. Clone the repo
2. Switch to the ticket/5046-ddev branch (eventually develop)
3. composer cgov-init
4. composer install
5. docker compose -f ./docker/docker-compose.yml up -d
6. docker compose -f ./docker/docker-compose.yml exec web bash
7. blt setup --no-interaction
   • This command will fail.
   • Continue to the next step.
8. Add these lines at the top of docroot/sites/default/settings/default.local.settings.php

   $db_name = '${drupal.db.database}';
   
   if (isset($_acsf_site_name)) {
     $db_name .= '_' . $_acsf_site_name;
   }
   
   /**
    * Database configuration.
    */
   $databases = array(
     'default' =>
     array(
       'default' =>
       array(
         'database' => $db_name,
         'username' => '${drupal.db.username}',
         'password' => '${drupal.db.password}',
         'host' => '${drupal.db.host}',
         'port' => '${drupal.db.port}',
         'namespace' => 'Drupal\\Core\\Database\\Driver\\mysql',
         'driver' => 'mysql',
         'prefix' => '',
       ),
     ),
   );

9. blt cgov:reinstall --no-interaction

[blairlearn]

Can you XDebug?

Yes; with notes.

The obvious: Change your .vscode/launch.json to use:

            "port": 9003,
            "pathMappings": {
              "/var/www/html/docroot": "${workspaceRoot}/docroot",
              "/var/www/html/vendor": "${workspaceRoot}/vendor"
            }

The non-obvious: Our docker/web/build/php-conf/xdebug.ini is ignored. In fact, ddev supplies its own copies of everything in the mods-available directory, so that should be removed from the Dockerfile as well as the docker/web/build/php-conf directory.