# DDEV Docs

> Do local website development on your computer or in the cloud with DDEV.

# Getting Started

# Get Started with DDEV

[DDEV](<https://github.com/ddev/ddev>) is an open source tool for launching local web development environments in minutes. It supports PHP and Node.js.

These environments can be extended, version controlled, and shared, so you can take advantage of a Docker workflow without Docker experience or bespoke configuration. Projects can be changed, powered down, or removed as easily as they’re started.

## System Requirements

### macOS

Runs natively on ARM64 (Apple Silicon) and AMD64 machines.

- macOS Sonoma (14) or higher. This is primarily driven by the available Docker providers.
- RAM: 8GB
- Storage: 256GB
- [OrbStack](<https://orbstack.dev/>) or [Lima](<https://github.com/lima-vm/lima>) or [Docker Desktop](<https://www.docker.com/products/docker-desktop/>) or [Rancher Desktop](<https://rancherdesktop.io/>) or [Colima](<https://github.com/abiosoft/colima>)

**Next steps:**

*You’ll need a Docker provider on your system before you can install DDEV.*

1. Install Docker with [recommended settings](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#macos>).
2. Install [DDEV for macOS](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#macos>).
3. Launch your [first project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) and start developing. 🚀

### Windows WSL2

- RAM: 8GB
- Storage: 256GB
- [Docker CE](<https://docs.docker.com/engine/install/ubuntu/>) inside WSL2 or [Docker Desktop](<https://www.docker.com/products/docker-desktop/>) on the Windows side.
- Ubuntu or an Ubuntu-derived distro is recommended, though others may work fine

**Next steps:**

*You’ll need a Docker provider on your system before you can install DDEV.*

1. Install [DDEV for Windows](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#windows>).
2. Launch your [first project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) and start developing. 🚀

**WSL2 in Mirrored Mode**

If you’re using Windows WSL2 with [“Mirrored” networking mode](<https://learn.microsoft.com/en-us/windows/wsl/networking#mirrored-mode-networking>), enable the experimental `hostAddressLoopback=true` setting.

You can do this using the “WSL Settings” app:

- Networking \> Networking mode: set to *Mirrored*
- Networking \> Host Address Loopback: turn *On*.

Or by creating/editing the file at `C:\Users\<you>\.wslconfig`:

```
[wsl2]
networkingMode=Mirrored

[experimental]
hostAddressLoopback=true
```

**WSL2 in VirtioProxy Mode (Experimental)**

If you’re using Windows WSL2 with [“VirtioProxy” networking mode](<https://learn.microsoft.com/en-us/windows/wsl/networking>), DDEV supports this mode experimentally. Set your `C:\Users\<you>\.wslconfig`:

```
[wsl2]
networkingMode=VirtioProxy
```

Then restart WSL with `wsl --shutdown`.

> [!WARNING]
>
> **VirtioProxy mode is experimental with significant limitations**
>
> VirtioProxy mode has known limitations and is poorly documented by Microsoft. On some machines it works well; on others, the WSL2 distro has no internet access at all, making tools like Composer and npm non-functional.
>
> When it does work: the WSL2 distro and Docker containers cannot make outgoing connections to the Windows host, so a Windows-side IDE cannot receive Xdebug connections. Run your IDE inside WSL2 via WSLg instead:
>
> ```
> ddev config global --xdebug-ide-location=wsl2
> ```
>
> Accessing DDEV sites from a Windows browser works normally. Run `ddev utility xdebug-diagnose` to check your Xdebug configuration.
>
> If VirtioProxy is required due to a corporate VPN (such as Netskope), see [Special Network Configurations](<https://ddev.github.io/ddev/en/stable/users/usage/networking/#wsl2-virtioproxy-mode-netskope-and-similar-vpns>). Users who can choose their setup may prefer the [Traditional Windows](<#traditional-windows>) approach instead.

### Traditional Windows

- Any recent edition of Windows Home or Windows Pro.
- RAM: 8GB
- Storage: 256GB
- [Docker Desktop](<https://www.docker.com/products/docker-desktop/>) using the WSL2 backend

**Next steps:**

*You’ll need a Docker provider on your system before you can install DDEV.*

1. Install Docker with [recommended settings](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#windows>).
2. Install [DDEV for Windows](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#windows>).
3. Launch your [first project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) and start developing. 🚀

### Linux

Most distros and most versions work fine, on both AMD64 and ARM64 architectures.

- RAM: 8GB
- Storage: 256GB

**Next steps:**

*You’ll need a Docker provider on your system before you can install DDEV.*

1. Install Docker with [recommended settings](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#linux>).
2. Install [DDEV for Linux](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#linux>).
3. Launch your [first project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) and start developing. 🚀

### GitHub Codespaces

With [GitHub Codespaces](<https://github.com/features/codespaces>) you don’t install anything; you only need a browser and an internet connection.

**Next steps:**

1. Install DDEV within [GitHub Codespaces](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#github-codespaces>).
2. Launch your [first project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) and start developing. 🚀

# Configuring Browsers for DDEV projects

**Most DDEV users can ignore this page. The standard instructions in DDEV Installation do everything that is needed. These instructions are for unusual browsers or OS environments.**

## Firefox on Windows

Modern Firefox on Windows supports using the Windows system certificate store automatically. If you use Firefox on Windows and see certificate errors on DDEV sites, go to Firefox Settings → Privacy &amp; Security and check **“Allow Firefox to automatically trust third-party root certificates you install”**. This is often all that is needed.

If that setting is already enabled and Firefox still shows errors, import the CA manually (see below).

DDEV generates SSL certificates to enable local projects to use the HTTPS protocol. It uses a custom root Certificate Authority (CA) to generate SSL certificates for `*.ddev.site` domains.

However, since this is a custom CA, web browsers display an ERR\_CERT\_AUTHORITY\_INVALID warning when trying to access a local DDEV site over HTTPS.

To eliminate this warning, you can install the custom root CA into your browser.

For default browsers, this works automatically using the [mkcert](<https://github.com/FiloSottile/mkcert>) utility.

For custom browsers (such as Firefox Developer Edition, Vivaldi, etc.), manual steps may be required.

> [!TIP]
>
> **Want to learn more about HTTPS in DDEV?**
>
> See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) for more information on DDEV hostname resolution.

## Adding the DDEV Root Certificate Authority to Browsers

The steps to install the root CA depend on the browser, but they generally follow this process:

1. Use `mkcert -CAROOT` to locate the directory with the generated root certificate. Inside, you should find a `rootCA.pem` file. If it’s missing, run `mkcert -install` command.
2. Open your browser and navigate to the preferences or settings.
3. Find the Certificate Manager, typically located in the “Security” section of the preferences.
4. Click the “Manage Certificates” button (labeled “View Certificates” in older Firefox versions).
5. Go to the “Authorities” tab.
6. Click the “Import” button to add a custom authority certificate.
7. Import the `rootCA.pem` file to install the root certificate authority.

> [!NOTE]
>
> **Still having issues?**
>
> Check out [this specific mkcert thread](<https://github.com/FiloSottile/mkcert/issues/370>) for additional troubleshooting.

## Xcode iOS Simulator

Testing any DDEV site via Safari through the iOS simulator will lead to TLS errors due to the mkcert CA certificate not being trusted. You will need to manually install the CA certificate into the simulator device.

1. Run `mkcert -CAROOT` and open that directory in Finder. On macOS, the default location is typically `~/Library/Application Support/mkcert`.
2. Drag the `rootCA.pem` file from that directory onto the iOS simulator session.
3. In the iOS simulator, open **Settings** and install the downloaded certificate profile. Depending on the iOS version, use **Profile Downloaded** or go to **General \> VPN &amp; Device Management** (or **Profiles**) and install the mkcert/root CA profile.
4. After the profile is installed, go to **Settings \> General \> About \> Certificate Trust Settings** and enable full trust for the mkcert certificate.

This should now allow valid TLS connections to any DDEV domain/site.

# DDEV Installation

Once you’ve [installed a Docker provider](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>), you’re ready to install DDEV!

## macOS

### Homebrew

[Homebrew](<https://brew.sh/>) is the easiest and most reliable way to install and [upgrade](<https://ddev.github.io/ddev/en/stable/users/install/ddev-upgrade/index.md>) DDEV:

```
# Install DDEV
brew install ddev/ddev/ddev

# One-time initialization of mkcert
mkcert -install
```

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

### Install Script

The [install script](<https://github.com/ddev/ddev/blob/main/scripts/install_ddev.sh>) is another option. It downloads, verifies, and sets up the `ddev` executable:

```
# Download and run the install script
curl -fsSL https://ddev.com/install.sh | bash
```

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

**Do you still have an old version after installing or upgrading?**

If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

**Need a specific version?**

Use the `-s` argument to specify a specific stable or prerelease version:

```
# Download and run the script to install DDEV v1.24.10
curl -fsSL https://ddev.com/install.sh | bash -s v1.24.10
```

## Linux

### Debian/Ubuntu

DDEV’s Debian and RPM packages work with `apt` and `yum` repositories and most variants that use them, including Windows WSL2:

```
# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Add DDEV’s GPG key to your keyring
sudo apt-get update && sudo apt-get install -y curl
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://packages.ddev.com/public/gpg.key | sudo tee /etc/apt/keyrings/ddev.asc > /dev/null
sudo chmod a+r /etc/apt/keyrings/ddev.asc

# Remove old repository files if present
sudo rm -f /etc/apt/keyrings/ddev.gpg /etc/apt/sources.list.d/ddev.list

# Add DDEV releases to your package repository
printf "Types: deb\nURIs: https://packages.ddev.com/public/deb/ubuntu\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/ddev.asc\n" | sudo tee /etc/apt/sources.list.d/ddev.sources >/dev/null

# Update package information and install DDEV
sudo apt-get update && sudo apt-get install -y ddev

# One-time initialization of mkcert
mkcert -install
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> Create a script file, then run it:
>
> ```
> cat > /tmp/install-ddev.sh << 'SCRIPT'
> #!/usr/bin/env bash
> set -euo pipefail
> sudo true
> sudo apt-get update && sudo apt-get install -y curl
> sudo install -m 0755 -d /etc/apt/keyrings
> curl -fsSL https://packages.ddev.com/public/gpg.key | sudo tee /etc/apt/keyrings/ddev.asc > /dev/null
> sudo chmod a+r /etc/apt/keyrings/ddev.asc
> sudo rm -f /etc/apt/keyrings/ddev.gpg /etc/apt/sources.list.d/ddev.list
> printf "Types: deb\nURIs: https://packages.ddev.com/public/deb/ubuntu\nSuites: stable\nComponents: main\nSigned-By: /etc/apt/keyrings/ddev.asc\n" | sudo tee /etc/apt/sources.list.d/ddev.sources >/dev/null
> sudo apt-get update && sudo apt-get install -y ddev
> mkcert -install
> SCRIPT
> ```
>
> Review the script, then run it: `bash /tmp/install-ddev.sh`

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

**Do you still have an old version after installing or upgrading?**

If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

**Need to remove a previously-installed variant?**

If you previously used DDEV’s [install script](<#install-script>), you can remove that version:

```
sudo rm -f /usr/local/bin/ddev /usr/local/bin/mkcert
```

If you previously [installed DDEV with Homebrew](<#homebrew>), you can run `brew unlink ddev` to get rid of the Homebrew version.

### Fedora, Red Hat, etc.

```
# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Add DDEV releases to your package repository
echo '[ddev]
name=ddev
baseurl=https://packages.ddev.com/public/rpm/any-distro/any-version/$basearch
gpgkey=https://packages.ddev.com/public/gpg.key
gpgcheck=1
repo_gpgcheck=1
enabled=1' | sed 's/^ \+//' | sudo tee /etc/yum.repos.d/ddev.repo >/dev/null

# Install DDEV
sudo dnf install -y --refresh ddev

# One-time initialization of mkcert
mkcert -install
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> Create a script file, then run it:
>
> ```
> cat > /tmp/install-ddev.sh << 'SCRIPT'
> #!/usr/bin/env bash
> set -euo pipefail
> sudo true
> printf "[ddev]\nname=ddev\nbaseurl=https://packages.ddev.com/public/rpm/any-distro/any-version/\$basearch\ngpgkey=https://packages.ddev.com/public/gpg.key\ngpgcheck=1\nrepo_gpgcheck=1\nenabled=1\n" | sudo tee /etc/yum.repos.d/ddev.repo >/dev/null
> sudo dnf install -y --refresh ddev
> mkcert -install
> SCRIPT
> ```
>
> Review the script, then run it: `bash /tmp/install-ddev.sh`

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

### Arch Linux

We maintain the [ddev-bin](<https://aur.archlinux.org/packages/ddev-bin/>) package in AUR for Arch-based systems including Arch Linux, EndeavourOS and Manjaro. Install with `yay` or your AUR tool of choice.

```
# Install DDEV
yay -S ddev-bin

# One-time initialization of mkcert
mkcert -install
```

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

### Homebrew

```
# Install DDEV using Homebrew
brew install ddev/ddev/ddev

# One-time initialization of mkcert
mkcert -install
```

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

### Install Script

The [install script](<https://github.com/ddev/ddev/blob/main/scripts/install_ddev.sh>) is another option. It downloads, verifies, and sets up the `ddev` executable:

```
# Download and run the install script
curl -fsSL https://ddev.com/install.sh | bash
```

For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

**Need a specific version?**

Use the `-s` argument to specify a specific stable or prerelease version:

```
# Download and run the script to install DDEV v1.24.10
curl -fsSL https://ddev.com/install.sh | bash -s v1.24.10
```

**Do you still have an old version after installing or upgrading?**

If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` executable must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

## Windows

DDEV on Windows uses an installer that supports three configurations — pick the one that fits you:

| Mode | Best for | Requires |
| --- | --- | --- |
| **Docker CE inside WSL2** (recommended) | Most users, best performance | WSL2 |
| **Docker Desktop / Rancher Desktop with WSL2** | Already have Docker Desktop or Rancher Desktop installed | WSL2 + Docker Desktop or Rancher Desktop |
| **Traditional Windows** | PowerShell/Git Bash workflow | Docker Desktop or Rancher Desktop (no separate WSL2 distro needed) |

### Step 1: Install WSL2

In PowerShell, run:

```
# Install WSL2; reboot if prompted, then continue:
wsl --install --no-distribution

# Update WSL2 if previously installed:
wsl --update
```

Create an Ubuntu or other Debian-based WSL2 distro (skip if you’re using Traditional Windows). Ubuntu is recommended:

```
# You'll be asked to set a username and password for the distro:
wsl --install Ubuntu-26.04 --name DDEV
```

> [!TIP]
>
> **"DDEV" is just a suggested name — use any name you like.**

> [!TIP]
>
> **Other Debian-based distros also work**
>
> The DDEV installer supports Ubuntu and Debian and has been tested with Kali Linux and eLxr. If you prefer one of those, substitute its name, for example `wsl --install Debian --name DDEV`.

Verify the “DDEV” distro is set as default:

```
> wsl -l -v
  NAME                   STATE           VERSION
* DDEV                   Stopped         2
```

### Step 2: Install DDEV

Download the installer — make sure to pick the right architecture:

- **AMD64 (x86-64)**: Most traditional Windows PCs (Intel/AMD processors)
- **ARM64**: Windows on ARM devices like Microsoft Surface Pro X, Surface Pro 9 (5G), or other ARM-based Windows devices

> [!TIP]
>
> **Check your system architecture**
>
> Not sure which architecture you have? Open PowerShell and run: `$env:PROCESSOR_ARCHITECTURE`. It will show `AMD64` or `ARM64`. Alternatively, in WSL2/Ubuntu run `uname -m` which shows `x86_64` for AMD64 or `aarch64` for ARM64.

Run the installer and select your mode. For WSL2 modes, the installer will display all detected Debian-based WSL2 distros (Ubuntu, Debian, Kali, eLxr, etc.) and prompt you to select one. The installer will automatically configure DDEV for your chosen Docker provider. If you run the wrong installer for your architecture, it will detect the mismatch and direct you to download the correct one.

> [!TIP]
>
> **Install using WinGet**
>
> [WinGet](<https://learn.microsoft.com/en-us/windows/package-manager/winget/>) can download and launch the installer interactively:
>
> ```
> winget install --interactive DDEV
> ```
>
> For silent/automated installation with specific options, use `--override` to pass installer flags:
>
> ```
> # WSL2 with Docker CE and specified distro, silently
> winget install DDEV --silent --override '/docker-ce /distro=DDEV'
> ```
>
> If WinGet picks up an old version (which can happen when DDEV was previously installed with the Windows installer), uninstall all versions first:
>
> ```
> winget uninstall DDEV --all-versions
> ```

> [!TIP]
>
> **Install using Chocolatey (Traditional Windows AMD64 only)**
>
> [Chocolatey](<https://chocolatey.org/>) has had DDEV support for years and remains an option for Traditional Windows on AMD64:
>
> ```
> choco install ddev
> ```

> [!TIP]
>
> **Installer in Silent Mode**
>
> The Windows installer supports silent mode for automated installations and testing:
>
> ```
> # WSL2 with Docker CE and specified distro
> ./ddev_windows_amd64_installer.exe /S /docker-ce /distro=DDEV
>
> # WSL2 with Docker Desktop and specified distro
> ./ddev_windows_amd64_installer.exe /S /docker-desktop /distro=Ubuntu
>
> # Traditional Windows (requires Docker Desktop/Rancher Desktop)
> ./ddev_windows_installer.exe /S /traditional
>
> # Get help with all options
> ./ddev_windows_amd64_installer.exe /help
> ```
>
> The `/S` flag makes the installation completely silent. Use `/distro=<name>` to specify your WSL2 distribution name (required for WSL2 options).

**Manual Installation**

### Windows Manual Installation

If you prefer to install DDEV manually on WSL2, these techniques can be used to install on a non-Ubuntu distro, and can be adapted for Yum-based or ArchLinux-based distros as well:

1. In PowerShell, run `mkcert.exe -install` and follow the prompt to install the Certificate Authority.
2. In PowerShell, run `$env:CAROOT="$(mkcert -CAROOT)"; setx CAROOT $env:CAROOT; If ($Env:WSLENV -notlike "*CAROOT/up:*") { $env:WSLENV="CAROOT/up:$env:WSLENV"; setx WSLENV $Env:WSLENV }`. This will set WSL2 to use the Certificate Authority installed on the Windows side, so your Windows-side browser can trust it.
3. In PowerShell, run `wsl --update` to make sure you have a current WSL version.
4. In PowerShell, run `wsl --install <distro-type> --name DDEV`, for example `wsl --install Debian --name DDEV`. This will install the WSL2 distro for you. (The name “DDEV” is just a suggestion; you can use any name you like.)
5. **Docker CE:** Follow the instructions in the [Linux install section here](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#linux>) to install Docker CE and DDEV. In addition, `sudo apt-get install -y docker-ce ddev ddev-wsl2` (or the equivalent `dnf` or other package manager commands).
6. **Docker Desktop for Windows (if used, this is not preferred):**

   - Download and install the installer from [docker.com](<https://www.docker.com/products/docker-desktop/>). Choose the WSL2-based configuration. Start Docker Desktop. It may prompt you to log out and log in again, or reboot.
   - Go to Docker Desktop’s *Settings* → *Resources* → *WSL integration* → *enable integration for your distro*. Now `docker` commands will be available from within your WSL2 distro.
7. Double-check your distro: `echo $CAROOT` should show something like `/mnt/c/Users/<you>/AppData/Local/mkcert`
8. Check that Docker is working inside Ubuntu (or your distro) by running `docker ps` in the distro.
9. Open the WSL2 terminal, for example `Debian` from the Windows start menu.
10. In WSL2, run `mkcert -install`.
11. Note that the older manual [PowerShell script](<https://github.com/ddev/ddev/blob/main/scripts/install_ddev_wsl2_docker_inside.ps1>) may be instructional if you’re setting up a non-Ubuntu distro. It has been replaced by the Windows installer, but could be adapted for other distros. Pass `-Distro <name>` when running it.

> [!NOTE]
>
> **Path to certificates**
>
> If you get the prompt `Installing to the system store is not yet supported on this Linux`, you may need to add `/usr/sbin` to the `$PATH` so that `/usr/sbin/update-ca-certificates` can be found.

### Step 3: Start working in WSL2

*(Skip if using Traditional Windows.)*

Open your distro from the Start menu (or run `wsl` in PowerShell) to get a Linux terminal. Run all `ddev` commands here — never in PowerShell or Git Bash.

**Store your [projects](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) inside WSL2** (e.g. `/home/<username>/projects`), not on `C:\` drive (`/mnt/c` in WSL2) — faster and avoids permission issues.

From Windows Explorer: **Linux → DDEV → home → \[username\]**.

> [!NOTE]
>
> **Custom hostnames**
>
> Custom hostnames with a non-default [TLD](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#project_tld>) (non `ddev.site`) are managed via the Windows hosts file at `C:\Windows\System32\drivers\etc\hosts`, not within WSL2.

**What if my browser (especially Firefox) doesn’t trust `https` URLs?**

DDEV uses [mkcert](<https://github.com/FiloSottile/mkcert>) to generate a local certificate authority (CA), and `mkcert -install` registers it with most browsers automatically. Firefox and some other browsers manage their own certificate stores and require a manual import.

To diagnose certificate trust issues, run `ddev utility tls-diagnose`.

To manually import the CA: run `mkcert.exe -CAROOT` to find the directory containing `rootCA.pem`, then import that file via your browser’s certificate manager (usually under Security settings → View Certificates → Authorities → Import).

See [Configuring Browsers](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>) for full details.

## GitHub Codespaces

You can use DDEV in remote [GitHub Codespaces](<https://github.com/features/codespaces>) without having to run Docker locally; you only need a browser and an internet connection.

Start by creating a `.devcontainer/devcontainer.json` file in your GitHub repository:

```
{
    "image": "mcr.microsoft.com/devcontainers/base:debian-12",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {
            "version": "latest"
        },
        "ghcr.io/ddev/ddev/install-ddev:latest": {}
    }
}
```

The `install-ddev` feature automatically configures the environment and sets up DDEV for use in Codespaces.

Launch your repository in Codespaces:

![Screenshot of codespace create dialog in a repository on GitHub](<https://ddev.github.io/ddev/en/images/codespaces-launch.png>)

![Screenshot of codespace create dialog in a repository on GitHub](<https://ddev.github.io/ddev/en/images/codespaces-setting-up.png>)

DDEV is now available within your new codespace instance:

![](<https://ddev.github.io/ddev/en/images/codespaces-hello-screen.png>)

Run `ddev config` to [start a new blank project](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) - or [install a CMS](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>).

Run `ddev start` if there is already a configured DDEV project in your repository.

**Troubleshooting**:

If there are errors after restarting a codespace, use `ddev restart` or `ddev poweroff`.

You can also use the commands

- “Codespaces: Rebuild container”
- “Codespaces: Full rebuild container” (Beware: database will be deleted)

via the [Visual Studio Code Command Palette](<https://docs.github.com/en/enterprise-cloud@latest/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces>):

- <kbd>⌘</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on a Mac
- <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on Windows/Linux
- from the Application Menu, click View \> Command Palette (Firefox)

If you need DDEV-specific assistance or have further questions, see [support](<https://ddev.github.io/ddev/en/stable/users/support/index.md>).

Your updated `devcontainer.json` file may differ depending on your project, but you should have `install-ddev` in the `features` section.

> [!NOTE]
>
> **Normal Linux installation also works**
>
> You can also install DDEV as if it were on any normal [Linux installation](<#linux>).

### Docker integration

DDEV in Codespaces relies on [`docker-in-docker`](<https://github.com/devcontainers/features>), which must be added manually to the features when using `"mcr.microsoft.com/devcontainers/base:debian-12"`. See [`devcontainers/features`](<https://github.com/devcontainers/features>) for general support and issues regarding Docker-support.

### DDEV’s router is not used

Since Codespaces handles all the routing, the internal DDEV router will not be used on Codespaces. Therefore config settings like [`web_extra_exposed_ports`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_extra_exposed_ports>) will have no effect.

You can expose ports via the `ports` setting, which is usually not recommended if you work locally due to port conflicts. But you can load these additional Docker compose files only when Codespaces is detected. See [Defining Additional Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#docker-composeyaml-examples>) for more information.

```
services:
    web:
        ports:
            - "5174:5174"
```

### Default environment variables

Codespace instances already provide some [default environment values](<https://docs.github.com/en/codespaces/developing-in-codespaces/default-environment-variables-for-your-codespace>). You can inherit and inject them in your `.ddev/config.yaml`:

```
web_environment:
    - CODESPACES
    - CODESPACE_NAME
    - GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN
```

### Advanced usage via devcontainer.json

A lot more customization is possible via the [`devcontainer.json`-configuration](<https://containers.dev/implementors/json_reference/>). You can install Visual Studio Code extensions by default or run commands automatically.

#### postCreateCommand

The [`postCreateCommand`](<https://containers.dev/implementors/json_reference/>) lets you run commands automatically when a new codespace is launched. DDEV commands are available here.

The event is triggered on: fresh creation, rebuilds and full rebuilds. `ddev poweroff` is used in this example to avoid errors on rebuilds since some Docker containers are kept.

You usually want to use a separate bash script to do this, as docker [might not yet be available when the command starts to run](<https://github.com/devcontainers/features/issues/780>).

```
{
    "image": "mcr.microsoft.com/devcontainers/base:debian-12",
    "features": {
        "ghcr.io/devcontainers/features/docker-in-docker:2": {
            "version": "latest"
        },
        "ghcr.io/ddev/ddev/install-ddev:latest": {}
    },
    "portsAttributes": {
        "3306": {
            "label": "database"
        },
        "8027": {
            "label": "mailpit"
        },
        "8080": {
            "label": "web http"
        },
        "8443": {
            "label": "web https"
        }
    },
    "postCreateCommand": "bash .devcontainer/setup_project.sh"
}
```

The `install-ddev` feature provides its own `postCreateCommand` to verify DDEV installation. User-provided commands run after the feature’s commands.

```
#!/usr/bin/env bash
set -ex

wait_for_docker() {
  while true; do
    docker ps > /dev/null 2>&1 && break
    sleep 1
  done
  echo "Docker is ready."
}

wait_for_docker

# download images beforehand, optional
ddev utility download-images

# avoid errors on rebuilds
ddev poweroff

# start ddev project automatically
ddev start -y

# further automated install / setup steps, e.g.
ddev composer install
```

To check for errors during the `postCreateCommand` action, use the command

- “Codespaces: View creation log”

via the [Visual Studio Code Command Palette](<https://docs.github.com/en/enterprise-cloud@latest/codespaces/codespaces-reference/using-the-vs-code-command-palette-in-codespaces>):

- <kbd>⌘</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on a Mac
- <kbd>CTRL</kbd> + <kbd>SHIFT</kbd> + <kbd>P</kbd> on Windows/Linux
- from the Application Menu, click View \> Command Palette (Firefox)

![](<https://ddev.github.io/ddev/en/images/codespaces-creation-log.png>)

## Manual

DDEV is a single executable, so installation on any OS is a matter of copying the `ddev` executable for your architecture into the appropriate system path on your machine.

- Download and extract the latest [DDEV release](<https://github.com/ddev/ddev/releases>) for your architecture.
- Move `ddev` to `/usr/local/bin` with `mv ddev /usr/local/bin/` (may require `sudo`), or another directory in your `$PATH` as preferred.
- Run `ddev` to test your installation. You should see DDEV’s command usage output.
- As a one-time initialization, run `mkcert -install`, which may require your `sudo` password.

  If you don’t have `mkcert` installed, download the [latest release](<https://github.com/FiloSottile/mkcert/releases>) for your architecture and `sudo mv <downloaded_file> /usr/local/bin/mkcert && sudo chmod +x /usr/local/bin/mkcert`.
- For unusual browsers and situations that don’t automatically support the `mkcert` certificate authority, [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

# Upgrading DDEV

Installing and upgrading DDEV are nearly the same thing, because you’re upgrading the `ddev` binary that talks with Docker. You can update this file like other software on your system, whether it’s with a package manager or traditional installer.

> [!TIP]
>
> **`ddev --version` shows an old version**
>
> If you have installed or upgraded DDEV to the latest version, but when you check the actual version with `ddev --version`, it shows an older version, please refer to [Why do I have an old DDEV?](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>)

## macOS

### Homebrew (Most Common)

```
# Upgrade DDEV to the latest version
brew update && brew upgrade ddev/ddev/ddev
```

### Install Script (Unusual)

```
# Download and run the script to replace the DDEV binary
curl -fsSL https://ddev.com/install.sh | bash
```

### Verify New Version

Use `ddev --version` to find out the version of the `ddev` binary in your `$PATH`. If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` binary must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

**Need a specific version?**

Use the `-s` argument to specify a specific stable or prerelease version:

```
# Download and run the script to update to DDEV v1.24.10
curl -fsSL https://ddev.com/install.sh | bash -s v1.24.10
```

## Linux

### Debian/Ubuntu (including WSL2)

```
# Update package information and ddev package
sudo apt-get update && sudo apt-get install --only-upgrade ddev

# If you are using WSL2, also upgrade the ddev-wsl2 package
sudo apt-get update && sudo apt-get install --only-upgrade ddev ddev-wsl2
```

### Fedora, Red Hat, etc.

```
# Upgrade the DDEV package
sudo dnf upgrade --refresh ddev
```

### Arch Linux

```
# Upgrade the DDEV package
yay -Syu ddev-bin
```

### Verify New Version

Use `ddev --version` to find out the version of the `ddev` binary in your `$PATH`. If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` binary must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

## Windows

### WSL2 + Docker

If you’re using WSL2, the upgrade process is the same regardless of how you installed DDEV.

Open the WSL2 terminal, for example “Ubuntu” from the Windows start menu, and run the following:

```
# Update package information and ddev packages
sudo apt-get update && sudo apt-get install --only-upgrade ddev ddev-wsl2
```

You can also download and run the DDEV Windows Installer again (see [Traditional Windows](<#traditional-windows>) below), and it will do the upgrade for you. Make sure to choose the type of installation you have (Docker CE or Docker/Rancher Desktop).

### Verify New Version

Use `ddev --version` to find out the version of the `ddev` binary in your `$PATH`. If `ddev --version` still shows an older version than you installed or upgraded to, use `which -a ddev` to find out where another version of the `ddev` binary must be installed. See the [“Why Do I Have An Old DDEV” FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>).

### Traditional Windows

Download the installer — make sure to pick the right architecture:

- **AMD64 (x86-64)**: Most traditional Windows PCs (Intel/AMD processors)
- **ARM64**: Windows on ARM devices like Microsoft Surface Pro X, Surface Pro 9 (5G), or other ARM-based Windows devices

> [!TIP]
>
> **Check your system architecture**
>
> Not sure which architecture you have? Open PowerShell and run: `$env:PROCESSOR_ARCHITECTURE`. It will show `AMD64` or `ARM64`. Alternatively, in WSL2/Ubuntu run `uname -m` which shows `x86_64` for AMD64 or `aarch64` for ARM64.

Run the installer and follow the prompts to complete the upgrade.

> [!TIP]
>
> **Upgrade using WinGet**
>
> ```
> winget upgrade --interactive DDEV
> ```

> [!TIP]
>
> **Upgrade using Chocolatey (Traditional Windows AMD64 only)**
>
> ```
> choco upgrade ddev
> ```

## GitHub Codespaces

```
# Update package information and ddev package
sudo apt-get update && sudo apt-get install --only-upgrade ddev
```

## Manual

Upgrade using the exact same [manual install](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#manual>) process:

- Download and extract the latest [DDEV release](<https://github.com/ddev/ddev/releases>) for your architecture.
- Move `ddev` to `/usr/local/bin` with `mv ddev /usr/local/bin/` (may require `sudo`), or another directory in your `$PATH` as preferred.
- Run `ddev --version` to confirm you’re running the expected version.

# Docker Installation

You’ll need a Docker provider on your system before you can [install DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>).

## macOS

Choose a container runtime:

- **Docker** (recommended) - The best-tested option. Install OrbStack, Lima, Docker Desktop, Rancher Desktop, or Colima.
- **Podman rootless** - Rootless by default; a good fit where Docker is forbidden. Can’t use the default ports 80/443, so DDEV must be configured to use unprivileged ports.

Install one of the supported Docker providers:

- [OrbStack](<#orbstack>): Recommended, easiest to install, most performant, commercial, not open-source.
- [Lima](<#lima>): Free, open-source.
- [Docker Desktop](<#docker-desktop-for-mac>): Familiar, popular, not open-source, may require license, may be unstable.
- [Rancher Desktop](<#rancher-desktop>): Free, open-source, simple installation, slower startup.
- [Colima](<#colima>): Free, open-source. Depends on separate Lima installation (managed by Homebrew).

### OrbStack

[OrbStack](<https://orbstack.dev>) is a newer Docker provider that is very popular with DDEV users because it’s fast, lightweight, and easy to install. It’s a good choice for most users. It is *not* open-source, and it is not free for professional use.

1. Install OrbStack with `brew install orbstack` or [download it directly](<https://orbstack.dev/download>).
2. Run the OrbStack app (from Applications) to finish setup, choosing “Docker” as the option. Answer any prompts to allow OrbStack access.

### Lima

[Lima](<https://github.com/lima-vm/lima>) is a free and open-source project supported by the [Cloud Native Computing Foundation](<https://cncf.io/>).

1. Install Lima with `brew install lima`.
2. If you don’t have the `docker` client (if `docker help` fails) then install it with `brew install docker`.
3. Create a 100GB VM in Lima with 4 CPUs, 6GB memory, and Cloudflare DNS. Adjust to your own needs:

   ```
   limactl create --name=default --vm-type=vz --mount-type=virtiofs --mount-writable --memory=6 --cpus=4 --disk=100 template:docker
   docker context create lima-default --docker "host=unix://$HOME/.lima/default/sock/docker.sock"
   docker context use lima-default
   ```

   After the initial run above, you can use `limactl start`. Run `limactl list` to see configured setup.

When your computer restarts, you’ll need to `limactl start` again.

> [!WARNING]
>
> **Docker contexts let the Docker client point at the right Docker server**
>
> The Docker provider you’re using is selected with `docker context`. You can see the available contexts with `docker context ls` and the currently selected one with `docker context show`. With the setup above you’ll want `docker context use lima-default`.

> [!WARNING]
>
> **Lima only mounts filesystems in your home directory unless you do further configuration**
>
> By default, Lima only works with DDEV projects in your home directory. You must have your projects somewhere in your home directory for DDEV to work unless you do additional configuration. If your project is not in your home directory, you must add additional mounts, as described in [mounts example](<https://github.com/lima-vm/lima/blob/e9423da6b7c60083aaa455a0c6ecb5c729edfe1f/examples/docker.yaml#L25-L28>).

### Docker Desktop for Mac

Docker Desktop for Mac can be downloaded from [docker.com](<https://www.docker.com/products/docker-desktop>). It has long been supported by DDEV and has extensive automated testing. It is not open-source, may require a license for many users, and sometimes has stability problems.

> [!WARNING]
>
> **Ports unavailable?**
>
> If you get messages like `Ports are not available... exposing port failed... is vmnetd running?` it means you need to check the “Allow privileged port mapping (requires password)” checkbox in the “Advanced” section of the Docker Desktop configuration. You may have to stop and restart Docker Desktop, and you may have to turn it off, restart Docker Desktop, turn it on again, restart Docker Desktop. (More extensive problem resolution is in [Docker Desktop issue](<https://github.com/docker/for-mac/issues/6677>).)

### Rancher Desktop

Rancher Desktop is an easy-to-install free and open-source Docker provider. Install from [Rancher Desktop](<https://rancherdesktop.io/>). It has automated testing with DDEV. When installing, choose only the Docker option and turn off Kubernetes.

### Colima

[Colima](<https://github.com/abiosoft/colima>) is a free and open-source project which bundles Lima.

1. Install Colima with `brew install colima`, which also installs Lima and other dependencies.
2. If you don’t have the `docker` client (if `docker help` fails) then install it with `brew install docker`.
3. Start Colima with 4 CPUs, 6GB memory, 100GB storage, Cloudflare DNS, and SSH-agent forwarding, adjusting as needed:

   ```
   colima start --cpu 4 --memory 6 --disk 100 --vm-type=vz --mount-type=virtiofs --dns=1.1.1.1 --ssh-agent
   ```

After the initial run above, you can use `colima start` or use `colima start -e` to edit the configuration file. Run `colima status` at any time to check Colima’s status.

> [!WARNING]
>
> **Docker contexts let the Docker client point at the right Docker server**
>
> Colima activates its own Docker context to prevent conflicts with Docker Desktop. If you run `docker context ls`, you’ll see a list of available contexts where the currently-active one is indicated with a `*`—which will be `colima` after you’ve started it. You can change to the default (Docker Desktop) with `docker context use default` or change back with `docker context use colima`. This means you can run Docker Desktop and Colima at the same time, but be mindful of which context you’re pointing at!

> [!WARNING]
>
> **Colima can only work in your home directory unless you do further configuration**
>
> By default, Colima only works with DDEV projects in your home directory. You need to have your projects somewhere in your home directory for DDEV to work unless you do additional configuration. See the `~/.colima/default/colima.yaml` for more information, or notes in [colima.yaml](<https://github.com/abiosoft/colima/blob/main/embedded/defaults/colima.yaml#L160-L173>).

### Migrating Projects Between Docker Providers

- OrbStack has built-in migration of images and volumes from Docker Desktop.
- Move projects between other Docker providers using [How can I migrate from one Docker provider to another?](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#how-can-i-migrate-from-one-docker-provider-to-another>).

Podman on macOS runs containers in a lightweight VM managed by `podman machine`. You can also use [Podman Desktop](<https://podman-desktop.io/>) for a GUI.

> [!WARNING]
>
> **Podman on macOS can’t use ports 80/443**
>
> Podman on macOS cannot bind to privileged ports (80/443), so you must configure DDEV to use unprivileged ports. After installing DDEV, run:
>
> ```
> ddev config global --router-http-port=8080 --router-https-port=8443
> ```
>
> Your projects will then be reachable at `https://yourproject.ddev.site:8443` instead of the standard `https://yourproject.ddev.site`.

### Install Podman

Install Podman using Homebrew:

```
brew install podman
```

Or install [Podman Desktop](<https://podman-desktop.io/docs/installation/macos-install>) if you prefer a GUI. For more information, see the [official Podman installation guide for macOS](<https://podman.io/docs/installation#macos>) and the [Podman tutorials](<https://github.com/containers/podman/tree/main/docs/tutorials#readme>).

### Install the Docker CLI

Podman provides a Docker-compatible API, so you can use the Docker CLI as a front-end for Podman. This lets you use familiar `docker` commands, switch between runtimes with Docker contexts, and keep compatibility with tools that expect the `docker` command.

```
brew install docker
```

### Initialize and start the Podman machine

The Podman machine gets only 2GB of memory by default, which runs out with more than a project or two running, so create it with 6GB, adjusting to your own needs:

```
# check `podman machine init -h` for more options
podman machine init --provider applehv --memory 6144
podman machine start
```

### Point the Docker CLI at Podman

```
SOCKET=$(podman machine inspect | jq -r '.[0].ConnectionInfo.PodmanSocket.Path')
docker context create podman-rootless \
    --description "Podman (rootless)" \
    --docker "host=unix://${SOCKET}"
docker context use podman-rootless
docker ps
```

### Reclaim disk space

> [!WARNING]
>
> **The Podman machine doesn’t reclaim its own disk space**
>
> The `podman machine` VM grows over time and does not shrink automatically, even after you remove images and containers. Periodically reclaim the freed space by trimming the VM’s filesystem:
>
> ```
> podman machine start
> podman machine ssh 'sudo fstrim -av'
> ```

## Linux

Choose a container runtime:

- **Docker** (recommended) - The best-tested option, with the best performance and stability. Install Docker CE or Docker Desktop.
- **Docker rootless** - Runs the Docker daemon without root, which reduces the attack surface. Full Docker compatibility.
- **Podman rootless** - Rootless by default; a good fit where Docker is forbidden. More setup and slower than Docker.

Install one of the supported Docker providers:

- [Docker CE](<#docker-for-linux>): Recommended, free, open-source, best performance and stability. Install from the official Docker repository.
- [Docker Desktop for Linux](<#docker-desktop-for-linux>): Not explicitly supported by DDEV and has no automated testing.

### Docker for Linux

The best way to install Docker on Linux is to use your native package management tool (`apt`, `dnf`, etc.) with the official Docker repository. While many Linux distributions provide Docker packages in their own repositories, these are often outdated and may not include the latest features required for stability in a development environment like DDEV. To ensure you’re using a supported version, install Docker directly from the official Docker repository.

#### Debian/Ubuntu

```
# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Remove any old/conflicting Docker packages
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true

# Install prerequisites
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

# Add Docker’s GPG key
sudo curl -fsSL https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Remove old repository files if present
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list

# Add Docker repository in deb822 format
printf "Types: deb\nURIs: https://download.docker.com/linux/%s\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "$ID")" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null

# Install Docker CE
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (create group if it doesn’t exist)
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}

# Start and enable Docker
sudo systemctl enable --now docker
```

Run `sg docker` to open a new subshell with the `docker` group active, then verify with `docker run hello-world`. (A full log out and back in applies the change to your whole session.)

> [!TIP]
>
> **Prefer to run as a script?**
>
> Create a script file, then run it:
>
> ```
> cat > /tmp/install-docker.sh << 'SCRIPT'
> #!/usr/bin/env bash
> set -euo pipefail
> sudo true
> sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true
> sudo apt-get update && sudo apt-get install -y ca-certificates curl
> sudo install -m 0755 -d /etc/apt/keyrings
> sudo curl -fsSL "https://download.docker.com/linux/$(. /etc/os-release && echo "$ID")/gpg" -o /etc/apt/keyrings/docker.asc
> sudo chmod a+r /etc/apt/keyrings/docker.asc
> sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list
> printf "Types: deb\nURIs: https://download.docker.com/linux/%s\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
>   "$(. /etc/os-release && echo "$ID")" \
>   "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
>   | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null
> sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
> sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
> sudo systemctl enable --now docker
> SCRIPT
> ```
>
> Review the script, then run it: `bash /tmp/install-docker.sh`

See the full [Docker Engine installation docs for Ubuntu](<https://docs.docker.com/engine/install/ubuntu/>) or [Debian](<https://docs.docker.com/engine/install/debian/>) for more details.

#### Other Linux Distributions

Follow these distribution-specific instructions to set up Docker Engine from the official Docker repository:

- [CentOS](<https://docs.docker.com/install/linux/docker-ce/centos/>)
- [Fedora](<https://docs.docker.com/install/linux/docker-ce/fedora/>)
- [binaries](<https://docs.docker.com/install/linux/docker-ce/binaries/>)

After installing Docker, add your user to the `docker` group and enable the Docker daemon to start at boot:

```
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
sudo systemctl enable --now docker
```

Run `sg docker` to open a new subshell with the `docker` group active, or log out and back in to apply the change to your whole session. See [Post-installation steps for Linux](<https://docs.docker.com/engine/install/linux-postinstall/>) for more details.

> [!WARNING]
>
> **Don’t `sudo` with `docker` or `ddev`**
>
> Don’t use `sudo` with the `docker` command. If you find yourself needing it, you haven’t finished the installation. You also shouldn’t use `sudo` with `ddev` unless it’s specifically for the [`ddev hostname`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#hostname>) command.

On systems without `systemd` or its equivalent—mostly if you’re installing inside WSL2—you’ll need to manually start Docker with `service docker start` or the equivalent in your distro. You can add this to your shell profile.

### Docker Desktop for Linux

As an alternative to Docker CE, Docker Desktop for Linux can be downloaded from [docker.com](<https://www.docker.com/products/docker-desktop>). Casual manual testing seems to work, but DDEV does not have explicit support for it and does not have automated testing.

[Docker rootless mode](<https://docs.docker.com/engine/security/rootless/>) runs the Docker daemon and containers as a non-root user, which reduces the attack surface (no root daemon, container processes can’t touch root-owned files). DDEV supports Docker rootless on Linux and WSL2, with full Docker compatibility.

> [!TIP]
>
> **`no_bind_mounts` is no longer required**
>
> Earlier DDEV versions (v1.25.0-v1.25.2) required [`no_bind_mounts`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_bind_mounts>) with Docker rootless. That is no longer necessary—Docker rootless now works with bind mounts.
>
> With bind mounts under Docker rootless, you appear as `root` inside the web container (for example, in [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>)). This is expected: rootless maps container `root` to your regular host user, so it has no special privileges on the host. If you prefer not to work as `root` in the container, run `ddev config global --no-bind-mounts=true`. This enables [`no_bind_mounts`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_bind_mounts>), which relies on [Mutagen](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) to sync files rather than mounting them directly.

### Install Docker rootless

Follow the official [Docker rootless installation guide](<https://docs.docker.com/engine/security/rootless/>).

### Configure the system

```
# Allow privileged port access if needed
if [ -f /proc/sys/net/ipv4/ip_unprivileged_port_start ]; then
  if [ "1024" = "$(cat /proc/sys/net/ipv4/ip_unprivileged_port_start)" ]; then
    echo 'net.ipv4.ip_unprivileged_port_start=0' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Allow loopback connections (needed for working Xdebug)
# See https://github.com/moby/moby/issues/47684#issuecomment-2166149845
mkdir -p ~/.config/systemd/user/docker.service.d
cat << 'EOF' > ~/.config/systemd/user/docker.service.d/override.conf
[Service]
Environment="DOCKERD_ROOTLESS_ROOTLESSKIT_DISABLE_HOST_LOOPBACK=false"
EOF
```

### Enable the Docker socket

```
systemctl --user enable --now docker.socket

# You should see `/run/user/1000/docker.sock` (the number may vary):
ls $XDG_RUNTIME_DIR/docker.sock
```

### Point the Docker CLI at the rootless socket

```
# View existing contexts
docker context ls

# Create the rootless context if it doesn't exist
docker context inspect rootless >/dev/null 2>&1 || \
    docker context create rootless \
        --description "Rootless runtime socket" \
        --docker host="unix://$XDG_RUNTIME_DIR/docker.sock"

# Switch to the context
docker context use rootless

# Verify it works
docker ps
```

[Podman](<https://podman.io/>) is rootless by default, which makes it a good fit for environments that forbid Docker or require rootless operation. Podman is slower than Docker and has more setup, but Podman rootless on Linux is solid.

### Install Podman

Install Podman with your distribution’s package manager (see the [official Podman installation guide for Linux](<https://podman.io/docs/installation#installing-on-linux>)):

```
# Ubuntu/Debian
sudo apt-get update && sudo apt-get install podman
# Fedora
sudo dnf install --refresh podman
```

**Last resort: a newer Podman from Homebrew**

[Homebrew](<https://brew.sh/>) packages a current Podman. DDEV’s CI installs it this way so that tests always run against the latest Podman, but it is not the recommended way to get Podman on a workstation: it means running a container stack from a second package manager, and most of the [troubleshooting](<#podman-rootless-troubleshooting>) entries below exist only because of it. Prefer your distribution’s Podman even when it’s older.

If you do use it, remove the distribution’s Podman *and what it brought in* first, keeping only the `uidmap` helpers, which are root-owned privileged binaries that Homebrew cannot provide:

```
# Ubuntu/Debian
sudo apt-get install -y uidmap && sudo apt-mark manual uidmap
sudo apt-get purge -y --auto-remove podman crun netavark aardvark-dns
# Fedora
sudo dnf remove -y podman crun netavark aardvark-dns

brew install podman
hash -r
```

The `apt-mark manual` is not optional: `uidmap` arrives as an automatic dependency of the distribution’s Podman, so the `--auto-remove` above — or any later `apt-get autoremove` run for unrelated cleanup — removes it again and breaks rootless Podman.

You can also install [Podman Desktop](<https://podman-desktop.io/docs/installation/linux-install>) if you prefer a GUI. For more information, see the [Podman tutorials](<https://github.com/containers/podman/tree/main/docs/tutorials#readme>).

### Install the Docker CLI and buildx

Podman provides a Docker-compatible API, so you can use the Docker CLI as a front-end for Podman. This lets you use familiar `docker` commands, switch between runtimes with Docker contexts, and keep compatibility with tools that expect the `docker` command.

1. [Set up Docker’s repository](<https://docs.docker.com/engine/install/>).
2. Install the CLI and the buildx plugin (you don’t need `docker-ce`, the Docker engine):

   ```
   # Ubuntu/Debian
   sudo apt-get update && sudo apt-get install docker-ce-cli docker-buildx-plugin
   # Fedora
   sudo dnf install --refresh docker-ce-cli docker-buildx-plugin
   ```

> [!WARNING]
>
> **buildx is required, and DDEV won’t install it for you**
>
> DDEV builds its project images with `docker buildx`, and its default setting (`docker_buildx_version: "system"`) uses whatever buildx is already installed rather than downloading one. Installing only `docker-ce-cli` leaves buildx missing, and `ddev start` then fails at the build step. Check with `docker buildx version`; DDEV requires 0.17.0 or newer.

### Configure Podman rootless

Prepare the system by configuring `subuid`/`subgid` ranges and enabling `userns` options (see the [Arch Linux Wiki](<https://wiki.archlinux.org/title/Podman#Rootless_Podman>) for details). If another user on this machine already holds `100000-165535`, give yourself a range that doesn’t overlap theirs — two users mapping the same host IDs break each other’s containers:

```
# Add subuid and subgid ranges if they don't exist for the current user
grep "^$(id -un):\|^$(id -u):" /etc/subuid >/dev/null 2>&1 || sudo usermod --add-subuids 100000-165535 $(whoami)
grep "^$(id -un):\|^$(id -u):" /etc/subgid >/dev/null 2>&1 || sudo usermod --add-subgids 100000-165535 $(whoami)
# Propagate changes to subuid and subgid
podman system migrate
# Debian requires setting unprivileged_userns_clone
if [ -f /proc/sys/kernel/unprivileged_userns_clone ]; then
  if [ "1" != "$(cat /proc/sys/kernel/unprivileged_userns_clone)" ]; then
    echo 'kernel.unprivileged_userns_clone=1' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Fedora requires setting max_user_namespaces
if [ -f /proc/sys/user/max_user_namespaces ]; then
  if [ "0" = "$(cat /proc/sys/user/max_user_namespaces)" ]; then
    echo 'user.max_user_namespaces=28633' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
# Allow privileged port access if needed
if [ -f /proc/sys/net/ipv4/ip_unprivileged_port_start ]; then
  if [ "1024" = "$(cat /proc/sys/net/ipv4/ip_unprivileged_port_start)" ]; then
    echo 'net.ipv4.ip_unprivileged_port_start=0' | sudo tee -a /etc/sysctl.d/60-rootless.conf
    sudo sysctl --system
  fi
fi
```

Enable the Podman socket and verify it’s running (see the [Podman socket activation documentation](<https://github.com/containers/podman/blob/main/docs/tutorials/socket_activation.md>)):

```
systemctl --user enable --now podman.socket

# You should see `/run/user/1000/podman/podman.sock` (the number may vary):
ls $XDG_RUNTIME_DIR/podman/podman.sock

# You can also check the socket path with:
podman info --format '{{.Host.RemoteSocket.Path}}'
```

Configure the Docker CLI to use Podman (see the [Podman rootless tutorial](<https://github.com/containers/podman/blob/main/docs/tutorials/rootless_tutorial.md>)):

```
# View existing contexts
docker context ls

# Create Podman rootless context
docker context create podman-rootless \
    --description "Podman (rootless)" \
    --docker host="unix://$XDG_RUNTIME_DIR/podman/podman.sock"

# Switch to the new context
docker context use podman-rootless

# Verify it works
docker ps
```

> [!WARNING]
>
> **WSL2: the root filesystem isn’t a shared mount**
>
> On WSL2, `podman info` and container starts may warn `"/" is not a shared mount, this could cause issues or missing mounts with rootless containers`. This is specific to WSL2: its own boot process mounts the root filesystem before `systemd` starts and never marks it shared, unlike a natively booted Linux, where it’s shared from boot. It hasn’t caused failures in DDEV’s own testing, but to fix it for the current session:
>
> ```
> sudo mount --make-rshared /
> ```
>
> That reverts on every `wsl --shutdown` or instance restart. To make it permanent, add to `/etc/wsl.conf`:
>
> ```
> [boot]
> command = mount --make-rshared /
> ```

### Validate the setup

DDEV ships a script that checks everything on this page and explains anything it finds. It works with any Podman install, however you got it, and changes nothing unless you ask it to install:

```
curl -fsSL https://raw.githubusercontent.com/ddev/ddev/main/scripts/linux-podman-rootless.sh -o /tmp/podman-rootless.sh
bash /tmp/podman-rootless.sh
```

It verifies the Podman and `netavark` version pairing, the socket, `cgroup` manager, `subuid`/`subgid` ranges, privileged ports, the Docker context, and buildx. It then stops inferring and starts testing: it runs a real container, builds an image and loads it back into the engine, and watches a container healthcheck report `healthy`. Those last three are the steps `ddev start` fails at on a machine where everything else looks correct. To perform the whole setup described above instead of just checking it, run the script with `--install`. There’s also `--install-brew` for the Homebrew last resort, which is what DDEV’s CI uses.

### Podman rootless performance optimization

What’s slower under Podman rootless is container image and filesystem work: `ddev start`, image builds, `ddev import-db`, `ddev export-db`, `ddev snapshot` (see [Podman run/build performance issues](<https://github.com/containers/podman/issues/13226>) and the [Podman performance documentation](<https://github.com/containers/podman/blob/main/docs/tutorials/performance.md>)). Serving your site is not — once the containers are up, requests go through the same web server, PHP, and database as under Docker. The storage driver is the biggest lever on the operations that are affected.

On Linux kernel 5.13 and newer, Podman uses native rootless `overlay`, which is the fastest option and needs no configuration at all. Check what you’re getting:

```
podman info --format '{{.Store.GraphDriverName}} {{index .Store.GraphStatus "Native Overlay Diff"}}'
```

`overlay true` means you’re already on the fast path — do nothing. If it prints `overlay false`, something has configured the `fuse-overlayfs` mount program, which *disables* native overlay diff; remove `mount_program` from `~/.config/containers/storage.conf` to get the faster native path back.

> [!WARNING]
>
> **Existing containers require a reset**
>
> If you already have Podman containers, images, or volumes, you’ll need to reset Podman for the storage change to take effect: `podman system reset`. This removes all existing containers, images, and volumes (similar to `docker system prune -a`).

### Podman rootless troubleshooting

The Docker CLI hides most Podman-side errors behind a generic message. When something fails, read the real error from the Podman service:

```
journalctl --user -u podman.service --since '-5min'
```

| Symptom | Cause | Fix |
| --- | --- | --- |
| `unable to upgrade to tcp, received 500` from `docker run`, and containers stuck in `Created` | Your `netavark` major version doesn’t match Podman’s — they’re released as a pair, so Podman 6.x needs `netavark` 2.x and Podman 4.x/5.x need 1.x. The Podman log shows `failed to load network options: invalid type: sequence, expected a map`. The usual cause is a Podman installed outside the distribution’s packages while the distribution’s older `netavark` is still there. | Remove the distribution’s `netavark`/`aardvark-dns` so Podman uses its own, or install a Podman matching them. Don’t mix stacks. |
| `could not find "netavark" in one of [...]` | `engine.helper_binaries_dir` is set somewhere. It *replaces* Podman’s helper search path rather than extending it, so if the list omits the `libexec/podman` directory next to your `podman` binary, Podman finds no `netavark` at all — or a wrong-version one. | Remove the `helper_binaries_dir` setting from your `containers.conf` files. |
| `failed to load image: ... Source image rejected: ... is rejected by policy`, after a build that ran to completion | Your `policy.json` rejects by default and doesn’t allow the `docker-archive` and `oci-archive` transports that `buildx --load` uses to hand the built image back. Registry pulls go through a different transport and keep working, so pulling, running and building all look healthy. | In the `policy.json` that applies (`~/.config/containers/policy.json` overrides `/etc/containers/policy.json`), add `"docker-archive"` and `"oci-archive"` entries set to `insecureAcceptAnything` under `transports`. That leaves the rest of the policy intact. |
| `Cannot connect to the Docker daemon`, and `systemctl --user is-active podman.socket` says `failed` | Repeated activation failures tripped `systemd`’s start limit. Fixing the underlying config doesn’t clear this on its own. | `systemctl --user reset-failed podman.socket podman.service`, then `systemctl --user start podman.socket`. |
| `crun: create /sys/fs/cgroup/docker: Permission denied` during a build | Podman is using the `cgroupfs` `cgroup` manager, either because there’s no lingering user session or because something set `cgroup_manager = "cgroupfs"` system-wide. GitHub Actions’ Ubuntu runner image does the latter: it installs Podman from the [`podman-static`](<https://github.com/mgoltzsche/podman-static>) bundle, which ships that setting in `/etc/containers/containers.conf`. | `sudo loginctl enable-linger $(whoami)`. If `grep -rn cgroup_manager /etc/containers/` finds a setting, override it with `cgroup_manager = "systemd"` under `[engine]` in `~/.config/containers/containers.conf.d/ddev-podman.conf`, which outranks `/etc`. Confirm with `podman info --format '{{.Host.CgroupManager}}'`. |
| Containers fail to start, or behave oddly, and `podman info` shows an `ociRuntime` path outside your Podman’s own prefix | Something pins the runtime with `[engine.runtimes]` in a `containers.conf` under `/etc`. GitHub Actions’ runner image pins `crun = ["/usr/local/bin/crun"]`, the statically built `crun` from its Podman 5.x bundle, which then gets used by an unrelated Podman. | Point it back at the `crun` next to your own `podman` — `/usr/bin/crun` for a distribution Podman, `/home/linuxbrew/.linuxbrew/bin/crun` for Homebrew’s — with `[engine.runtimes]` and `crun = ["<that path>"]` in `~/.config/containers/containers.conf.d/ddev-podman.conf`. |
| `compose build requires buildx 0.17.0 or later` | The buildx plugin isn’t installed. | `sudo apt-get install docker-buildx-plugin` |
| `Must provide a valid firewall backend, got iptables` | Newer `netavark` dropped the `iptables` backend, but Podman still requests it. | Add `firewall_driver = "nftables"` under `[network]` in `~/.config/containers/containers.conf.d/ddev-podman.conf`. |
| `registries.conf must be in v2 format but is in v1` | Podman 6 rejects the old registries format. | Replace `/etc/containers/registries.conf` with `unqualified-search-registries = ["docker.io"]`. |
| `Include journald in compilation path to log to systemd journal` | Homebrew’s `conmon` is built without `journald` support, but Podman defaults to `journald` logging. | Set `log_driver = "k8s-file"` under `[containers]` and `events_logger = "file"` under `[engine]` in `~/.config/containers/containers.conf.d/ddev-podman.conf`. |
| `failed to become ready ... timed out without becoming healthy` for every container, with an empty health log (`{"Status":"starting","FailingStreak":0,"Log":null}`) | Podman schedules each container’s healthcheck as a transient `systemd` **user** timer. Either your Podman was built without its `systemd` build tag, which makes the timer functions silent no-ops, or your user session cannot create transient units. The healthcheck script itself is fine — running it with `podman exec` succeeds, which is why this is easy to misdiagnose. | Check the tags with `go version -m $(command -v podman) \\| grep -- -tags=`. If `systemd` is missing, that Podman can’t run healthchecks at all and no configuration changes it — use your distro’s or Homebrew’s build instead. Otherwise check `sudo loginctl enable-linger $(whoami)` and that `systemd-run --user --quiet /bin/true` succeeds. |
| `Unit podman.socket could not be found` from `systemctl --user status podman.socket`, on a Homebrew install | Homebrew’s systemd user units live under `$(brew --prefix)/lib/systemd/user/`, which isn’t one of `systemctl --user`’s search paths (`~/.config/systemd/user/` is). | `mkdir -p ~/.config/systemd/user && ln -s "$(brew --prefix)"/lib/systemd/user/podman.{socket,service} ~/.config/systemd/user/`, then `systemctl --user daemon-reload`. Note that the units Homebrew ships carry no `PATH`, so symlinking them leads straight to `could not find a working conmon binary` below. `scripts/linux-podman-rootless.sh --install-brew` writes its own units with that `PATH` already set. |
| `could not find a working conmon binary`, even though `conmon --version` works in your shell | `systemd --user` services start with a minimal `PATH` that excludes Homebrew’s `bin`, so `podman.service` can’t find `conmon`, `crun`, or other helpers even though your interactive shell can. | Add Homebrew’s `bin` to the service’s `PATH`: `systemctl --user edit podman.service`, add `Environment=PATH=/home/linuxbrew/.linuxbrew/bin:/usr/local/bin:/usr/bin:/bin` under `[Service]`, then `systemctl --user daemon-reload && systemctl --user restart podman.socket`. |
| `netavark (exit code 127): ... libgcc_s.so.1: cannot open shared object file`, or containers silently get no networking | Homebrew’s Linux dynamic linker doesn’t search the host’s system library paths, and `gcc` — which provides `libgcc_s.so.1` — isn’t installed via Homebrew even though `netavark`/`aardvark-dns` (Rust binaries) need it at runtime. | `brew install gcc` |
| `config file not found: no policy.json file found; searched paths: [...]` on a Homebrew install | Homebrew’s Podman ships a default `policy.json` under its own prefix, but nothing links it into a path Podman actually searches (`~/.config/containers/`, `/etc/containers/`, `/usr/share/containers/`). | `mkdir -p ~/.config/containers && cp "$(brew --prefix podman)"/etc/containers/policy.json ~/.config/containers/policy.json` |
| `unable to retrieve auth token: invalid username/password: unauthorized: incorrect username or password` pulling a public image | Stale or invalid Docker Hub credentials in `~/.docker/config.json` interfere with anonymous pulls, the same underlying cause as [`403 authentication required`](<#troubleshooting>) below. | `docker logout` |

## Windows

First [install WSL2](<#install-wsl2>) below, then [choose a container runtime](<#choose-a-container-runtime>):

- **Docker** (recommended) - The best-tested option. Run Docker CE inside WSL2, or use Docker Desktop or Rancher Desktop.
- **Docker rootless** - Runs the Docker daemon without root, which reduces the attack surface. Runs inside WSL2 using the same setup as Linux.
- **Podman rootless** - Rootless by default; a good fit where Docker is forbidden. Works via Podman Desktop, but is less mature on Windows than on Linux.

### Install WSL2

In PowerShell, run:

```
# Install WSL2; reboot if prompted, then continue:
wsl --install --no-distribution

# Update WSL2 if previously installed:
wsl --update
```

Create a Debian-based WSL2 distro (skip if you’re using Traditional Windows). Ubuntu is recommended:

```
# You'll be asked to set a username and password for the distro:
wsl --install Ubuntu-26.04 --name DDEV
```

> [!TIP]
>
> **"DDEV" is just a suggested name — use any name you like.**

> [!TIP]
>
> **Other Debian-based distros also work**
>
> The DDEV installer supports Ubuntu and Debian and has been tested on Kali Linux and eLxr. If you prefer one of those, substitute its name, for example `wsl --install Debian --name DDEV`.

Verify the “DDEV” distro is set as default:

```
> wsl -l -v
  NAME                   STATE           VERSION
* DDEV                   Stopped         2
```

### Choose a container runtime

Install one of the supported Docker providers:

- [Docker CE inside WSL2](<#docker-ce-inside-wsl2>): Recommended, most popular, performant, and best-supported. The [DDEV installer](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#windows>) installs it automatically. Requires WSL2.
- [Docker Desktop for Windows](<#docker-desktop-for-windows>): Works with both WSL2 and traditional Windows. Extensive automated testing, but some performance and reliability problems. Not open-source; may require a license.
- [Rancher Desktop for Windows](<#rancher-desktop-for-windows>): Free, open-source. Manually tested on traditional Windows; no automated testing. Works with both WSL2 and traditional Windows.

### Docker CE inside WSL2

The [DDEV Windows installer](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#step-2-install-ddev>) automatically installs Docker CE in your WSL2 environment — no manual Docker installation is needed. After installing WSL2 above, proceed to [install DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#step-2-install-ddev>).

To install Docker CE manually instead, open your WSL2 terminal (Ubuntu) and run:

```
# Ensure sudo credentials are cached for copy/paste of this block
sudo true

# Remove any old/conflicting Docker packages
sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true

# Install prerequisites
sudo apt-get update && sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings

# Add Docker's GPG key
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Remove old repository files if present
sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list

# Add Docker repository in deb822 format
printf "Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
  "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
  | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null

# Install Docker CE
sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (create group if it doesn't exist)
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
```

Run `sg docker` to open a new subshell with the `docker` group active, or log out and back in to apply the change to your whole session. On WSL2 systems without `systemd`, you may need to start Docker manually with `sudo service docker start`.

> [!TIP]
>
> **Prefer to run as a script?**
>
> Create a script file, then run it:
>
> ```
> cat > /tmp/install-docker.sh << 'SCRIPT'
> #!/usr/bin/env bash
> set -euo pipefail
> sudo true
> sudo apt-get remove -y docker.io docker-doc docker-compose podman-docker containerd runc 2>/dev/null || true
> sudo apt-get update && sudo apt-get install -y ca-certificates curl
> sudo install -m 0755 -d /etc/apt/keyrings
> sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
> sudo chmod a+r /etc/apt/keyrings/docker.asc
> sudo rm -f /etc/apt/keyrings/docker.gpg /etc/apt/sources.list.d/docker.list
> printf "Types: deb\nURIs: https://download.docker.com/linux/ubuntu\nSuites: %s\nComponents: stable\nSigned-By: /etc/apt/keyrings/docker.asc\n" \
>   "$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")" \
>   | sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null
> sudo apt-get update && sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
> sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
> SCRIPT
> ```
>
> Review the script, then run it: `bash /tmp/install-docker.sh`

### Docker Desktop for Windows

1. Download and install Docker Desktop from [docker.com](<https://www.docker.com/products/docker-desktop>).
2. During installation, ensure “Use WSL 2 instead of Hyper-V” is selected.
3. After installation, open Docker Desktop settings and navigate to **Resources → WSL Integration**.
4. Enable integration with your Debian-based WSL2 distro (e.g., Ubuntu-26.04, Debian).
5. Apply the changes and restart Docker Desktop if prompted.
6. Verify that `docker ps` works in git-bash, PowerShell, or WSL2, wherever you’re using it.

### Rancher Desktop for Windows

1. Download and install [Rancher Desktop](<https://rancherdesktop.io/>).
2. During installation, choose **Docker** as the container runtime and disable Kubernetes.
3. After installation, open Rancher Desktop and go to **WSL Integration** in the settings.
4. Enable integration with your Debian-based WSL2 distro (e.g., Ubuntu-26.04, Debian).
5. Apply the changes and restart Rancher Desktop if needed.
6. Verify that `docker ps` works in git-bash, PowerShell, or WSL2, wherever you’re using it.

Docker rootless runs inside WSL2 using the same setup as Linux. In your WSL2 distro, follow the [Docker rootless instructions for Linux](<#linux-docker-rootless>).

Windows users can run Podman via [Podman Desktop](<https://podman-desktop.io/>), which manages the WSL2-based VM for you. Podman on Windows works but is less mature than on Linux.

### Install Podman

Install [Podman Desktop](<https://podman-desktop.io/docs/installation/windows-install>), which includes Podman. Alternatively, install Podman directly following the [official Podman installation guide for Windows](<https://podman.io/docs/installation#windows>). For more information, see the [Podman tutorials](<https://github.com/containers/podman/tree/main/docs/tutorials#readme>).

### Configure Podman

Setup and configuration follow the same patterns as the Linux/WSL2 setup, but with Podman Desktop managing the VM for you. Follow the [Podman rootless instructions for Linux](<#linux-podman-rootless>).

## GitHub Codespaces

You can set up [GitHub Codespaces](<https://github.com/features/codespaces>) following the instructions in the [DDEV Installation](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#github-codespaces>) section.

## Docker Buildx

DDEV requires the [Docker buildx plugin](<https://github.com/docker/buildx>). GUI-based providers (OrbStack, Docker Desktop, Rancher Desktop) bundle it. If `docker buildx version` doesn’t work, install it:

- **macOS (Homebrew):** `brew install docker-buildx`
- **Linux/WSL2 (Debian/Ubuntu):** `sudo apt-get install docker-buildx-plugin` (requires the [official Docker repository](<https://docs.docker.com/engine/install/>) to be configured)
- **Other:** see [Docker buildx requirement](<https://ddev.com/blog/docker-buildx-requirement-v1-25-1/>) for installation instructions across platforms.

> [!TIP]
>
> **Can’t install the plugin?**
>
> As a fallback, DDEV can manage its own copy via [`docker_buildx_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#docker_buildx_version>).

## Running Multiple Container Runtimes

You can run Docker and Podman sockets simultaneously and switch between them using Docker contexts.

For example, here’s a system with three active Docker contexts:

```
$ docker context ls
NAME                DESCRIPTION                               DOCKER ENDPOINT
default             Current DOCKER_HOST based configuration   unix:///var/run/docker.sock
podman-rootless *   Podman (rootless)                         unix:///run/user/1000/podman/podman.sock
rootless            Rootless runtime socket                   unix:///run/user/1000/docker.sock
```

Switch between them with:

```
docker context use "<context-name>"
```

## Switching Runtimes with DDEV

DDEV automatically detects your active container runtime. To switch:

1. Stop DDEV projects:

```
ddev poweroff
```

1. Switch the Docker context or change the `DOCKER_HOST` environment variable.
2. Start your project:

```
ddev start
```

For background on the trade-offs between these runtimes, see [Podman and Docker Rootless in DDEV](<https://ddev.com/blog/podman-and-docker-rootless/>).

## Troubleshooting Docker

### Common Connection Errors

> `Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?`

A message like this can mean that your Docker provider hasn’t been started (or hasn’t been installed). It can also mean that the wrong Docker context is selected, which happens sometimes when people are switching to a new Docker provider. `docker context ls` will show you the available contexts and which one is in use.

But this error often indicates that either Docker is not installed or the Docker daemon is not running:

- **macOS/Traditional Windows:** Start your Docker provider (e.g., OrbStack, Docker Desktop, Rancher Desktop) from your applications menu
- **Linux/WSL2:** Run `sudo systemctl enable --now docker` to start and enable it to start automatically on boot

---

> `permission denied while trying to connect to the docker API at unix:///var/run/docker.sock`

A message like this means that your user is not in the `docker` group:

```
sudo groupadd -f docker && sudo usermod -aG docker ${SUDO_USER:-$USER}
# sg opens a new subshell with the `docker` group active;
# log out and back in to apply the change to your full session
sg docker
```

---

> `error during connect: Get "http://host:2375/v1.51/version": dial tcp: lookup host on 127.0.0.53:53: server misbehaving`

or

> `unable to resolve docker endpoint: context "docker-desktop": context not found`

These errors indicate Docker context issues:

- List available contexts: `docker context ls`
- Switch to default (or different) context: `docker context use default`
- Validate the current context: `docker ps`

> [!WARNING]
>
> **Environment variables override Docker context**

If you have set `DOCKER_HOST` and/or `DOCKER_CONTEXT` environment variables, they will override the `docker context` settings. This can lead to connection issues if the host is unreachable or the specified context is incorrect. Check your shell profile (`~/.bashrc`, `~/.zshrc`) for these variables.

> [!TIP]
>
> **Creating a Docker context**

You can create a new Docker context using the `docker context create` command. See [Remote Docker Environments](<https://ddev.github.io/ddev/en/stable/users/topics/remote-docker/index.md>) for examples.

### Testing Docker Setup

For DDEV to work properly, Docker needs to:

- Mount your project code directory (typically under your home folder) from host to container
- Access TCP ports on the host for HTTP/HTTPS (default ports 80 and 443, configurable per project)

Run this command in your *project directory* to verify Docker configuration (use Git Bash if you’re on Windows!):

```
docker run --rm -t -p 80:80 -p 443:443 -v "//$PWD:/tmp/projdir" ddev/ddev-utilities sh -c "echo ---- Project Directory && ls /tmp/projdir"
```

**Expected result:** A list of files in the current directory.

Common test command issues:

> `port is already allocated`

Another service is using ports 80 or 443. See the [Web Server Ports Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>) section.

> `invalid mount config for type "bind": bind mount source path does not exist`

The filesystem path isn’t properly shared with Docker:

- **Docker Desktop:** Go to Settings → Resources → File Sharing and add your project directory or drive
- **Linux:** Ensure proper permissions on the project directory

> `The path (...) is not shared and is not known to Docker`

**Docker Desktop:** Add the path in Settings → Resources → File Sharing and restart Docker Desktop after making changes.

> `Error response from daemon: Get registry-1.docker.io/v2/`

Docker daemon isn’t running, or no internet connection:

- Start/restart Docker and verify internet connectivity
- Check if corporate firewall blocks Docker Hub access

> `403 authentication required` during `ddev start`

Stale Docker Hub authentication interfering with public image pulls:

- **Solution:** Run `docker logout` and try again
- **Note:** Docker authentication is *not* required for normal DDEV operations

# Installation

Whatever system you’re on, you’ll first need to [install a Docker provider](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>), then [install DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>), and optionally [configure your browser](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

For the best experience, consider [performance tuning](<https://ddev.github.io/ddev/en/stable/users/install/performance/index.md>) and [enabling shell completion](<https://ddev.github.io/ddev/en/stable/users/install/shell-completion/index.md>).

# Performance

DDEV is continually focused on quick project startup and fast responses to its web requests. DDEV’s performance is mostly an issue of how Docker runs on your workstation.

On Linux, including Windows WSL2, Docker is fast. Most people are happy with Linux performance and don’t need to change anything.

On macOS and Windows with Docker Desktop, allocated resources and mounted filesystem performance can be significant bottlenecks. Taking a bit of time to optimize your setup can yield massive performance gains.

## Filesystem Performance

Mutagen offers a huge performance boost on macOS and Traditional Windows. It’s fast and doesn’t need any setup; It’s enabled by default in those environments, but you have the option of turning it off.

Mutagen is enabled by default on Mac and traditional Windows, and it can be disabled per-project or globally.

## Mutagen

### What Mutagen Does

The [Mutagen](<https://mutagen.io>) asynchronous caching feature is the best way to improve DDEV’s web-serving performance on macOS and Windows, and we recommend it for most projects. It offers enormous webserving performance benefits over most basic Docker providers, and it makes filesystem watchers (`fsnotify`/`inotify`) work correctly.

Mutagen decouples in-container reads and writes from reads and writes on the host machine, so each can enjoy near-native speed. A change on the host gets changed “pretty soon” in the container, and a change in the container gets updated “pretty soon” on the host; neither filesystem is stuck waiting on the other one. This “pretty soon” means, however, that there’s a brief window where files on the host may not exactly match the files inside the container—so files that manage to change in both places can lead to conflicts.

Docker bind-mounts, the traditional approach to getting your code into DDEV’s web container, check every file access against the file on the host. Docker’s way of doing these checks macOS and Windows is not very performant. Linux and Linux-like systems are faster because Docker provides native file-access performance.

While Mutagen works fine and has automated tests for Linux and Windows WSL2, it may not be worth enabling on those systems since it won’t make the dramatic difference it does on macOS and Windows.

Mutagen supports filesystem notifications, so file-watchers on both the host and inside the container will be notified when changes occur. This is a great advantage for many development tools, which otherwise have to poll for changes at greater expense. Instead, they can be notified via normal `inotify`/`fsnotify` techniques.

### Enabling and Disabling Mutagen

> [!WARNING]
>
> **Don’t Install Mutagen**
>
> You do not need to install anything to use Mutagen. DDEV installs and maintains its own `mutagen` binary.

On macOS and traditional Windows, Mutagen is enabled globally by default.

To disable Mutagen on a single project, run `ddev config --performance-mode=none && ddev restart`.

To revert Mutagen back to the default globally controlled mode for a single project, run `ddev config --performance-mode-reset && ddev restart`.

(This removes the configuration line so global settings are used instead.)

To disable Mutagen globally on all ddev projects, run `ddev mutagen reset && ddev config global --performance-mode=none && ddev config --performance-mode=none`. To then use Mutagen on a specific project, run [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>), enable it with `ddev config --performance-mode=mutagen`, and [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) again.

### Mutagen and User-Generated Uploads

When Mutagen is enabled, DDEV attempts to exclude user-generated files in `upload_dirs` (if they exist) from syncing. It does this by using a bind-mount in the generated docker-compose configuration, and excluding the directories from syncing in `.ddev/mutagen/mutagen.yml`.

If you have a non-standard location for user-generated files, like `private/fileadmin` with the deprecated `typo3-secure-web` approach, you should override the project defaults by setting `upload_dirs` in `.ddev/config.yaml` and pointing it at the correct directory. This will allow Mutagen to sync correctly.

If you change the `upload_dirs`, run `ddev mutagen reset` to let Mutagen know about the changed behavior.

### Mutagen Integration Caveats

If you run into an issue with Mutagen, please try to recreate and report it via a [support channel](<https://ddev.github.io/ddev/en/stable/users/support/index.md>)!

Mutagen has generally been great for those using it, but it’s good to be aware of its trade-offs:

- **It may not be the right choice for every project.**  
  Filesystem consistency has been excellent with Mutagen, but performance is its specialty. If consistency is your highest priority, then there are reasons to be cautious. Two-way sync is a very difficult computational problem, and problems *may* surface.
- **The initial sync takes longer.**  
  For most projects, the first-time Mutagen sync of a project takes no more than 30 seconds, and subsequent starts take 10 seconds or less. If your project is taking a long time to sync, especially after the initial sync, see [Advanced Configuration](<#advanced-mutagen-configuration-options>) below to figure out what’s taking time and how to bind-mount it.
- **Reset if you change `mutagen.yml`.**  
  If you take control of the `mutagen.yml` file and make changes to it, run `ddev mutagen reset` after making changes.
- **Avoid file changes when DDEV is stopped.**  
  If you change files—checking out a different branch, removing a file—while DDEV is stopped, Mutagen has no way to know about it. When you start again, it will get the files that are stored and bring them back to the host. If you *do* change files while DDEV is stopped, run `ddev mutagen reset` before restarting the project so Mutagen only starts with awareness of the host’s file contents.
- **It modestly increases disk usage.**  
  Mutagen integration increases the size of your project code’s disk usage, because the code exists both on your computer *and* inside a Docker volume. Your user-uploaded files directories (`upload_dirs`) are normally excluded from Mutagen so they’re not a problem for most project types or generic configurations where `upload_dirs` is specified. Take care that you have enough overall disk space, and that on macOS you’ve allocated enough file space in Docker Desktop. If you have other large directories you can [exclude specific directories from getting synced](<#advanced-mutagen-configuration-options>) and use a regular Docker mount for them instead.
- **Beware simultaneous changes to the same file in both filesystems.**  
  As we pointed out above, any project likely to change the same file on the host *and* inside the container may encounter conflicts.
- **Massive changes can cause problems.**  
  Massive file changes on the host or in the container are the most likely to introduce issues. This integration has been tested extensively with major changes introduced by `ddev composer` and `ddev composer create-project`, but be aware of this issue. Changing Git branches, `npm install`, `yarn install`, or a script that deletes huge sections of the synced data are related behaviors that should raise caution. Again, use `ddev mutagen reset` before restarting the project if you want to be sure Mutagen starts out looking at the host machine’s files.
- **Mutagen is asynchronous.**  
  A massive change in either filesystem can result in lag as all changed files are handled. You can use `ddev mutagen monitor` to get a better look at what’s happening.
- **You can manually trigger a sync.**  
  [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>) automatically force a Mutagen sync. You can cause an explicit sync with `ddev mutagen sync` and see syncing status with [`ddev mutagen status`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mutagen-status>).
- **Be mindful of in-container Composer actions.**  
  If you run Composer actions inside the container with [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), it’s a good idea to run [`ddev mutagen sync`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mutagen-sync>) and make sure they’re synced as soon as possible. Most people won’t notice the difference and Mutagen will get it synced soon enough.
- **Perform big Git operations on the host side.**  
  Git actions that change lots of files, like switching branches, are best done on the host side and not inside the container. You may want to do an explicit `ddev mutagen sync` command after doing something like that to be sure all changes are picked up quickly.
- **Share projects carefully with non-Mutagen users.**  
  If you share a project with some users that want Mutagen, perhaps on macOS, and other users that don’t want or need it, perhaps on WSL2, don’t check in `.ddev/config.yaml`’s [`performance_mode: "mutagen"`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#performance_mode>). Instead, either use [global performance mode configuration](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#performance_mode>) or add a not-checked-in, project-level `.ddev/config.performance.yaml` solely to include `performance_mode: "mutagen"` in it. That way, only users with that file will have Mutagen enabled.
- **Windows symlinks have some Mutagen restrictions.**  
  On macOS and Linux (including WSL2) the default `.ddev/mutagen/mutagen.yml` chooses the `posix-raw` type of symlink handling. (See [mutagen docs](<https://mutagen.io/documentation/synchronization/symbolic-links>)). This basically means any symlink created will try to sync, regardless of whether it’s valid in the other environment. Mutagen, however, does not support `posix-raw` on traditional Windows, so DDEV uses the `portable` symlink mode. The result is that on Windows, using Mutagen, symlinks must be strictly limited to relative links that are inside the Mutagen section of the project.
- **It’s a filesystem feature. Make backups!**  
  If we’ve learned anything from computer file-storage adventures, it’s that backups are always a good idea!
- **Large `node_modules` can cause cause slow sync times**  
  When you’re compiling static, front-end assets with tools like `npm` and `yarn`, e.g. Drupal themes, syncing the `node_modules` directory can be very slow. **The solution is to add `node_modules` to the `upload_dirs` list in `.ddev/config.yaml`**, which will exclude it from Mutagen sync while still making it available in the container via Docker bind-mount.

**Important:** When overriding `upload_dirs`, you must include any existing CMS-specific defaults (like `sites/default/files` for Drupal) or they will be lost. For example, for a Drupal project:

```
upload_dirs:
  - sites/default/files  # Keep the CMS default
  - node_modules         # Add your exclusion
```

Then run `ddev restart`. This problem can also occur with directories that contain large binaries or fonts, for example.

### Syncing After `git checkout`

In general, it’s best practice on most projects to do significant Git operations on the host, but they can be disruptive to the sync. It’s easy to add a Git post-checkout hook to do a `ddev mutagen sync` operation though. Add a `.git/hooks/post-checkout` file to your project and make it executable with `chmod +x .git/hooks/post-checkout`:

```
#!/usr/bin/env bash
ddev mutagen sync || true
```

### Syncing After `yarn`, `npm`, and `pnpm` Actions

Actions by those programs can also set off massive filesystem changes.

You should run [`ddev mutagen sync`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mutagen-sync>) in order to get things into sync, or simply wait.

### Advanced Mutagen Configuration Options

> [!WARNING]
>
> **Editing mutagen.yml is rarely needed**
>
> **In almost all cases, you should use `upload_dirs` in `.ddev/config.yaml` to exclude directories from Mutagen sync** (see example above). This is simpler and doesn’t require understanding Mutagen’s configuration format. Only edit `.ddev/mutagen/mutagen.yml` if you need advanced control beyond what `upload_dirs` provides.

The Mutagen project provides [extensive configuration options](<https://mutagen.io/documentation/introduction/configuration>).

Each DDEV project includes a `.ddev/mutagen/mutagen.yml` file by default, with basic defaults you can override if you remove the `#ddev-generated` line at the beginning of the file.

If you need to edit the `.ddev/mutagen/mutagen.yml` file:

- Remove the `#ddev-generated` line
- Execute a [`ddev mutagen reset`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mutagen-reset>) to avoid the situation where the Docker volume and Mutagen session still have files from an older configuration.

The most common need is to exclude a path from Mutagen syncing:

- **Recommended approach:** Add directories to the `upload_dirs` list in `.ddev/config.yaml` (see example above). This automatically excludes them from Mutagen sync while making them available in the container via Docker bind-mount.
- **Advanced approach:** Manually configure exclusions in the `paths:` section of the `ignore:` stanza in `.ddev/mutagen/mutagen.yml` and set up custom bind mounts with `docker-compose.*.yaml` files.

For example, if you want the `node_modules` subdirectory of the project to be available inside the container, but don’t need Mutagen to be syncing it, you can either:

**Option 1 (Recommended - Simple):** Add to `upload_dirs` in `.ddev/config.yaml` (remember to include existing defaults):

```
upload_dirs:
  - sites/default/files  # Keep existing CMS default (if applicable)
  - node_modules         # Add your exclusion
```

Then `ddev restart`.

**Option 2 (Advanced):** Manually configure Mutagen exclusion and bind mount:

- Take over the `.ddev/mutagen/mutagen.yml` by removing the `#ddev-generated` line.
- Add `/web/core/node_modules` to the excluded paths:

```
ignore:
  paths:
  - "/web/core/node_modules"
```

- Add a `.ddev/docker-compose.bindmount.yaml`:

```
services:
  web:
    volumes:
    - "../web/core/node_modules:/var/www/html/web/core/node_modules"
```

- `ddev mutagen reset` and `ddev start` to get the new configuration.

### Troubleshooting Mutagen Sync Issues

- Please make sure that DDEV projects work *without* Mutagen before troubleshooting it. Run `ddev config --performance-mode=none && ddev restart`.
- - Volume sizes (warns if \>5GB, critical if \>10GB)
  - Upload directories configuration
  - Sync session status and problems
  - Large files being synced that could impact performance
  - Ignore pattern configuration

  **Run `ddev utility mutagen-diagnose`** to automatically check for common Mutagen issues. This command analyzes:

  The diagnostic output provides actionable recommendations for improving sync performance. Use `ddev utility mutagen-diagnose --all` to see all Mutagen volumes across all projects. See the [command reference](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-mutagen-diagnose>) for details.
- Rename your project’s `.ddev/mutagen/mutagen.yml` file to `.ddev/mutagen/mutagen.yml.bak` and run `ddev restart`. This ensures you’ll have a fresh version in case the file has been changed and `#ddev-generated` removed.
- Avoid having Mutagen sync large binaries, which can cause `ddev start` to take a long time. The `.tarballs` directory is automatically excluded, so Mutagen will ignore anything you move there. To see what Mutagen is trying to sync, run `ddev mutagen status -l` in another window.
- `DDEV_DEBUG=true ddev start` will provide more information about what’s going on with Mutagen.
- DDEV’s Mutagen daemon keeps its data in a DDEV-only `MUTAGEN_DATA_DIRECTORY` in `$HOME/.ddev_mutagen_data_directory`.
- DDEV’s private Mutagen binary is installed in `$HOME/.ddev/bin/mutagen` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)). You can use all the features of Mutagen with `ddev utility mutagen`. For example:

  ```
  ddev utility mutagen sync list --template "{{ json (index . 0) }}" | docker run -i --rm ddev/ddev-utilities jq -r
  ddev utility mutagen sync monitor <projectname> -l
  ```
- You can run the [diagnose\_mutagen.sh](<https://raw.githubusercontent.com/ddev/ddev/main/scripts/diagnose_mutagen.sh>) script to gather information about Mutagen’s setup. Please share output from it when creating an issue or seeking support.
- Try `ddev poweroff` or `$HOME/.ddev/bin/mutagen daemon stop && $HOME/.ddev/bin/mutagen daemon start` to restart the Mutagen daemon if you suspect it’s hanging.
- Use `ddev mutagen reset` if you suspect trouble, and *always* after changing `.ddev/mutagen/mutagen.yml`. This restarts the project’s Mutagen data (Docker volume + Mutagen session) from scratch.
- `ddev mutagen monitor` can help watch Mutagen behavior. It’s the same as `$HOME/.ddev/bin/mutagen sync monitor <syncname>`.
- If you’re working on the host and expecting things to show up immediately inside the container, you can learn a lot by running `ddev mutagen monitor` in a separate window as you work. You’ll see when Mutagen responds to your changes and get an idea about how much delay there is.
- Consider `ddev stop` before massive file change operations, like moving a directory.
- If you get in real trouble, run `ddev stop`, reset your files with Git, and run `ddev mutagen reset` to throw away the Docker volume which may already have incorrect files on it.

#### Debugging Long Mutagen Startup Time

Normally, a first-time `ddev start` on a new or changed project should only take a minute or less. If it’s taking longer than that, there are likely some huge files or directories that are being synced that we don’t need to sync.

(All we really want to sync is PHP files, everything else is a waste. So if we’re syncing fonts or user-generated files or anything else, we want to figure out what it is and stop it. As noted elsewhere here, `node_modules` can cause this behavior.)

To see what’s causing the slow syncing try this technique:

```
ddev mutagen reset # Cleans up all synced files so starting from scratch
ddev start
```

Then in another terminal window view the syncing behavior with:

```
while true; do ddev mutagen st -l | grep "^Current"; sleep 1; done
```

You’ll see something like this, which may help understand what mutagen is working so hard at. This example is a 5GB file named `dummyfile` in `vendor/bin`.

```
Current file: vendor/bin/dummyfile (306 MB/5.2 GB)
Current file: vendor/bin/dummyfile (687 MB/5.2 GB)
Current file: vendor/bin/dummyfile (1.1 GB/5.2 GB)
Current file: vendor/bin/dummyfile (1.6 GB/5.2 GB)
Current file: vendor/bin/dummyfile (2.0 GB/5.2 GB)
Current file: vendor/bin/dummyfile (2.4 GB/5.2 GB)
Current file: vendor/bin/dummyfile (2.8 GB/5.2 GB)
Current file: vendor/bin/dummyfile (3.1 GB/5.2 GB)
Current file: vendor/bin/dummyfile (3.5 GB/5.2 GB)
Current file: vendor/bin/dummyfile (4.0 GB/5.2 GB)
Current file: vendor/bin/dummyfile (4.4 GB/5.2 GB)
Current file: vendor/bin/dummyfile (4.8 GB/5.2 GB)
Current file: vendor/mck89/peast/lib/Peast/Syntax/Parser.php (66 kB/131 kB)
Current file: web/core/tests/Drupal/Tests/Core/Config/Entity/EntityDisplayBaseTest.php (2.0 kB/2.0 kB)
```

#### Advanced Mutagen Troubleshooting

You can observe what Mutagen is doing by watching `ddev mutagen monitor` in another terminal window to see the results. However, Mutagen has full logging. You can run it with `ddev mutagen logs`.

### Mutagen Strategies and Design Considerations

Mutagen provides enormous speed boosts in everyday usage, but it’s trying desperately under the hood to keep container changes reflected on the host and vice versa.

DDEV mounts a fast Docker volume onto `/var/www/html` inside the `web` container, then delegates to the Mutagen daemon (on the host). That daemon has the job of keeping all host project contents in sync with the contents of the Docker volume.

Consistency is a high priority for DDEV’s integration, which tries at key points to make sure everything is completely consistent and in sync.

The Mutagen daemon’s life cycle and sync sessions are something like this:

1. On `ddev start`, the Mutagen agent will be started if it’s not already running.
2. If there’s already a sync session for the project, it’s resumed.
3. On `ddev stop` the sync session is flushed to ensure consistency, then paused.

A synchronous flush happens after any `ddev composer` command, since Composer may cause massive changes to the filesystem inside the container that need to be synced before operation continues.

If you need to reset everything for a project, you can do it with `ddev mutagen reset`, which starts the Mutagen session from scratch and removes the Docker volume so it can be recreated from scratch.

### Safe to Use with Other Mutagen Installations

DDEV requires and provides a specific version of Mutagen, which you can see running [`ddev version`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#version>). If another `mutagen` instance or daemon is installed on your workstation it doesn’t matter, because DDEV’s version runs separately and uses a different data directory.

## Freeing Up System Resources

Every project you run uses system resources, and may compete for those resources. A reasonable practice is to individually stop projects you’re not using. You could also stop all projects with [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) and only start the one you’re working on. [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) will display all your projects along with each one’s status.

## Docker Desktop for Mac Settings

Open Docker Desktop’s *Preferences*, and visit *Resources* → *Advanced*. Here you can adjust the CPUs, memory, and disk allocated to Docker. The defaults work well for a small project or two, but you may want to adjust these upward based on your experience. Most people raise the memory allocation to 6GB or higher. The disk allocation almost always needs to be raised to accommodate increased downloaded images. Your experience will determine what to do with CPUs.

# PhpStorm Setup

If you work with the [PhpStorm](<https://www.jetbrains.com/phpstorm/>) IDE, you can configure it for tight integration with DDEV and Docker to more easily run actions, access services, enable autocompletion, and enjoy a more convenient development experience.

## Before Starting

Make sure to get at least one project going with `ddev start` before trying to set up the plugin, because the plugin assumes it has a project to work with. For Drupal, see [Configuring PhpStorm](<https://www.drupal.org/docs/develop/development-tools/editors-and-ides/configuring-phpstorm>).

## DDEV Integration Plugin

It’s easiest to use the DDEV Integration Plugin, which you can install from [its landing page](<https://plugins.jetbrains.com/plugin/18813-ddev-integration>) or by searching the in-app marketplace (*Settings* → *Plugins* → *Marketplace*) for “DDEV”. The integration plugin handles nearly everything on this page automatically, and works on all platforms.

Install and enable the plugin, then [set up `phpunit`](<#enabling-phpunit>) since it doesn’t yet handle that for you.

> [!NOTE]
>
> **PHP and Node interpreter automatic setup**
>
> The plugin automatically adds PHP and Node interpreters to your project.
>
> If you installed the plugin *after* a project was already open in PhpStorm, you’ll need to manually switch to the newly added PHP and Node interpreters in *Preferences*. Alternatively, close your IDE and delete the `.idea` directory in the project root to let the plugin set them up automatically.

## Manual Setup

If you’re not using the DDEV Integration Plugin, you can follow these steps instead:

1. Start your project by running [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).
2. Open the DDEV project. In this example, the project name is `drup` and the site is `drup.ddev.site`.

   - If you’re on Windows, running PhpStorm on the Windows side but using WSL2 for your DDEV project, open the project as a WSL2 project. In other words, in the *Open* dialog, browse to `\\wsl$\Ubuntu\home\rfay\workspace\drup` (in this example). (If you’re running PhpStorm inside WSL2, there are no special instructions.)
3. Under *Build, Execution, Deployment* → *Docker*, set the correct Docker provider, for example “Colima” or “Docker for Mac”.
4. Set up your project to do normal Xdebug, as described in the [Step Debugging section](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>). This will result in a PhpStorm “Server” with the proper name, normally the same as the FQDN of the project. In this example, `drup.ddev.site`. (All you have to do here is click the little “bug” to “Start listening for PHP Debug Connections”, run `ddev xdebug on`, and visit a web page and choose the correct mapping from host to server.)
5. Under *File* → *Settings* → *PHP* (Windows) or *Preferences* → *PHP* (macOS), click “…” to the right of “CLI Interpreter”.

   1. Use the “+” to select “From Docker, Vagrant, VM…”.
   2. Choose “Docker Compose”.
   3. Create a “server”; Choose the appropriate Docker provider configured above under *Build, Execution, Deployment* → *Docker*.
   4. In the “Path mappings” of the “Server” you may have to map the local paths (which on WSL2 means `/home/...`) to the in-container paths, especially if you have Mutagen enabled. So “Virtual Machine Path” would be `/var/www/html` and “Local path” would be something like `/Users/rfay/workspace/drup` (on macOS) or `\\wsl$\Ubuntu\home\rfay\workspace\drup` on Windows using WSL2.
   5. Now back in the “Configure Remote PHP Interpreter” for “Configuration files” use `.ddev/.ddev-docker-compose-full.yaml`. On macOS, you may need to use <kbd>⌘</kbd> + <kbd>SHIFT</kbd> + <kbd>.</kbd>, to show hidden dotfiles.
   6. Service: `web`.
   7. Environment variables: Set the `COMPOSE_PROJECT_NAME` variable to the name of the project prefixed with `ddev`. In the `drup` example this would become `ddev-drup`. You can find the name of the project in je `config.yaml` of your project. The result will be `COMPOSE_PROJECT_NAME=ddev-drup`. Note that the content of COMPOSE\_PROJECT\_NAME needs to be lowercase even when project name itself has uppercase characters.
   8. In the CLI interpreter “Lifecycle” select “Connect to existing container”.
   9. Here’s an example filled out: ![example configuration](<https://ddev.github.io/ddev/en/stable/images/phpstorm-cli-interpreter.png>)
6. In the main PHP setup dialog, add an entry to the path mappings, as it doesn’t correctly derive the full path mapping. Add an entry that maps your project location to `/var/www/html`. So in this example, the “Local Path” is `/Users/rfay/workspace/drup` and the “Remote Path” is `/var/www/html`: ![example mapping](<https://ddev.github.io/ddev/en/stable/images/phpstorm-mapping.png>)
7. Configure composer under *PHP* → *Composer*.

   - Use “remote interpreter”
   - CLI Interpreter will be “web”

## Enabling PHPUnit

This assumes you’ll need to use PHPUnit and you already have it installed.

1. Under “Test Frameworks” click “+” to add PHPUnit.

   - PHPUnit by remote interpreter
   - Interpreter “DDEV”
   - Choose “Path to phpunit.phar” and use `/var/www/html/vendor/bin/phpunit`, or wherever your PHPUnit is inside the container. You need PHPUnit properly Composer-installed for your project. For example, for Drupal 10, `ddev composer require --dev --with-all-dependencies drupal/core-dev:^10` and `ddev composer require --dev phpspec/prophecy-phpunit:^2`.
   - Default configuration file: `/var/www/html/web/core/phpunit.xml` or wherever yours is inside the container. ![Example config](<https://ddev.github.io/ddev/en/stable/images/phpstorm-phpunit-setup.png>)
2. Open Run/Debug configurations and use “+” to add a PHPUnit configuration. Give it a name.

   - Test scope (as you wish, by directory or class or whatever).
   - Interpreter: “web” (the one we set up). ![Run-debug configuration](<https://ddev.github.io/ddev/en/stable/images/phpstorm-run-debug-config.png>)
3. Enable Xdebug if you want to debug tests with `ddev xdebug on`.
4. Run the runner you created: ![Example PHPUnit run](<https://ddev.github.io/ddev/en/stable/images/phpstorm-example-phpunit-run.png>)

## PhpStorm Basic Setup on Windows WSL2

It’s possible to use PhpStorm with DDEV on WSL2 in at least three different ways:

1. Run PhpStorm in Windows as usual, opening the project on the WSL2 filesystem at `\\wsl$\<distro>` (e.g. `\\wsl$\Ubuntu`). PhpStorm is slow to index files but can be slow to respond to file changes in this mode, although it’s adequate for many people.
2. “Remote Development” in PhpStorm 2022.3+, which has explicit support for WSL2 and actually runs a PhpStorm instance on WSL2.
3. Enabling X11 on Windows and running PhpStorm inside WSL2 as a Linux app. PhpStorm works fine this way; it does require WSL2 graphics support, which is now available on all Windows 10 and Windows 11 systems.

We’ll walk through each of these approaches.

### Basics

- Start with a working DDEV/WSL2 setup as described in the [docs](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>). Until that’s all working it doesn’t help to go farther.
- If you haven’t used Xdebug with DDEV and PhpStorm before, you’ll want to read the [step debugging instructions](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>).
- Your project absolutely must be in `/home` inside WSL2, which is on the Linux filesystem. Although you could keep your project on the Windows filesystem and access it in WSL2 via `/mnt/c`, the performance is even worse than native Windows. It does work though, but don’t do it. You’ll be miserable.

### PhpStorm Running On Windows Side and Using Docker Desktop

With the [DDEV Integration Plugin](<https://plugins.jetbrains.com/plugin/18813-ddev-integration>) almost everything is already done for you, so use it. Create your project inside WSL2 (on the `/home` partition) and get it started first.

1. Your working project will be on the `/home` partition, so you’ll open it using Windows PhpStorm as `\\wsl$\Ubuntu\home\<username>\...\<projectdir>`.
2. On some systems and some projects it may take a very long time for PhpStorm to index the files.
3. File changes are noticed only by polling, and PhpStorm will complain about this in the lower right, “External file changes sync may be slow”.
4. Temporarily disable your Windows firewall. When you have everything working, you can turn it back on again.
5. Use `ddev start` and `ddev xdebug on`.
6. Click the Xdebug listen button on PhpStorm (the little phone icon) to make it start listening.
7. Set a breakpoint on or near the first line of your `index.php`.
8. Visit the project with a web browser or cURL. You should get a popup asking for mapping of the host-side files to the in-container files. Make sure `/home/<you>/.../<yourproject>` is mapped to `/var/www/html`.

Debugging should be working. You can step through your code, set breakpoints, view variables, etc.

Set the PhpStorm terminal path (*Settings* → *Tools* → *Terminal* → *Shell Path*) to `C:\Windows\System32\wsl.exe`. That way when you use the terminal Window in WSL2 it’s using the Bash shell in WSL2.

### PhpStorm with “Remote Development” Option

1. Open your WSL2 project using *File* → *Remote Development* → *WSL* and choose the distro, then the project.
2. For Xdebug you’ll want to use `ddev config global --xdebug-ide-location=wsl2` because essentially the IDE is running inside WSL2 (and listening there).
3. Use `ddev xdebug on` as normal; test with a simple breakpoint in your `index.php`.

### PhpStorm Inside WSL2 in Linux

1. On Windows 10 or 11 get “Windows Subsystem for Linux” from the Microsoft Store, which now includes graphical support.
2. Edit `/etc/wsl.conf` to enable systemd support, which allows for installing PhpStorm with snap, see [details about WSL2 and systemd](<https://devblogs.microsoft.com/commandline/systemd-support-is-now-available-in-wsl/>):

   ```
   [boot]
   systemd=true
   ```
3. Run `wsl --shutdown` on the Windows side and wait 10 seconds, then restart your distro.
4. In WSL2, `sudo snap install --classic phpstorm`.
5. DDEV should already be installed as described in [DDEV installation](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#windows>).
6. `ddev config global --xdebug-ide-location=wsl2` to tell DDEV that the IDE is listening in WSL2 as opposed to listening on the Windows side.
7. Start PhpStorm, `phpstorm &`.
8. Use `ddev start` and `ddev xdebug on`.
9. Click the Xdebug listen button in PhpStorm (the little phone icon) to make it start listening.
10. Set a breakpoint on or near the first line of your `index.php`.
11. Visit the project with a web browser or cURL. You should get a popup asking for mapping of the host-side files to the in-container files. Make sure `/home/<you>/.../<yourproject>` is mapped to `/var/www/html`.

Debugging should be working! You can step through your code, set breakpoints, view variables, etc.

# Shell Completion &amp; Autocomplete

Most people like to have shell completion on the command line. In other words, when you’re typing a command, you can hit `<TAB>` and the shell will show you what the options are. For example, if you type `ddev <TAB>`, you’ll see all the possible commands. `ddev utility <TAB>` will show you the options for the command. And `ddev list -<TAB>` will show you all the flags available for [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>).

Shells like Bash and Zsh need help to do this though, they have to know what the options are. DDEV provides the necessary hint scripts, and if you use Homebrew, they get installed automatically.

## macOS Bash with Homebrew

The easiest way to use Bash completion on macOS is install it with Homebrew ([docs](<https://docs.brew.sh/Shell-Completion#configuring-completions-in-bash>)). `brew install bash-completion`. When you install it though, it will warn you with something like this, which **may vary on your system**. Add the following line to your `~/.bash_profile` file (or if that doesn’t exist, to your `~/.profile`:

```
[[ -r "$(brew --prefix)/etc/profile.d/bash_completion.sh" ]] && . "$(brew --prefix)/etc/profile.d/bash_completion.sh"
```

> [!NOTE]
>
> **Bash profile**
>
> You must add the include to your `.bash_profile` or `.profile` or nothing will work. Use `source ~/.bash_profile` or `source ~/.profile` to make it take effect immediately in your current terminal window.

Link completions by running `brew completions link`.

When you install DDEV via Homebrew, each new release will automatically get a refreshed completions script.

## macOS Zsh with Homebrew

To make Homebrew completions available in Zsh the Homebrew-managed path `zsh/site-functions` has to be added to the FPATH variable.

Add the following block to your `~/.zshrc` file (see [docs](<https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh>)):

```
if type brew &>/dev/null
then
  FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}"
  autoload -Uz compinit
  compinit
fi
```

Note that the updating of the FPATH variable has to happen before the Zsh completion index is initialized with `compinit`.

Oh My Zsh is calling `compinit` for you when `oh-my-zsh.sh` is sourced (see [docs](<https://docs.brew.sh/Shell-Completion#configuring-completions-in-zsh>)). Instead of adding the block that was necessary for `macOS Zsh` place the following line right before the `oh-my-zsh.sh` file is sourced in your `~/.zshrc` file:

```
FPATH="$(brew --prefix)/share/zsh/site-functions:${FPATH}"
```

To avoid any potential caching issue remove and rebuild the `.zcompdump` file, which is the index for Zsh completions:

```
rm -f ~/.zcompdump; compinit
```

In case you run into any `zsh compinit: insecure directories` warnings, run:

```
chmod -R go-w "$(brew --prefix)/share"
```

## macOS Fish with Homebrew

`fish` shell completions are automatically installed at `/usr/local/share/fish/vendor_completions.d/ddev_fish_completion.sh` when you install DDEV via Homebrew.

If you installed `fish` without Homebrew, you can extract the fish completions (`ddev_fish_completion.sh`) from the tar archive of completion scripts included with each release. See [below](<#tar-archive-of-completion-scripts-for-manual-deployment>).

## Bash/Zsh/Fish on Linux including WSL2

On Debian and Yum based systems, if you installed DDEV using `apt-get install ddev`, the `bash`, `zsh`, and `fish` completions should be automatically installed at `/usr/share/bash-completion/completions/ddev`, `/usr/share/zsh/vendor-completions/_ddev` and `/usr/share/fish/completions/ddev.fish` respectively, and the `bash` completions should be automatically installed at `/usr/share/bash-completion/completions/bash`.

Otherwise, you can download the completion files for manual installation as described [below](<#tar-archive-of-completion-scripts-for-manual-deployment>). Every Linux distro requires a different manual installation technique. On Debian/Ubuntu, you could deploy the `ddev_bash_completion.sh` script where it needs to be by running `sudo mkdir -p /usr/share/bash-completion/completions && sudo cp ddev_bash_completion.sh /usr/share/bash-completion/completions/ddev`.

## Git Bash

Git Bash completions (`ddev_bash_completion.sh`) are provided in the tar archive of completion scripts included with each release. See [below](<#tar-archive-of-completion-scripts-for-manual-deployment>).

Completions in Git Bash are sourced from at least the `~/bash_completion.d` directory. You can copy `ddev_bash_completion.sh` to that directory by running `mkdir -p ~/bash_completion.d && cp ddev_bash_completion.sh ~/bash_completion.d/ddev.bash`.

## PowerShell

PowerShell completions (`ddev_powershell_completion.ps1`) are provided in the tar archive of completion scripts included with each release. See [below](<#tar-archive-of-completion-scripts-for-manual-deployment>).

You can run the `ddev_powershell_completion.ps1` script manually or install it so it will be run whenever PS is opened using the technique described at [Run PowerShell Script When You Open PowerShell](<https://superuser.com/questions/886951/run-powershell-script-when-you-open-powershell>).

## tar Archive of Completion Scripts for Manual Deployment

Although most people will use techniques like Homebrew for installation, a tar archive of shell completion scripts for various shells is available in each release, called `ddev_shell_completion_scripts.<version>.tar.gz`. If you need to manually install, you can download the files and extract them with the following commands, replacing the VERSION number in the first line with your version:

```
VERSION=v1.24.0
curl -sSLf https://github.com/ddev/ddev/releases/download/${VERSION}/ddev_shell_completion_scripts.${VERSION}.tar.gz
tar -zxf ddev_shell_completion_scripts.${VERSION}.tar.gz
```

Alternatively, you could download the tar archive using a browser, from a URL such as the following, replacing the version numbers with your version: [https://github.com/ddev/ddev/releases/download/v1.22.6/ddev\_shell\_completion\_scripts.v1.22.6.tar.gz](<https://github.com/ddev/ddev/releases/download/v1.22.6/ddev_shell_completion_scripts.v1.22.6.tar.gz>).

After extracting the archive, copy the appropriate completion script where you need it, for example by running `sudo cp ddev_bash_completion.sh /etc/bash_completion.d/ddev`. Detailed instructions for various shells are given above.

# Starting a Project

Once [DDEV is installed](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>), setting up a new project should be quick:

1. Clone or create the code for your project.
2. `cd` into the project directory and run [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) to initialize a DDEV project.
3. Run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) to spin up the project.
4. Run [`ddev launch`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#launch>) to open your project in a browser.

You can also type `ddev` to manage your projects from an [interactive dashboard](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#interactive-dashboard>).

DDEV can automatically detect your project type and docroot. If it guessed wrong or there’s something else you want to change, use the [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) command or update [project options](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>) by editing `.ddev/config.yaml`. You can see the result by running [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>).

> [!TIP]
>
> **What is the `php` project type?**
>
> A `php` project type is the most general, ready for whatever modern PHP or static HTML/JS project you might be working on. It’s as full-featured as other [CMS-specific options](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>), without any assumptions about your configuration or presets. (You can use this with a CMS or framework fine!)

If you need to configure your app to connect to the database, the hostname, username, password, and database name are all `db`.

While you’re getting your bearings, use [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) to get project details, and [`ddev help`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#help>) to investigate commands.

Next, you may want to run [`ddev composer install`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>), [import a database](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>), or [load user-managed files](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-files>).

If you’re new to DDEV, check out [Using the `ddev` Command](<https://ddev.github.io/ddev/en/stable/users/usage/cli/index.md>) for an overview of what’s available.

# CMS Quickstarts

DDEV is [ready to go](<https://ddev.github.io/ddev/en/stable/users/project/index.md>) with generic project types for PHP frameworks, and more specific project types for working with popular platforms and CMSes. To learn more about how to manage projects in DDEV visit [Managing Projects](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/index.md>).

Before proceeding, make sure your installation of DDEV is up to date. In a new and empty project folder, using your favorite shell, run the following commands:

## Asterios

Use a new or existing Composer project, or clone a Git repository.

The Asterios project type can be used for [Scaffolding](<https://github.com/asteriosframework/asterios-app>) and others, as it is used with basic Asterios. DDEV automatically updates or creates the `.env` file with the database information.

Create the project directory and configure DDEV:

```
mkdir -p my-asterios-site && cd my-asterios-site
ddev config --project-type=asterios --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Asterios via Composer:

```
ddev composer create-project asterios/app
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-asterios.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-asterios-site && cd my-asterios-site
> ddev config --project-type=asterios --docroot=public
> ddev start -y
> ddev composer create-project asterios/app
> ddev launch
> EOF
> chmod +x setup-asterios.sh
> ./setup-asterios.sh
> ```

## Backdrop

You can start a new [Backdrop](<https://backdropcms.org>) project or configure an existing one.

Create the project directory and configure DDEV:

```
mkdir -p my-backdrop-site && cd my-backdrop-site
ddev config --project-type=backdrop
# Add the official Bee CLI add-on
ddev add-on get backdrop-ops/ddev-backdrop-bee
```

Start DDEV (this may take a minute):

```
ddev start
```

Download Backdrop core and create admin user:

```
# Download Backdrop core
ddev bee download-core
# Create admin user
ddev bee si --username=admin --password=Password123 --db-name=db --db-user=db --db-pass=db --db-host=db --auto
```

Launch the site:

```
# Login using `admin` user and `Password123` password
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-backdrop.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-backdrop-site && cd my-backdrop-site
> ddev config --project-type=backdrop
> ddev add-on get backdrop-ops/ddev-backdrop-bee
> ddev start -y
> ddev bee download-core
> ddev bee si --username=admin --password=Password123 --db-name=db --db-user=db --db-pass=db --db-host=db --auto
> ddev launch
> EOF
> chmod +x setup-backdrop.sh
> ./setup-backdrop.sh
> ```

You can start using DDEV with an existing project, too—but make sure you have a database backup handy!

Create project directory and clone your repository:

```
mkdir -p my-backdrop-site && cd my-backdrop-site
git clone https://github.com/ddev/test-backdrop.git .
```

Configure DDEV:

```
ddev config --project-type=backdrop
```

Add the official Bee CLI add-on:

```
ddev add-on get backdrop-ops/ddev-backdrop-bee
```

Start DDEV (this may take a minute):

```
ddev start
```

Import database and files backups:

```
ddev import-db --file=/path/to/db.sql.gz
ddev import-files --source=/path/to/files.tar.gz
ddev bee cc all
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-backdrop-existing.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-backdrop-site && cd my-backdrop-site
> git clone https://github.com/ddev/test-backdrop.git .
> ddev config --project-type=backdrop
> ddev add-on get backdrop-ops/ddev-backdrop-bee
> ddev start -y
> ddev import-db --file=/path/to/db.sql.gz
> ddev import-files --source=/path/to/files.tar.gz
> ddev bee cc all
> ddev launch
> EOF
> chmod +x setup-backdrop-existing.sh
> ./setup-backdrop-existing.sh
> ```

## CakePHP

You can start a new [CakePHP](<https://cakephp.org>) project or configure an existing one.

The CakePHP project type can be used with any CakePHP project \>= 3.x, but it has been fully tested with CakePHP 5.x. DDEV automatically creates the `.env` file with the database information, email transport configuration and a random salt. If `.env` file already exists, `.env.ddev` will be created, so you can take any variable and put it into your `.env` file.

Please note that you will need to change the PHP version to 7.4 to be able to work with CakePHP 3.x.

Create the project directory and configure DDEV:

```
mkdir -p my-cakephp-composer-site && cd my-cakephp-composer-site
ddev config --project-type=cakephp --docroot=webroot
```

Start DDEV (this may take a minute):

```
ddev start
```

Install CakePHP via Composer:

```
ddev composer create-project --prefer-dist --no-interaction cakephp/app:~5.0
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-cakephp.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-cakephp-composer-site && cd my-cakephp-composer-site
> ddev config --project-type=cakephp --docroot=webroot
> ddev start -y
> ddev composer create-project --prefer-dist --no-interaction cakephp/app:~5.0
> ddev launch
> EOF
> chmod +x setup-cakephp.sh
> ./setup-cakephp.sh
> ```

Clone the repository and configure DDEV:

```
git clone <my-cakephp-repo> my-cakephp-git-site
cd my-cakephp-git-site
ddev config --project-type=cakephp --docroot=webroot
```

Start DDEV (this may take a minute):

```
ddev start
```

Install dependencies and launch:

```
ddev composer install
ddev cake
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-cakephp-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> git clone <my-cakephp-repo> my-cakephp-git-site
> cd my-cakephp-git-site
> ddev config --project-type=cakephp --docroot=webroot
> ddev start -y
> ddev composer install
> ddev cake
> ddev launch
> EOF
> chmod +x setup-cakephp-git.sh
> ./setup-cakephp-git.sh
> ```

## CiviCRM (Standalone)

[CiviCRM Standalone](<https://civicrm.org/blog/ufundo/next-steps-civicrm-standalone>) allows running [CiviCRM](<https://civicrm.org/>) without a CMS. Visit [Install CiviCRM (Standalone)](<https://docs.civicrm.org/installation/en/latest/standalone>) for more installation details.

Create the project directory and configure DDEV:

```
mkdir -p my-civicrm-site && cd my-civicrm-site
ddev config --project-type=php --composer-root=core --upload-dirs=public/media
```

Start DDEV (this may take a minute):

```
ddev start
```

Download and extract CiviCRM:

```
ddev exec "curl -fsSL https://download.civicrm.org/latest/civicrm-STABLE-standalone.tar.gz -o /tmp/civicrm-standalone.tar.gz"
ddev exec "tar --strip-components=1 -xzf /tmp/civicrm-standalone.tar.gz"
ddev composer require civicrm/cli-tools --no-scripts
```

Install CiviCRM (or use `ddev launch` to install manually):

```
# You can install CiviCRM manually in your browser using `ddev launch`
# and selecting `db` for the server and `db` for database/username/password
# or do the same automatically using the command below:
# The parameter `-m loadGenerated=1` includes sample data
ddev exec cv core:install \
    --cms-base-url='$DDEV_PRIMARY_URL' \
    --db=mysql://db:db@db/db \
    -m loadGenerated=1 \
    -m extras.adminUser=admin \
    -m extras.adminPass=admin \
    -m extras.adminEmail=admin@example.com
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-civicrm.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-civicrm-site && cd my-civicrm-site
> ddev config --project-type=php --composer-root=core --upload-dirs=public/media
> ddev start -y
> ddev exec "curl -fsSL https://download.civicrm.org/latest/civicrm-STABLE-standalone.tar.gz -o /tmp/civicrm-standalone.tar.gz"
> ddev exec "tar --strip-components=1 -xzf /tmp/civicrm-standalone.tar.gz"
> ddev composer require civicrm/cli-tools --no-scripts
> ddev exec cv core:install \
>     --cms-base-url='$DDEV_PRIMARY_URL' \
>     --db=mysql://db:db@db/db \
>     -m loadGenerated=1 \
>     -m extras.adminUser=admin \
>     -m extras.adminPass=admin \
>     -m extras.adminEmail=admin@example.com
> ddev launch
> EOF
> chmod +x setup-civicrm.sh
> ./setup-civicrm.sh
> ```

## CodeIgniter

Use a new or existing Composer project, or clone a Git repository.

DDEV automatically updates or creates the `.env` file with the database information.

Create the project directory and configure DDEV:

```
mkdir -p my-ci4-site && cd my-ci4-site
ddev config --project-type=codeigniter --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install CodeIgniter via Composer:

```
ddev composer create-project codeigniter4/appstarter
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-codeigniter.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-ci4-site && cd my-ci4-site
> ddev config --project-type=codeigniter --docroot=public
> ddev start -y
> ddev composer create-project codeigniter4/appstarter
> ddev launch
> EOF
> chmod +x setup-codeigniter.sh
> ./setup-codeigniter.sh
> ```

## Contao

Further information on the DDEV procedure can also be found in the [Contao documentation](<https://docs.contao.org/manual/en/guides/local-installation/ddev/>).

Create the project directory and configure DDEV:

```
mkdir -p my-contao-composer-site && cd my-contao-composer-site
ddev config --project-type=php --docroot=public --webserver-type=apache-fpm --php-version=8.4
```

Install Contao via Composer (this may take a minute):

```
ddev composer create-project contao/managed-edition:5.7
```

Configure database and mailer settings:

```
ddev dotenv set .env.local --database-url=mysql://db:db@db:3306/db --mailer-dsn=smtp://localhost:1025
```

Create the database:

```
ddev exec contao-console contao:migrate --no-interaction
```

Create backend user:

```
ddev exec contao-console contao:user:create --username=admin --name=Administrator --email=admin@example.com --language=en --password=Password123 --admin
```

Launch the administration area:

```
ddev launch contao
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-contao.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-contao-composer-site && cd my-contao-composer-site
> ddev config --project-type=php --docroot=public --webserver-type=apache-fpm --php-version=8.4
> ddev composer create-project contao/managed-edition:5.7
> ddev dotenv set .env.local --database-url=mysql://db:db@db:3306/db --mailer-dsn=smtp://localhost:1025
> ddev exec contao-console contao:migrate --no-interaction
> ddev exec contao-console contao:user:create --username=admin --name=Administrator --email=admin@example.com --language=en --password=Password123 --admin
> ddev launch contao
> EOF
> chmod +x setup-contao.sh
> ./setup-contao.sh
> ```

Like most PHP projects, Contao could be installed and updated with Composer. The [Contao Manager](<https://docs.contao.org/manual/en/installation/contao-manager/>) is a tool that provides a graphical user interface to manage a Contao installation.

Create the project directory and configure DDEV:

```
mkdir -p my-contao-manager-site && cd my-contao-manager-site
ddev config --project-type=php --docroot=public --webserver-type=apache-fpm --php-version=8.4
```

Configure database and mailer settings:

```
ddev dotenv set .env.local --database-url=mysql://db:db@db:3306/db --mailer-dsn=smtp://localhost:1025
```

Start DDEV (this may take a minute):

```
ddev start
```

Download the Contao Manager:

```
ddev exec "wget -O public/contao-manager.phar.php https://download.contao.org/contao-manager/stable/contao-manager.phar"
```

Launch the Contao Manager and follow the setup wizard:

```
ddev launch contao-manager.phar.php
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-contao-manager.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-contao-manager-site && cd my-contao-manager-site
> ddev config --project-type=php --docroot=public --webserver-type=apache-fpm --php-version=8.4
> ddev dotenv set .env.local --database-url=mysql://db:db@db:3306/db --mailer-dsn=smtp://localhost:1025
> ddev start -y
> ddev exec "wget -O public/contao-manager.phar.php https://download.contao.org/contao-manager/stable/contao-manager.phar"
> ddev launch contao-manager.phar.php
> EOF
> chmod +x setup-contao-manager.sh
> ./setup-contao-manager.sh
> ```

The [Contao demo website](<https://demo.contao.org/>) is maintained for the currently supported Contao versions and can be [optionally installed](<https://github.com/contao/contao-demo>). Via the Contao Manager you can select this option during the first installation.

## Craft CMS

Start a new [Craft CMS](<https://craftcms.com>) project or retrofit an existing one.

DDEV injects a number of special environment variables into the container (via `.ddev/.env.web`) that [automatically configure](<https://craftcms.com/docs/5.x/configure.html#environment-overrides>) Craft’s database connection and the project’s primary site URL. You may opt out of this behavior with the [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) setting.

> [!TIP]
>
> **Compatibility with Craft CMS 3**
>
> The `craftcms` project works best with configuration features that became available in Craft CMS 4.x. If you are using Craft CMS 3.x or earlier, you may want to use the `php` project type and explicitly define [database connection details](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#database-backends-and-defaults>) via [Craft’s `db.php`](<https://craftcms.com/docs/3.x/config/db-settings.html>).

Create the project directory and configure DDEV:

```
mkdir -p my-craft-site && cd my-craft-site
ddev config --project-type=craftcms --docroot=web
```

Start DDEV (this may take a minute):

```
ddev start
```

Scaffold a new project with Composer:

```
ddev composer create-project craftcms/craft
```

Craft’s setup wizard will start automatically!

[Third-party starter projects](<https://craftcms.com/knowledge-base/using-the-starter-project#community-starter-projects>) can be substituted for `craftcms/craft` when running `ddev composer create-project`.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-craft.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-craft-site && cd my-craft-site
> ddev config --project-type=craftcms --docroot=web
> ddev start -y
> ddev composer create-project craftcms/craft
> EOF
> chmod +x setup-craft.sh
> ./setup-craft.sh
> ```

You can start using DDEV with an existing Craft project, too. All you need is the codebase and a database backup!

Clone the repository (or navigate to a local project directory):

```
git clone https://github.com/example/example-site my-craft-site
cd my-craft-site
```

Configure DDEV:

```
ddev config --project-type=craftcms --docroot=web
```

Start DDEV and install Composer packages:

```
ddev start
ddev composer install
```

Import database backup and launch:

```
ddev craft db/restore /path/to/db.sql.gz
ddev launch
```

Craft CMS projects use MySQL 8.0, by default. You can override this setting (and the PHP version) during setup with [`config` command flags](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) or after setup via the [configuration files](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-craft-existing.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> git clone https://github.com/example/example-site my-craft-site
> cd my-craft-site
> ddev config --project-type=craftcms --docroot=web
> ddev start -y
> ddev composer install
> ddev craft db/restore /path/to/db.sql.gz
> ddev launch
> EOF
> chmod +x setup-craft-existing.sh
> ./setup-craft-existing.sh
> ```

### Running Craft in a Subdirectory

Set [`composer_root`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#composer_root>) to the subdirectory where Craft is installed. For example, `ddev config --composer-root=app`.

> [!TIP]
>
> **Installing Craft**
>
> Read more about installing Craft in the [official documentation](<https://craftcms.com/docs>).

## Drupal

Create the project directory and configure DDEV:

```
mkdir -p my-drupal11-site && cd my-drupal11-site
ddev config --project-type=drupal11 --docroot=web
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Drupal via Composer:

```
ddev composer create-project drupal/recommended-project
ddev composer require drush/drush
```

Run Drupal installation and launch:

```
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch
# or automatically log in with:
ddev launch $(ddev drush uli)
```

Read more about [Drupal Core](<https://new.drupal.org/about/overview/technical>) &amp; [Documentation](<https://www.drupal.org/docs>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal11.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-drupal11-site && cd my-drupal11-site
> ddev config --project-type=drupal11 --docroot=web
> ddev start -y
> ddev composer create-project drupal/recommended-project
> ddev composer require drush/drush
> ddev drush site:install --account-name=admin --account-pass=admin -y
> ddev launch
> EOF
> chmod +x setup-drupal11.sh
> ./setup-drupal11.sh
> ```

Create the project directory and configure DDEV:

```
mkdir -p my-drupalcms-site && cd my-drupalcms-site
ddev config --project-type=drupal11 --docroot=web
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Drupal CMS via Composer:

```
ddev composer create-project drupal/cms
# Note: recipe-unpack runs automatically in DDEV v1.25.0+
ddev composer drupal:recipe-unpack
```

Launch the site:

```
ddev launch
```

Read more about [Drupal CMS](<https://new.drupal.org/drupal-cms>) &amp; [Documentation](<https://new.drupal.org/docs/drupal-cms>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal-cms.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-drupalcms-site && cd my-drupalcms-site
> ddev config --project-type=drupal11 --docroot=web
> ddev start -y
> ddev composer create-project drupal/cms
> # Note: recipe-unpack runs automatically in DDEV v1.25.0+
> ddev composer drupal:recipe-unpack
> ddev launch
> EOF
> chmod +x setup-drupal-cms.sh
> ./setup-drupal-cms.sh
> ```

Create the project directory and configure DDEV:

```
mkdir -p my-drupal10-site && cd my-drupal10-site
ddev config --project-type=drupal10 --docroot=web
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Drupal via Composer:

```
ddev composer create-project "drupal/recommended-project:^10"
ddev composer require drush/drush
```

Run Drupal installation and launch:

```
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch
# or automatically log in with:
ddev launch $(ddev drush uli)
```

Read more about [Drupal Core](<https://new.drupal.org/about/overview/technical>) &amp; [Documentation](<https://www.drupal.org/docs>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal10.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-drupal10-site && cd my-drupal10-site
> ddev config --project-type=drupal10 --docroot=web
> ddev start -y
> ddev composer create-project "drupal/recommended-project:^10"
> ddev composer require drush/drush
> ddev drush site:install --account-name=admin --account-pass=admin -y
> ddev launch
> EOF
> chmod +x setup-drupal10.sh
> ./setup-drupal10.sh
> ```

Clone your Drupal repository:

```
git clone https://github.com/example/my-drupal-site
cd my-drupal-site
```

Configure DDEV (follow prompts):

```
ddev config
```

Start DDEV and launch:

```
ddev start
ddev launch /install.php
```

Drupal 7 doesn’t know how to redirect from the front page to `/install.php` if the database is not set up but the settings files *are* set up, so launching with `/install.php` gets you started with an installation. You can also run `drush site-install`, then `ddev exec drush site-install --yes`.

See [Importing a Database](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/#importing-a-database>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal67.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> git clone https://github.com/example/my-drupal-site
> cd my-drupal-site
> ddev config
> ddev start -y
> ddev launch /install.php
> EOF
> chmod +x setup-drupal67.sh
> ./setup-drupal67.sh
> ```

This example shows how to work on an existing Drupal project, using a clone of a test repository. Replace with your Git repository.

Clone your web project repository:

```
PROJECT_GIT_URL=https://github.com/ddev/test-drupal11.git
git clone ${PROJECT_GIT_URL} my-drupal11-site
cd my-drupal11-site
```

Configure and start DDEV:

```
ddev config --project-type=drupal11 --docroot=web
ddev start
```

Install dependencies and set up Drupal:

```
ddev composer install
ddev drush site:install --account-name=admin --account-pass=admin -y
```

Launch the site:

```
ddev launch
```

Read more about [Drupal Core](<https://new.drupal.org/about/overview/technical>) &amp; [Documentation](<https://www.drupal.org/docs>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> PROJECT_GIT_URL=https://github.com/ddev/test-drupal11.git
> git clone ${PROJECT_GIT_URL} my-drupal11-site
> cd my-drupal11-site
> ddev config --project-type=drupal11 --docroot=web
> ddev start -y
> ddev composer install
> ddev drush site:install --account-name=admin --account-pass=admin -y
> ddev launch
> EOF
> chmod +x setup-drupal-git.sh
> ./setup-drupal-git.sh
> ```

Those who want to try out the unreleased upcoming Drupal 12 can install it this way:

```
mkdir -p my-drupal12-site && cd my-drupal12-site
ddev config --project-type=drupal12 --docroot=web
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Drupal via Composer:

```
ddev composer create-project drupal/recommended-project:main-dev@dev
ddev composer require drush/drush
```

Run Drupal installation and launch:

```
ddev drush site:install --account-name=admin --account-pass=admin -y
ddev launch
# or automatically log in with:
ddev launch $(ddev drush uli)
```

Read more about [Drupal Core](<https://new.drupal.org/about/overview/technical>) &amp; [Documentation](<https://www.drupal.org/docs>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-drupal12.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-drupal12-site && cd my-drupal12-site
> ddev config --project-type=drupal12 --docroot=web
> ddev start -y
> ddev composer create-project drupal/recommended-project:main-dev@dev
> ddev composer require drush/drush
> ddev drush site:install --account-name=admin --account-pass=admin -y
> ddev launch
> EOF
> chmod +x setup-drupal12.sh
> ./setup-drupal12.sh
> ```

## ExpressionEngine

Create the project directory:

```
mkdir -p my-ee-zip-site && cd my-ee-zip-site
```

Download and extract the latest ExpressionEngine release:

```
DOWNLOAD_URL=$(curl -fsSL https://api.github.com/repos/ExpressionEngine/ExpressionEngine/releases/latest | docker run -i --rm ddev/ddev-utilities jq -r '.assets | map(select(.name | test("^ExpressionEngine.*\\.zip$")))[0].browser_download_url')
curl -fsSL -o ee.zip "${DOWNLOAD_URL}"
unzip ee.zip && rm -f ee.zip
```

Configure and start DDEV:

```
ddev config --database=mysql:8.0
ddev start
```

Launch the installation wizard:

```
ddev launch /admin.php
```

When the installation wizard prompts for database settings, enter `db` for the *DB Server Address*, *DB Name*, *DB Username*, and *DB Password*.

Visit your site.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-ee.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-ee-zip-site && cd my-ee-zip-site
> DOWNLOAD_URL=$(curl -fsSL https://api.github.com/repos/ExpressionEngine/ExpressionEngine/releases/latest | docker run -i --rm ddev/ddev-utilities jq -r '.assets | map(select(.name | test("^ExpressionEngine.*\\.zip$")))[0].browser_download_url')
> curl -fsSL -o ee.zip "${DOWNLOAD_URL}"
> unzip ee.zip && rm -f ee.zip
> ddev config --database=mysql:8.0
> ddev start -y
> ddev launch /admin.php
> EOF
> chmod +x setup-ee.sh
> ./setup-ee.sh
> ```

Follow these steps based on the [ExpressionEngine Git Repository README.md](<https://github.com/ExpressionEngine/ExpressionEngine#how-to-install>):

Create the project directory and clone the repository:

```
mkdir -p my-ee-git-site && cd my-ee-git-site
git clone https://github.com/ExpressionEngine/ExpressionEngine .
```

Configure and start DDEV:

```
ddev config --database=mysql:8.0
ddev start
```

Install Composer dependencies and prepare installation:

```
ddev composer install
touch system/user/config/config.php
echo "EE_INSTALL_MODE=TRUE" >.env.php
```

Launch the installation wizard:

```
ddev launch /admin.php
```

When the installation wizard prompts for database settings, enter `db` for the *DB Server Address*, *DB Name*, *DB Username*, and *DB Password*.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-ee-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-ee-git-site && cd my-ee-git-site
> git clone https://github.com/ExpressionEngine/ExpressionEngine .
> ddev config --database=mysql:8.0
> ddev start -y
> ddev composer install
> touch system/user/config/config.php
> echo "EE_INSTALL_MODE=TRUE" >.env.php
> ddev launch /admin.php
> EOF
> chmod +x setup-ee-git.sh
> ./setup-ee-git.sh
> ```

## Generic

The [`webserver_type: generic`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webserver_type>) allows you to define your own web server process(es) and exposed ports for projects that don’t use the standard `nginx-fpm` or `apache-fpm` configurations.

> [!TIP]
>
> **Looking for more advanced generic web server examples?**
>
> Check out the [Node.js](<#nodejs>) and [Wagtail](<#wagtail-python-generic>) examples below.
>
> See also the [ddev-frankenphp](<https://github.com/ddev/ddev-frankenphp>) add-on, which uses the `generic` webserver under the hood.

This trivial example demonstrates running PHP’s built-in web server inside DDEV’s web container. The `ddev-webserver` container will not start the default `nginx` or `php-fpm` daemons—the PHP built-in server will handle all requests. You probably wouldn’t find this useful compared to the normal `nginx-fpm` or `apache-fpm` configurations, but it’s offered here as an example of how the `generic` webserver type works.

Create the project directory and configure DDEV:

```
export GENERIC_SITENAME=my-generic-site
mkdir -p ${GENERIC_SITENAME} && cd ${GENERIC_SITENAME}
ddev config --project-type=php
```

Create a sample PHP info page:

```
echo "<?php phpinfo(); ?>" > index.php
```

Configure the web server to run PHP’s built-in server:

```
cat <<'EOF' > .ddev/config.php-server.yaml
webserver_type: generic
web_extra_daemons:
    - name: "php-server"
      command: "php -S 0.0.0.0:8000 -t \"${DDEV_DOCROOT:-.}\""
      directory: /var/www/html
web_extra_exposed_ports:
    - name: "php-server"
      container_port: 8000
      http_port: 80
      https_port: 443
EOF
```

Start DDEV (this may take a minute):

```
ddev start
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-generic.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> export GENERIC_SITENAME=my-generic-site
> mkdir -p ${GENERIC_SITENAME} && cd ${GENERIC_SITENAME}
> ddev config --project-type=php
> echo "<?php phpinfo(); ?>" > index.php
> cat <<'INNEREOF' > .ddev/config.php-server.yaml
> webserver_type: generic
> web_extra_daemons:
>     - name: "php-server"
>       command: "php -S 0.0.0.0:8000 -t \"${DDEV_DOCROOT:-.}\""
>       directory: /var/www/html
> web_extra_exposed_ports:
>     - name: "php-server"
>       container_port: 8000
>       http_port: 80
>       https_port: 443
> INNEREOF
> ddev start -y
> ddev launch
> EOF
> chmod +x setup-generic.sh
> ./setup-generic.sh
> ```

## Grav

Create the project directory and configure DDEV:

```
mkdir -p my-grav-composer-site && cd my-grav-composer-site
ddev config --php-version=8.3 --omit-containers=db
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Grav via Composer:

```
ddev composer create-project getgrav/grav
```

Install the [Admin2](<https://github.com/getgrav/grav-plugin-admin2>) plugin and launch:

```
ddev exec gpm install admin2 -y
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-grav.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-grav-composer-site && cd my-grav-composer-site
> ddev config --php-version=8.3 --omit-containers=db
> ddev start -y
> ddev composer create-project getgrav/grav
> ddev exec gpm install admin2 -y
> ddev launch
> EOF
> chmod +x setup-grav.sh
> ./setup-grav.sh
> ```

Create the project directory and clone Grav:

```
mkdir -p my-grav-git-site && cd my-grav-git-site
git clone -b master https://github.com/getgrav/grav.git .
```

Configure DDEV:

```
ddev config --php-version=8.3 --omit-containers=db
```

Start DDEV (this may take a minute):

```
ddev start
```

Install dependencies and initialize Grav:

```
ddev composer install
ddev exec grav install
```

Install the [Admin2](<https://github.com/getgrav/grav-plugin-admin2>) plugin and launch:

```
ddev exec gpm install admin2 -y
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-grav-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-grav-git-site && cd my-grav-git-site
> git clone -b master https://github.com/getgrav/grav.git .
> ddev config --php-version=8.3 --omit-containers=db
> ddev start -y
> ddev composer install
> ddev exec grav install
> ddev exec gpm install admin2 -y
> ddev launch
> EOF
> chmod +x setup-grav-git.sh
> ./setup-grav-git.sh
> ```

> [!TIP]
>
> **How to update?**
>
> Upgrade Grav core:
>
> ```
> ddev exec gpm selfupgrade -f
> ```
>
> Update plugins and themes:
>
> ```
> ddev exec gpm update -f
> ```

Visit the [Grav Documentation](<https://learn.getgrav.org/17>) for more information about Grav in general and visit [Local Development with DDEV](<https://learn.getgrav.org/17/webservers-hosting/local-development-with-ddev>) for more details about the usage of Grav with DDEV.

## Ibexa DXP

Install [Ibexa DXP](<https://www.ibexa.co>) OSS Edition.

Create the project directory and configure DDEV:

```
mkdir -p my-ibexa-site && cd my-ibexa-site
ddev config --project-type=symfony --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Ibexa via Composer:

```
ddev composer create-project ibexa/oss-skeleton
```

Run Ibexa installation:

```
ddev console ibexa:install --no-interaction
ddev console ibexa:graphql:generate-schema
```

Launch the admin interface:

```
ddev launch /admin/login
```

In the web browser, log into your account using `admin` and `publish`.

Visit [Ibexa documentation](<https://doc.ibexa.co/en/latest/getting_started/install_with_ddev/>) for more cases.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-ibexa.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-ibexa-site && cd my-ibexa-site
> ddev config --project-type=symfony --docroot=public
> ddev start -y
> ddev composer create-project ibexa/oss-skeleton
> ddev console ibexa:install --no-interaction
> ddev console ibexa:graphql:generate-schema
> ddev launch /admin/login
> EOF
> chmod +x setup-ibexa.sh
> ./setup-ibexa.sh
> ```

## Joomla

Create the project directory and download Joomla:

```
mkdir -p my-joomla-site && cd my-joomla-site
curl -fsSL -o joomla.zip "https://www.joomla.org/latest"
unzip joomla.zip && rm -f joomla.zip
```

Configure DDEV:

```
ddev config --project-type=joomla
```

Adjust `php.ini` settings for Joomla:

```
echo "display_errors = off" > .ddev/php/joomla.ini
echo "output_buffering = off" >> .ddev/php/joomla.ini
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Joomla:

```
ddev php installation/joomla.php install --site-name="My Joomla Site" --admin-user="Administrator" --admin-username=admin --admin-password=AdminAdmin1! --admin-email=admin@example.com --db-type=mysql --db-encryption=0 --db-host=db --db-user=db --db-pass="db" --db-name=db --db-prefix=ddev_ --public-folder=""
```

Launch the admin interface (login with `admin` and `AdminAdmin1!`):

```
ddev launch /administrator
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-joomla.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-joomla-site && cd my-joomla-site
> curl -fsSL -o joomla.zip "https://www.joomla.org/latest"
> unzip joomla.zip && rm -f joomla.zip
> ddev config --project-type=joomla
> echo "display_errors = off" > .ddev/php/joomla.ini
> echo "output_buffering = off" >> .ddev/php/joomla.ini
> ddev start -y
> ddev php installation/joomla.php install --site-name="My Joomla Site" --admin-user="Administrator" --admin-username=admin --admin-password=AdminAdmin1! --admin-email=admin@example.com --db-type=mysql --db-encryption=0 --db-host=db --db-user=db --db-pass="db" --db-name=db --db-prefix=ddev_ --public-folder=""
> ddev launch /administrator
> EOF
> chmod +x setup-joomla.sh
> ./setup-joomla.sh
> ```

## Kirby CMS

Start a new [Kirby CMS](<https://getkirby.com>) project or use an existing one.

Create a new Kirby CMS project from the official [Starterkit](<https://github.com/getkirby/starterkit>) using DDEV’s [`composer create-project` command](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>):

Create the project directory and configure DDEV:

```
mkdir -p my-kirby-site && cd my-kirby-site
ddev config --omit-containers=db --webserver-type=apache-fpm
```

Start DDEV (this may take a minute):

```
ddev start
```

Install the Kirby Starterkit:

```
ddev composer create-project getkirby/starterkit
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-kirby.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-kirby-site && cd my-kirby-site
> ddev config --omit-containers=db --webserver-type=apache-fpm
> ddev start -y
> ddev composer create-project getkirby/starterkit
> ddev launch
> EOF
> chmod +x setup-kirby.sh
> ./setup-kirby.sh
> ```

You can start using DDEV with an existing project as well:

Navigate to your existing project directory:

```
cd my-kirby-site
```

Configure DDEV:

```
ddev config --omit-containers=db --webserver-type=apache-fpm
```

Start DDEV (this may take a minute):

```
ddev start
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-kirby-existing.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> cd my-kirby-site
> ddev config --omit-containers=db --webserver-type=apache-fpm
> ddev start -y
> ddev launch
> EOF
> chmod +x setup-kirby-existing.sh
> ./setup-kirby-existing.sh
> ```

> [!TIP]
>
> **Installing Kirby**
>
> Read more about developing your Kirby project with DDEV in our [extensive DDEV guide](<https://getkirby.com/docs/cookbook/setup/ddev>).

## Laravel

Use a new or existing Composer project, or clone a Git repository.

The Laravel project type can be used for [StarterKits](<https://laravel.com/docs/starter-kits>), [Laravel Livewire](<https://livewire.laravel.com/>) and others, as it is used with basic Laravel. DDEV automatically updates or creates the `.env` file with the database information.

Laravel defaults to SQLite, but we use MariaDB to better mimic a production environment:

Create the project directory and configure DDEV:

```
mkdir -p my-laravel-composer-site && cd my-laravel-composer-site
ddev config --project-type=laravel --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Laravel via Composer:

```
ddev composer create-project laravel/laravel
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-laravel.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-laravel-composer-site && cd my-laravel-composer-site
> ddev config --project-type=laravel --docroot=public
> ddev start -y
> ddev composer create-project laravel/laravel
> ddev launch
> EOF
> chmod +x setup-laravel.sh
> ./setup-laravel.sh
> ```

To use the SQLite configuration provided by Laravel:

Create the project directory and configure DDEV:

```
mkdir -p my-laravel-sqlite-site && cd my-laravel-sqlite-site
ddev config --project-type=laravel --docroot=public --omit-containers=db
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Laravel via Composer:

```
ddev composer create-project laravel/laravel
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-laravel-sqlite.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-laravel-sqlite-site && cd my-laravel-sqlite-site
> ddev config --project-type=laravel --docroot=public --omit-containers=db
> ddev start -y
> ddev composer create-project laravel/laravel
> ddev launch
> EOF
> chmod +x setup-laravel-sqlite.sh
> ./setup-laravel-sqlite.sh
> ```

To switch an existing Laravel project to SQLite:

Configure for SQLite and restart:

```
ddev config --project-type=laravel --docroot=public --omit-containers=db
ddev restart
```

Run post-install scripts:

```
ddev composer run-script post-root-package-install
ddev dotenv set .env --db-connection=sqlite
ddev composer run-script post-create-project-cmd
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > switch-laravel-sqlite.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> ddev config --project-type=laravel --docroot=public --omit-containers=db
> ddev restart
> ddev composer run-script post-root-package-install
> ddev dotenv set .env --db-connection=sqlite
> ddev composer run-script post-create-project-cmd
> ddev launch
> EOF
> chmod +x switch-laravel-sqlite.sh
> ./switch-laravel-sqlite.sh
> ```

Create the project directory and configure DDEV:

```
mkdir -p my-laravel-installer-site && cd my-laravel-installer-site
ddev config --project-type=laravel --docroot=public
# For SQLite instead, use:
# ddev config --project-type=laravel --docroot=public --omit-containers=db
```

Create Dockerfile to add Laravel installer:

```
cat <<'DOCKERFILEEND' >.ddev/web-build/Dockerfile.laravel
ARG COMPOSER_HOME=/usr/local/composer
RUN composer global require laravel/installer
RUN ln -s $COMPOSER_HOME/vendor/bin/laravel /usr/local/bin/laravel
DOCKERFILEEND
```

Start DDEV (this may take a minute):

```
ddev start
```

Run Laravel installer (follow prompts and select starter kit):

```
ddev exec laravel new temp --database=sqlite
# SQLite is used here as other database types would fail due to
# the .env file not being ready, which DDEV will fix on 'ddev restart'
```

Move files and clean up:

```
ddev exec 'rsync -rltgopD temp/ ./ && rm -rf temp'
rm -f .ddev/web-build/Dockerfile.laravel .env
```

Restart and finalize:

```
ddev restart
ddev composer run-script post-root-package-install
ddev composer run-script post-create-project-cmd
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-laravel-installer.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-laravel-installer-site && cd my-laravel-installer-site
> ddev config --project-type=laravel --docroot=public
>
> cat <<'INNEREOF' >.ddev/web-build/Dockerfile.laravel
> ARG COMPOSER_HOME=/usr/local/composer
> RUN composer global require laravel/installer
> RUN ln -s $COMPOSER_HOME/vendor/bin/laravel /usr/local/bin/laravel
> INNEREOF
>
> ddev start -y
> ddev exec laravel new temp --database=sqlite
> ddev exec 'rsync -rltgopD temp/ ./ && rm -rf temp'
> rm -f .ddev/web-build/Dockerfile.laravel .env
> ddev restart
> ddev composer run-script post-root-package-install
> ddev composer run-script post-create-project-cmd
> ddev launch
> EOF
> chmod +x setup-laravel-installer.sh
> ./setup-laravel-installer.sh
> ```

Clone your Laravel repository:

```
git clone <my-laravel-repo> my-laravel-git-site
cd my-laravel-git-site
```

Configure and start DDEV:

```
ddev config --project-type=laravel --docroot=public
ddev start
```

Install dependencies and run post-install scripts:

```
ddev composer install
ddev composer run-script post-root-package-install
ddev composer run-script post-create-project-cmd
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-laravel-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> git clone <my-laravel-repo> my-laravel-git-site
> cd my-laravel-git-site
> ddev config --project-type=laravel --docroot=public
> ddev start -y
> ddev composer install
> ddev composer run-script post-root-package-install
> ddev composer run-script post-create-project-cmd
> ddev launch
> EOF
> chmod +x setup-laravel-git.sh
> ./setup-laravel-git.sh
> ```

> [!TIP]
>
> **Add Vite support?**
>
> Since Laravel v9.19, Vite is included as the default [asset bundler](<https://laravel.com/docs/vite>). See the [Vite Integration](<https://ddev.github.io/ddev/en/stable/users/usage/vite/#laravel>) documentation for complete setup instructions.

## Magento 2

Normal details of a Composer build for Magento 2 are on the [Magento 2 site](<https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/composer.html>). You must have a public and private key to install from Magento’s repository. When prompted for “username” and “password” in `composer create-project`, it’s asking for your public key as “username” and private key as “password”.

> [!TIP]
>
> **Store Adobe/Magento Composer credentials in the global DDEV config**
>
> If you have Composer installed on your workstation and have an `auth.json` you can reuse the `auth.json` by making a symlink. See the example in [Composer Authentication](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#composer-authentication>).
>
> Alternately, you can install the Adobe/Magento Composer credentials in your global `$HOME/.ddev/homeadditions/.composer/auth.json` and never have to enter them again (see below):
>
> **Script to store Adobe/Magento Composer credentials (click me)**
>
> ```
> # Enter your username/password and agree to store your credentials
> ddev_dir="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
> mkdir -p $ddev_dir/homeadditions/.composer
> docker_command=("docker" "run" "-it" "--rm" "-v" "$ddev_dir/homeadditions/.composer:/composer" "--workdir=/tmp" "-e" "COMPOSER_HOME=/composer" "--user" "$(id -u):$(id -g)")
> auth_json_path="$ddev_dir/homeadditions/.composer/auth.json"
> if [ -L "$auth_json_path" ]; then
>     # If auth.json is a symlink, add the optional mount
>     auth_json_dir=$(dirname "$(readlink -f "$auth_json_path")")
>     docker_command+=("-v" "$auth_json_dir:$auth_json_dir")
> fi
> image="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.web | select (.!=null)" 2>/dev/null)"
> docker_command+=("$image" "bash" "-c" "composer create-project --repository https://repo.magento.com/ magento/project-community-edition --no-install")
> # Execute the command to store credentials
> "${docker_command[@]}"
> ```

Create the project directory and configure DDEV:

```
export MAGENTO_HOSTNAME=my-magento2-site
mkdir -p ${MAGENTO_HOSTNAME} && cd ${MAGENTO_HOSTNAME}
ddev config --project-type=magento2 --docroot=pub --upload-dirs=media --disable-settings-management
ddev add-on get ddev/ddev-opensearch
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Magento via Composer:

```
ddev composer create-project --repository https://repo.magento.com/ magento/project-community-edition
rm -f app/etc/env.php
```

Run Magento setup:

```
ddev magento setup:install --base-url="https://${MAGENTO_HOSTNAME}.ddev.site/" \
    --cleanup-database --db-host=db --db-name=db --db-user=db --db-password=db \
    --opensearch-host=opensearch --search-engine=opensearch --opensearch-port=9200 \
    --admin-firstname=Magento --admin-lastname=User --admin-email=user@example.com \
    --admin-user=admin --admin-password=Password123 --language=en_US
```

Configure Magento and launch:

```
ddev magento deploy:mode:set developer
ddev magento module:disable Magento_TwoFactorAuth Magento_AdminAdobeImsTwoFactorAuth
ddev config --disable-settings-management=false
# Change the backend frontname URL to /admin_ddev
ddev magento setup:config:set --backend-frontname="admin_ddev" --no-interaction
# Login using `admin` user and `Password123` password
ddev launch /admin_ddev
```

Change the admin name and related information as needed.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-magento.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> export MAGENTO_HOSTNAME=my-magento2-site
> mkdir -p ${MAGENTO_HOSTNAME} && cd ${MAGENTO_HOSTNAME}
> ddev config --project-type=magento2 --docroot=pub --upload-dirs=media --disable-settings-management
> ddev add-on get ddev/ddev-opensearch
> ddev start -y
> ddev composer create-project --repository https://repo.magento.com/ magento/project-community-edition
> rm -f app/etc/env.php
> ddev magento setup:install --base-url="https://${MAGENTO_HOSTNAME}.ddev.site/" \
>     --cleanup-database --db-host=db --db-name=db --db-user=db --db-password=db \
>     --opensearch-host=opensearch --search-engine=opensearch --opensearch-port=9200 \
>     --admin-firstname=Magento --admin-lastname=User --admin-email=user@example.com \
>     --admin-user=admin --admin-password=Password123 --language=en_US
> ddev magento deploy:mode:set developer
> ddev magento module:disable Magento_TwoFactorAuth Magento_AdminAdobeImsTwoFactorAuth
> ddev config --disable-settings-management=false
> ddev magento setup:config:set --backend-frontname="admin_ddev" --no-interaction
> ddev launch /admin_ddev
> EOF
> chmod +x setup-magento.sh
> ./setup-magento.sh
> ```

The admin login URL is specified by `frontName` in `app/etc/env.php`.

You may want to add the [Magento 2 Sample Data](<https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/next-steps/sample-data/composer-packages.html>) with:

```
ddev magento sampledata:deploy
ddev magento setup:upgrade
```

## Maho

You can start a new [Maho](<https://mahocommerce.com>) project or configure an existing one. Maho is an e-commerce platform derived from Magento 1, with modern PHP support and no external service requirements: it needs only a web server, PHP and a database.

DDEV automatically creates `app/etc/local.xml` with the database connection details, so importing an existing site is just `ddev import-db` and `ddev import-files` away. For a fresh installation the Maho installer needs `--force` to take over that pre-created file.

Create the project directory and configure DDEV:

```
mkdir -p my-maho-site && cd my-maho-site
ddev config --project-type=maho --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Maho via Composer:

```
ddev composer create-project mahocommerce/maho-starter
```

Run the Maho installer with sample data:

```
ddev maho install --force \
  --license_agreement_accepted yes \
  --locale en_US --timezone UTC --default_currency USD \
  --db_host db --db_name db --db_user db --db_pass db \
  --url "$(ddev exec echo '$DDEV_PRIMARY_URL')" \
  --use_secure 1 --secure_base_url "$(ddev exec echo '$DDEV_PRIMARY_URL')" --use_secure_admin 1 \
  --admin_firstname Store --admin_lastname Admin --admin_email admin@example.com \
  --admin_username admin --admin_password veryl0ngpassw0rd \
  --sample_data 1
```

Re-index and flush the cache:

```
ddev maho index:reindex:all && ddev maho cache:flush
```

Launch the admin interface (login with `admin` and `veryl0ngpassw0rd`):

```
ddev launch /admin
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-maho.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-maho-site && cd my-maho-site
> ddev config --project-type=maho --docroot=public
> ddev start -y
> ddev composer create-project mahocommerce/maho-starter
> ddev maho install --force \
>   --license_agreement_accepted yes \
>   --locale en_US --timezone UTC --default_currency USD \
>   --db_host db --db_name db --db_user db --db_pass db \
>   --url "$(ddev exec echo '$DDEV_PRIMARY_URL')" \
>   --use_secure 1 --secure_base_url "$(ddev exec echo '$DDEV_PRIMARY_URL')" --use_secure_admin 1 \
>   --admin_firstname Store --admin_lastname Admin --admin_email admin@example.com \
>   --admin_username admin --admin_password veryl0ngpassw0rd \
>   --sample_data 1
> ddev maho index:reindex:all && ddev maho cache:flush
> ddev launch /admin
> EOF
> chmod +x setup-maho.sh
> ./setup-maho.sh
> ```

> [!WARNING]
>
> **For contributing to Maho core only**
>
> This setup is only for contributing to Maho itself. Never build a store on a clone of the core repository — use the Composer setup instead.

Create the project directory and clone the repository:

```
mkdir -p maho && cd maho
git clone https://github.com/MahoCommerce/maho .
```

Configure and start DDEV:

```
ddev config --project-type=maho --docroot=public
ddev start
```

Install Composer dependencies:

```
ddev composer install
```

Run the Maho installer with sample data:

```
ddev maho install --force \
  --license_agreement_accepted yes \
  --locale en_US --timezone UTC --default_currency USD \
  --db_host db --db_name db --db_user db --db_pass db \
  --url "$(ddev exec echo '$DDEV_PRIMARY_URL')" \
  --use_secure 1 --secure_base_url "$(ddev exec echo '$DDEV_PRIMARY_URL')" --use_secure_admin 1 \
  --admin_firstname Store --admin_lastname Admin --admin_email admin@example.com \
  --admin_username admin --admin_password veryl0ngpassw0rd \
  --sample_data 1
```

Re-index and flush the cache:

```
ddev maho index:reindex:all && ddev maho cache:flush
```

Launch the admin interface (login with `admin` and `veryl0ngpassw0rd`):

```
ddev launch /admin
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-maho-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p maho && cd maho
> git clone https://github.com/MahoCommerce/maho .
> ddev config --project-type=maho --docroot=public
> ddev start -y
> ddev composer install
> ddev maho install --force \
>   --license_agreement_accepted yes \
>   --locale en_US --timezone UTC --default_currency USD \
>   --db_host db --db_name db --db_user db --db_pass db \
>   --url "$(ddev exec echo '$DDEV_PRIMARY_URL')" \
>   --use_secure 1 --secure_base_url "$(ddev exec echo '$DDEV_PRIMARY_URL')" --use_secure_admin 1 \
>   --admin_firstname Store --admin_lastname Admin --admin_email admin@example.com \
>   --admin_username admin --admin_password veryl0ngpassw0rd \
>   --sample_data 1
> ddev maho index:reindex:all && ddev maho cache:flush
> ddev launch /admin
> EOF
> chmod +x setup-maho-git.sh
> ./setup-maho-git.sh
> ```

## MODX Revolution

DDEV supports both [MODX](<https://modx.com/>) Revolution 2.x and 3.x.

Create the project directory and configure DDEV:

```
mkdir -p my-modx-site && cd my-modx-site
ddev config --project-type=modx
```

Start DDEV (this may take a minute):

```
ddev start
```

Install MODX Revolution via Composer:

```
ddev composer create-project modx/revolution
```

Create the project directory:

```
mkdir -p my-modx-site && cd my-modx-site
```

Download the latest MODX Revolution release and extract it. The archive extracts into a versioned subdirectory, so move its contents up to the project root:

```
MODX_VERSION=$(curl -fsSL https://api.github.com/repos/modxcms/revolution/tags | grep -o '"v[0-9][0-9.]*-pl"' | head -1 | tr -dc '0-9.')
curl -fLo modx.zip "https://modx.s3.amazonaws.com/releases/${MODX_VERSION}/modx-${MODX_VERSION}-pl.zip"
unzip -q modx.zip && rm -f modx.zip
(shopt -s dotglob && mv "modx-${MODX_VERSION}-pl"/* .) && rmdir "modx-${MODX_VERSION}-pl"
```

Set `MODX_VERSION` yourself to install a specific release, for example `MODX_VERSION=2.8.9` for MODX Revolution 2.x. Releases are also listed on [modx.com](<https://modx.com/download>).

Configure and start DDEV:

```
ddev config --project-type=modx
ddev start
```

DDEV generates a `#ddev-generated` `core/config/config.inc.php` with the DDEV database credentials (database name, user, and password are all `db`; host is `db`). Install MODX with the CLI installer, which performs a fresh install using those credentials:

```
ddev php setup/cli-install.php \
  --database_server=db --database=db --database_user=db --database_password=db \
  --table_prefix=modx_ --http_host=my-modx-site.ddev.site \
  --cmsadmin=admin --cmspassword=Admin123! --cmsadminemail=admin@example.com --language=en \
  --context_mgr_path=/var/www/html/manager/ --context_mgr_url=/manager/ \
  --context_connectors_path=/var/www/html/connectors/ --context_connectors_url=/connectors/
```

The four `--context_*` arguments are the installer’s own defaults. Passing them explicitly keeps the install non-interactive; leave them out and the installer stops to ask for each one.

Launch the manager (log in with `admin` / `Admin123!`):

```
ddev launch /manager/
```

> [!NOTE]
>
> **Web installer and the DDEV-managed config**
>
> You can also install through the web wizard with `ddev launch /setup/`. Because DDEV has already written a valid `core/config/config.inc.php`, MODX opens the web wizard in *upgrade* mode; for a brand-new site use the CLI installer above (or remove `core/config/config.inc.php` before opening `/setup/`). When you import an existing MODX site and its database (for example with [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>)), the DDEV-generated `config.inc.php` connects it straight away with no installer step.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-modx.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-modx-site && cd my-modx-site
> ddev config --project-type=modx
> ddev start -y
> ddev composer create-project modx/revolution
> ddev php setup/cli-install.php \
>   --database_server=db --database=db --database_user=db --database_password=db \
>   --table_prefix=modx_ --http_host=my-modx-site.ddev.site \
>   --cmsadmin=admin --cmspassword=Admin123! --cmsadminemail=admin@example.com --language=en \
>   --context_mgr_path=/var/www/html/manager/ --context_mgr_url=/manager/ \
>   --context_connectors_path=/var/www/html/connectors/ --context_connectors_url=/connectors/
> ddev launch /manager/
> EOF
> chmod +x setup-modx.sh
> ./setup-modx.sh
> ```

## Moodle

Create the project directory and configure DDEV:

```
mkdir -p my-moodle-site && cd my-moodle-site
ddev config --docroot=public --webserver-type=apache-fpm
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Moodle via Composer:

```
ddev composer create-project moodle/moodle
```

Run Moodle installation:

```
ddev exec 'php admin/cli/install.php --non-interactive --agree-license --wwwroot=$DDEV_PRIMARY_URL --dbtype=mariadb --dbhost=db --dbname=db --dbuser=db --dbpass=db --fullname="DDEV Moodle Demo" --shortname=Demo --adminemail=admin@example.com --adminpass=password'
```

Launch Moodle (login with `admin` and `password`)::

```
ddev launch /login
```

Visit the [Moodle Admin Quick Guide](<https://docs.moodle.org/400/en/Admin_quick_guide>) for more information.

> [!TIP]
>
> Moodle relies on a periodic cron job—don’t forget to set that up! See [ddev/ddev-cron](<https://github.com/ddev/ddev-cron>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-moodle.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-moodle-site && cd my-moodle-site
> ddev config --docroot=public --webserver-type=apache-fpm
> ddev start -y
> ddev composer create-project moodle/moodle
> ddev exec 'php admin/cli/install.php --non-interactive --agree-license --wwwroot=$DDEV_PRIMARY_URL --dbtype=mariadb --dbhost=db --dbname=db --dbuser=db --dbpass=db --fullname="DDEV Moodle Demo" --shortname=Demo --adminemail=admin@example.com --adminpass=password'
> ddev launch /login
> EOF
> chmod +x setup-moodle.sh
> ./setup-moodle.sh
> ```

## Node.js

This example installation sets up the SvelteKit demo in DDEV with the `generic` webserver.

Node.js support as in this example is experimental, and your suggestions and improvements are welcome.

```
export SVELTEKIT_SITENAME=my-sveltekit-site
mkdir -p ${SVELTEKIT_SITENAME} && cd ${SVELTEKIT_SITENAME}
ddev config --project-type=generic --webserver-type=generic
ddev start

cat <<EOF > .ddev/config.sveltekit.yaml
web_extra_exposed_ports:
    - name: svelte
      container_port: 3000
      http_port: 80
      https_port: 443
web_extra_daemons:
    - name: "sveltekit-demo"
      command: "node build"
      directory: /var/www/html
EOF

# When it prompts "Directory not empty. Continue?", choose Yes
ddev exec "npx sv create --template=demo --types=ts --no-add-ons --no-install ."

# Use adapter-node, and set the port and allowed hosts in vite.config.ts
ddev exec "sed -i -e 's#adapter-auto#adapter-node#' -e 's#^export default defineConfig({#&\n\tserver: { port: 3000, allowedHosts: true },#' vite.config.ts"
ddev npm install @sveltejs/adapter-node
ddev npm install
ddev npm run build
ddev restart
ddev launch
```

SvelteKit requires just a bit of configuration to make it run. There are many ways to make any Node.js site work, these are just examples. SvelteKit 3 no longer uses `svelte.config.js`; its configuration is passed to the `sveltekit()` plugin in `vite.config.ts`, which can be adapted in many ways. For more Vite configuration options, see the [Vite Integration](<https://ddev.github.io/ddev/en/stable/users/usage/vite/index.md>) documentation.

- The `sed` command switches the adapter from `adapter-auto` to `adapter-node`.
- It also sets `server.port` to 3000 and `server.allowedHosts` to `true` in `vite.config.ts`.

```
export NODEJS_SITENAME=my-nodejs-site
mkdir -p ${NODEJS_SITENAME} && cd ${NODEJS_SITENAME}
ddev config --project-type=generic --webserver-type=generic
ddev start
ddev npm install express

cat <<EOF > .ddev/config.nodejs.yaml
web_extra_exposed_ports:
    - name: node-example
      container_port: 3000
      http_port: 80
      https_port: 443

web_extra_daemons:
    - name: "node-example"
      command: "node server.js"
      directory: /var/www/html
EOF

ddev exec curl -fsSLO https://raw.githubusercontent.com/ddev/test-nodejs/main/server.js
ddev restart
ddev launch
```

The [`server.js`](<https://github.com/ddev/test-nodejs/blob/main/server.js>) used here is a trivial Express-based Node.js webserver. Yours will be more extensive.

## OpenMage

Visit [OpenMage Docs](<https://docs.openmage.org>) for more installation details.

Create the project directory and configure DDEV:

```
mkdir -p my-openmage-composer-site && cd my-openmage-composer-site
ddev config --project-type=magento --docroot=public_test --php-version=8.3 --web-environment-add=MAGE_IS_DEVELOPER_MODE=1
```

Start DDEV (this may take a minute):

```
ddev start
```

Initialize and configure Composer:

```
ddev composer init --name "openmage/composer-test" --description "OpenMage starter project" --type "project" -l "OSL-3.0" -s "dev" -q
ddev composer config prefer-stable true
ddev composer config policy.advisories.block false
ddev composer config extra.magento-root-dir "public_test"
ddev composer config extra.magento-core-package-type "magento-source"
ddev composer config allow-plugins.vaimo/composer-patches true
ddev composer config allow-plugins.magento-hackathon/magento-composer-installer true
ddev composer config allow-plugins.aydin-hassan/magento-core-composer-installer true
ddev composer config allow-plugins.openmage/composer-plugin true
ddev composer require --no-update "aydin-hassan/magento-core-composer-installer":"^2.1.0" "openmage/magento-lts":"^20.19"
```

Download the OpenMage install command and install dependencies:

```
ddev exec wget -O .ddev/commands/web/openmage-install https://raw.githubusercontent.com/OpenMage/magento-lts/refs/heads/main/.ddev/commands/web/openmage-install
ddev composer install
```

Run OpenMage silent installation with sample data:

```
ddev openmage-install -q
```

Launch the admin interface (login with `admin` and `veryl0ngpassw0rd`):

```
ddev launch /admin
```

> [!NOTE]
>
> **Make sure that `docroot` is set correctly**
>
> DDEV config `--docroot` has to match Composer config `extra.magento-root-dir`.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-openmage.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-openmage-composer-site && cd my-openmage-composer-site
> ddev config --project-type=magento --docroot=public_test --php-version=8.3 --web-environment-add=MAGE_IS_DEVELOPER_MODE=1
> ddev start -y
> ddev composer init --name "openmage/composer-test" --description "OpenMage starter project" --type "project" -l "OSL-3.0" -s "dev" -q
> ddev composer config prefer-stable true
> ddev composer config policy.advisories.block false
> ddev composer config extra.magento-root-dir "public_test"
> ddev composer config extra.magento-core-package-type "magento-source"
> ddev composer config allow-plugins.vaimo/composer-patches true
> ddev composer config allow-plugins.magento-hackathon/magento-composer-installer true
> ddev composer config allow-plugins.aydin-hassan/magento-core-composer-installer true
> ddev composer config allow-plugins.openmage/composer-plugin true
> ddev composer require --no-update "aydin-hassan/magento-core-composer-installer":"^2.1.0" "openmage/magento-lts":"^20.19"
> ddev exec wget -O .ddev/commands/web/openmage-install https://raw.githubusercontent.com/OpenMage/magento-lts/refs/heads/main/.ddev/commands/web/openmage-install
> ddev composer install
> ddev openmage-install -q
> ddev launch /admin
> EOF
> chmod +x setup-openmage.sh
> ./setup-openmage.sh
> ```

Create the project directory and clone the repository:

```
mkdir -p my-openmage-git-site && cd my-openmage-git-site
git clone https://github.com/OpenMage/magento-lts .
```

Configure and start DDEV:

```
ddev config --project-type=magento --php-version=8.3 --web-environment-add=MAGE_IS_DEVELOPER_MODE=1
ddev start
```

Install Composer dependencies:

```
ddev composer install
```

Run OpenMage silent installation with sample data:

```
ddev openmage-install -q
```

Launch the admin interface (login with `admin` and `veryl0ngpassw0rd`):

```
ddev launch /admin
```

Note that OpenMage itself provides several custom DDEV commands, including `openmage-install`, `openmage-admin`, `phpmd`, `rector`, `phpcbf`, `phpstan`, `vendor-patches`, and `php-cs-fixer`.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-openmage-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-openmage-git-site && cd my-openmage-git-site
> git clone https://github.com/OpenMage/magento-lts .
> ddev config --project-type=magento --php-version=8.3 --web-environment-add=MAGE_IS_DEVELOPER_MODE=1
> ddev start -y
> ddev composer install
> ddev openmage-install -q
> ddev launch /admin
> EOF
> chmod +x setup-openmage-git.sh
> ./setup-openmage-git.sh
> ```

## October CMS

Start a new [October CMS](<https://octobercms.com>) project or configure an existing one.

October CMS is built on Laravel, so it uses the `laravel` project type. DDEV automatically updates or creates the `.env` file with the database information.

Create the project directory and configure DDEV:

```
mkdir -p my-october-site && cd my-october-site
ddev config --project-type=laravel --webserver-type=apache-fpm
```

Start DDEV (this may take a minute):

```
ddev start
```

Install October CMS via Composer:

```
ddev composer create-project october/october
```

Run the installer:

```
ddev artisan october:install --no-interaction
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-october.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-october-site && cd my-october-site
> ddev config --project-type=laravel --webserver-type=apache-fpm
> ddev start -y
> ddev composer create-project october/october
> ddev artisan october:install --no-interaction
> ddev launch
> EOF
> chmod +x setup-october.sh
> ./setup-october.sh
> ```

You can start using DDEV with an existing October CMS project too — but make sure you have a database backup handy!

Clone the repository (or navigate to a local project directory):

```
git clone <my-october-repo> my-october-site
cd my-october-site
```

Configure DDEV:

```
ddev config --project-type=laravel --webserver-type=apache-fpm
```

Start DDEV and install dependencies:

```
ddev start
ddev composer install
```

Import your database and run migrations:

```
ddev import-db --file=/path/to/db.sql.gz
ddev artisan october:migrate
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-october-existing.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> git clone <my-october-repo> my-october-site
> cd my-october-site
> ddev config --project-type=laravel --webserver-type=apache-fpm
> ddev start -y
> ddev composer install
> ddev import-db --file=/path/to/db.sql.gz
> ddev artisan october:migrate
> ddev launch
> EOF
> chmod +x setup-october-existing.sh
> ./setup-october-existing.sh
> ```

> [!TIP]
>
> **Installing October CMS**
>
> Read more about installing October CMS in the [official documentation](<https://docs.octobercms.com/3.x/setup/installation.html>).

## Pimcore

Using the [Pimcore skeleton](<https://github.com/pimcore/skeleton>) repository:

Create the project directory and configure DDEV:

```
mkdir -p my-pimcore-site && cd my-pimcore-site
ddev config --project-type=php --docroot=public --webimage-extra-packages='php${DDEV_PHP_VERSION}-amqp'
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Pimcore via Composer:

```
ddev composer create-project pimcore/skeleton
```

Run Pimcore installation:

```
ddev exec pimcore-install \
    --mysql-username=db \
    --mysql-password=db \
    --mysql-host-socket=db \
    --mysql-database=db \
    --admin-password=admin \
    --admin-username=admin
```

Create consumer daemon configuration:

```
echo "web_extra_daemons:
  - name: consumer
    command: 'while true; do /var/www/html/bin/console messenger:consume pimcore_core pimcore_maintenance pimcore_scheduled_tasks pimcore_image_optimize pimcore_asset_update --memory-limit=250M --time-limit=3600; done'
    directory: /var/www/html" >.ddev/config.pimcore.yaml
```

Restart and launch:

```
ddev restart
ddev launch /admin
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-pimcore.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-pimcore-site && cd my-pimcore-site
> ddev config --project-type=php --docroot=public --webimage-extra-packages='php${DDEV_PHP_VERSION}-amqp'
> ddev start -y
> ddev composer create-project pimcore/skeleton
> ddev exec pimcore-install \
>     --mysql-username=db \
>     --mysql-password=db \
>     --mysql-host-socket=db \
>     --mysql-database=db \
>     --admin-password=admin \
>     --admin-username=admin
> echo "web_extra_daemons:
>   - name: consumer
>     command: 'while true; do /var/www/html/bin/console messenger:consume pimcore_core pimcore_maintenance pimcore_scheduled_tasks pimcore_image_optimize pimcore_asset_update --memory-limit=250M --time-limit=3600; done'
>     directory: /var/www/html" >.ddev/config.pimcore.yaml
> ddev restart
> ddev launch /admin
> EOF
> chmod +x setup-pimcore.sh
> ./setup-pimcore.sh
> ```

## ProcessWire

To get started with [ProcessWire](<https://processwire.com/>), create a new directory and use the ZIP file download, composer, or Git checkout to build. These instructions are adapted from [ProcessWire Install Documentation](<https://processwire.com/docs/start/install/new/#installing-processwire>).

Create the project directory:

```
mkdir -p my-processwire-zip-site && cd my-processwire-zip-site
```

Download and extract ProcessWire:

```
curl -LJOf https://github.com/processwire/processwire/archive/master.zip
unzip processwire-master.zip && rm -f processwire-master.zip
cp -R processwire-master/. . && rm -rf processwire-master
```

Configure and start DDEV:

```
ddev config --project-type=php --webserver-type=apache-fpm
ddev start
```

Launch ProcessWire:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-processwire-zip.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-processwire-zip-site && cd my-processwire-zip-site
> curl -LJOf https://github.com/processwire/processwire/archive/master.zip
> unzip processwire-master.zip && rm -f processwire-master.zip
> cp -R processwire-master/. . && rm -rf processwire-master
> ddev config --project-type=php --webserver-type=apache-fpm
> ddev start -y
> ddev launch
> EOF
> chmod +x setup-processwire-zip.sh
> ./setup-processwire-zip.sh
> ```

Create the project directory and configure DDEV:

```
mkdir -p my-processwire-composer-site && cd my-processwire-composer-site
ddev config --project-type=php --webserver-type=apache-fpm
```

Start DDEV (this may take a minute):

```
ddev start
```

Install ProcessWire via Composer:

```
ddev composer create-project "processwire/processwire:^3"
```

Launch ProcessWire:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-processwire.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-processwire-composer-site && cd my-processwire-composer-site
> ddev config --project-type=php --webserver-type=apache-fpm
> ddev start -y
> ddev composer create-project "processwire/processwire:^3"
> ddev launch
> EOF
> chmod +x setup-processwire.sh
> ./setup-processwire.sh
> ```

Create the project directory:

```
mkdir -p my-processwire-git-site && cd my-processwire-git-site
```

Clone ProcessWire (main branch for stable release):

```
git clone https://github.com/processwire/processwire.git .
# For latest features, use dev branch instead:
# git clone -b dev https://github.com/processwire/processwire.git .
```

Configure and start DDEV:

```
ddev config --webserver-type=apache-fpm
ddev start
```

Launch ProcessWire:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-processwire-git.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-processwire-git-site && cd my-processwire-git-site
> git clone https://github.com/processwire/processwire.git .
> ddev config --webserver-type=apache-fpm
> ddev start -y
> ddev launch
> EOF
> chmod +x setup-processwire-git.sh
> ./setup-processwire-git.sh
> ```

When the installation wizard prompts for database settings, enter:

- `DB Name` = `db`
- `DB User` = `db`
- `DB Pass` = `db`
- `DB Host` = `db` (**not** `localhost`!)
- `DB Charset` = `utf8mb4`
- `DB Engine` = `InnoDB`

If you get a warning about “Apache mod\_rewrite” during the compatibility check, Click “refresh”.

**After installation,** configure `upload_dirs` to specify where user-generated files are managed by Processwire:

```
ddev config --upload-dirs=sites/assets/files && ddev restart
```

## Shopware

Though you can set up a Shopware 6 environment many ways, we recommend the following technique. DDEV creates a `.env.local` file for you by default; if you already have one DDEV adds necessary information to it. When `ddev composer create-project` asks if you want to include Docker configuration, answer `x`, as this approach does not use their Docker configuration.

Create the project directory and configure DDEV:

```
mkdir -p my-shopware-site && cd my-shopware-site
ddev config --project-type=shopware6 --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Shopware via Composer:

```
ddev composer create-project shopware/production
# If it asks `Do you want to include Docker configuration from recipes?`
# answer `x`, as we're using DDEV for this rather than its recipes.
```

Run Shopware installation and launch:

```
ddev console system:install --basic-setup
ddev launch /admin
# Default username and password are `admin` and `shopware`
```

Log into the admin site (`/admin`) using the web browser. The default credentials are username `admin` and password `shopware`. You can use the web UI to install sample data or accomplish many other tasks.

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-shopware.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-shopware-site && cd my-shopware-site
> ddev config --project-type=shopware6 --docroot=public
> ddev start -y
> # Answer `x` to "Do you want to include Docker configuration from recipes?"
> # so Shopware's Docker recipe is not added (DDEV provides the environment).
> printf "x\n" | ddev composer create-project shopware/production
> ddev console system:install --basic-setup
> ddev launch /admin
> EOF
> chmod +x setup-shopware.sh
> ./setup-shopware.sh
> ```

For more advanced tasks, such as

- setting up workers and the scheduler as automated tasks,
- installing additional services like RabbitMQ, or
- mirroring production media through an nginx proxy,

see [notebook.vanwittlaer.de](<https://notebook.vanwittlaer.de/ddev-for-shopware/>).

### shopware-cli and hot-reload watchers

For `shopware6` projects, DDEV bundles the [`shopware-cli`](<https://github.com/shopware/shopware-cli>) tool and hot-reload watcher commands automatically, with no add-on required. The `shopware-cli` binary is baked into the web image, and these commands become available:

- `ddev shopware-cli` — run `shopware-cli` inside the web container
- `ddev storefront-watch` — hot-reload the storefront (proxy on port 9998)
- `ddev admin-watch <plugin-dir>` — hot-reload a plugin’s administration (Vite, port 5173)

Reach the watchers through your project’s primary URL with the relevant port, for example `https://my-shopware-site.ddev.site:9998` for the storefront, not `localhost`.

> [!NOTE]
>
> **Requires Shopware 6.7.4.2 or newer**
>
> The bundled watchers target the Vite-based administration (port 5173) introduced in Shopware 6.7.4.2. Older Shopware versions use a different watcher setup.

## Silverstripe CMS

Use a new or existing Composer project, or clone a Git repository.

Create the project directory and configure DDEV:

```
mkdir -p my-silverstripe-composer-site && cd my-silverstripe-composer-site
ddev config --project-type=silverstripe --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Silverstripe via Composer:

```
ddev composer create-project --prefer-dist silverstripe/installer
ddev sake dev/build flush=all
```

Launch the admin area:

```
ddev launch /admin
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-silverstripe.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-silverstripe-composer-site && cd my-silverstripe-composer-site
> ddev config --project-type=silverstripe --docroot=public
> ddev start -y
> ddev composer create-project --prefer-dist silverstripe/installer
> ddev sake dev/build flush=all
> ddev launch /admin
> EOF
> chmod +x setup-silverstripe.sh
> ./setup-silverstripe.sh
> ```

```
git clone <my-silverstripe-repo> my-silverstripe-git-site
cd my-silverstripe-git-site
ddev config --project-type=silverstripe --docroot=public
ddev start
ddev composer install
ddev sake dev/build flush=all
```

Your Silverstripe CMS project is now ready. The CMS can be found at `/admin`, log into the default admin account using `admin` and `password`.

Visit the Silverstripe CMS [user documentation](<https://userhelp.silverstripe.org/>) and [developer documentation](<https://docs.silverstripe.org/>) for more information.

`ddev sake` can be used as a shorthand for the Silverstripe CLI command `ddev exec vendor/bin/sake`.

To open the CMS directly from CLI, run `ddev launch /admin`.

## Statamic

Use a new or existing Composer project, or clone a Git repository.

The Laravel project type can be used for [Statamic](<https://statamic.com/>) like it can for Laravel. DDEV automatically updates or creates the `.env` file with the database information.

Create the project directory and configure DDEV:

```
mkdir -p my-statamic-composer-site && cd my-statamic-composer-site
ddev config --project-type=laravel --docroot=public
```

Install Statamic via Composer:

```
ddev composer create-project --prefer-dist statamic/statamic
```

Create admin user and launch:

```
ddev php please make:user admin@example.com --password=admin1234 --super --no-interaction
ddev launch /cp
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-statamic.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-statamic-composer-site && cd my-statamic-composer-site
> ddev config --project-type=laravel --docroot=public
> ddev composer create-project --prefer-dist statamic/statamic
> ddev php please make:user admin@example.com --password=admin1234 --super --no-interaction
> ddev launch /cp
> EOF
> chmod +x setup-statamic.sh
> ./setup-statamic.sh
> ```

```
git clone <my-statamic-repo> my-statamic-git-site
cd my-statamic-git-site
ddev config --project-type=laravel --docroot=public
ddev start
ddev composer install
ddev exec "php artisan key:generate"
ddev launch /cp
```

## Sulu

Create the project directory and configure DDEV:

```
mkdir -p my-sulu-site && cd my-sulu-site
ddev config --project-type=php --docroot=public --upload-dirs=uploads --database=mysql:8.0
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Sulu via Composer:

```
ddev composer create-project sulu/skeleton
```

Create your default webspace configuration `mv config/webspaces/website.xml config/webspaces/my-sulu-site.xml` and adjust the values for `<name>` and `<key>` so that they are matching your project:

```
<?xml version="1.0" encoding="utf-8"?>
<webspace xmlns="http://schemas.sulu.io/webspace/webspace"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://schemas.sulu.io/webspace/webspace http://schemas.sulu.io/webspace/webspace-1.1.xsd">
    <!-- See: http://docs.sulu.io/en/latest/book/webspaces.html how to configure your webspace-->

    <name>My Sulu Site</name>
    <key>my-sulu-site</key>
```

Alternatively, use the following commands to adjust the values for `<name>` and `<key>` to match your project setup:

Configure webspace settings:

```
export SULU_PROJECT_NAME="My Sulu Site"
export SULU_PROJECT_KEY="my-sulu-site"
export SULU_PROJECT_CONFIG_FILE="config/webspaces/my-sulu-site.xml"
ddev exec "mv config/webspaces/website.xml ${SULU_PROJECT_CONFIG_FILE}"
ddev exec "sed -i -e 's|<name>.*</name>|<name>${SULU_PROJECT_NAME}</name>|g' -e 's|<key>.*</key>|<key>${SULU_PROJECT_KEY}</key>|g' ${SULU_PROJECT_CONFIG_FILE}"
```

> [!WARNING]
>
> **Caution**
>
> Changing the `<key>` for a webspace later on causes problems. It is recommended to decide on the value for the key before the database is build in the next step.

Build the database with the `dev` argument (adds user `admin` with password `admin`):

```
ddev dotenv set .env.local --app-env=dev --database-url="mysql://db:db@db:3306/db?serverVersion=8.0&charset=utf8mb4"
ddev exec bin/adminconsole sulu:build dev --no-interaction
```

Launch Sulu (login with `admin` and `admin`):

```
ddev launch /admin
```

> [!TIP]
>
> If you don’t want to add an admin user use the `prod` argument instead
>
> ```
> ddev execute bin/adminconsole sulu:build prod
> ```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-sulu.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-sulu-site && cd my-sulu-site
> ddev config --project-type=php --docroot=public --upload-dirs=uploads --database=mysql:8.0
> ddev start -y
> ddev composer create-project sulu/skeleton
> export SULU_PROJECT_NAME="My Sulu Site"
> export SULU_PROJECT_KEY="my-sulu-site"
> export SULU_PROJECT_CONFIG_FILE="config/webspaces/my-sulu-site.xml"
> ddev exec "mv config/webspaces/website.xml ${SULU_PROJECT_CONFIG_FILE}"
> ddev exec "sed -i -e 's|<name>.*</name>|<name>${SULU_PROJECT_NAME}</name>|g' -e 's|<key>.*</key>|<key>${SULU_PROJECT_KEY}</key>|g' ${SULU_PROJECT_CONFIG_FILE}"
> ddev dotenv set .env.local --app-env=dev --database-url="mysql://db:db@db:3306/db?serverVersion=8.0&charset=utf8mb4"
> ddev exec bin/adminconsole sulu:build dev --no-interaction
> ddev launch /admin
> EOF
> chmod +x setup-sulu.sh
> ./setup-sulu.sh
> ```

## Symfony

There are many ways to install Symfony, here are a few of them based on the [Symfony docs](<https://symfony.com/doc/current/setup.html>).

DDEV automatically updates or creates the `.env.local` file with the database information.

Create the project directory and configure DDEV:

```
mkdir -p my-symfony-composer-site && cd my-symfony-composer-site
ddev config --project-type=symfony --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Symfony via Composer, pinned to the current [long-term support (LTS) release](<https://symfony.com/doc/current/setup.html#symfony-lts-versions>):

```
ddev composer create-project symfony/skeleton:"7.4.*"
ddev composer require webapp
# When it asks if you want to include docker configuration, say "no" with "x"
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-symfony.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-symfony-composer-site && cd my-symfony-composer-site
> ddev config --project-type=symfony --docroot=public
> ddev start -y
> ddev composer create-project symfony/skeleton:"7.4.*"
> ddev composer require webapp
> ddev launch
> EOF
> chmod +x setup-symfony.sh
> ./setup-symfony.sh
> ```

```
mkdir -p my-symfony-cli-site && cd my-symfony-cli-site
ddev config --project-type=symfony --docroot=public
ddev start
ddev exec symfony check:requirements
# --version=lts always resolves to the current long-term support release
ddev exec symfony new temp --webapp --version=lts
# 'symfony new' can't install in the current directory right away,
# so we use 'rsync' to move the installed files one level up
ddev exec 'rsync -rltgopD temp/ ./ && rm -rf temp'
ddev launch
```

```
git clone <my-symfony-repo> my-symfony-git-site
cd my-symfony-git-site
ddev config --project-type=symfony --docroot=public
ddev start
ddev composer install
ddev launch
```

> [!TIP]
>
> **Want to run Symfony Console (`bin/console`)?**
>
> ```
> ddev console list
> # ddev console doctrine:schema:update --force
> ```

> [!TIP]
>
> **Consuming Messages (Running the Worker)**
>
> Edit `.ddev/config.yaml` in your project directory and uncomment `post-start` hook to see `messenger:consume` command logs, and run:
>
> ```
> ddev exec symfony server:log
> ```

## Tempest

Create the project directory and configure DDEV:

```
PROJECT_NAME=my-tempest-site
mkdir -p ${PROJECT_NAME} && cd ${PROJECT_NAME}
ddev config --project-type=php --docroot=public --php-version=8.5 --omit-containers=db
```

Start DDEV (this may take a minute):

```
ddev start
```

Install Tempest via Composer:

```
ddev composer create-project tempest/app
```

Launch the site:

```
ddev launch
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-tempest.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> PROJECT_NAME=my-tempest-site
> mkdir -p ${PROJECT_NAME} && cd ${PROJECT_NAME}
> ddev config --project-type=php --docroot=public --php-version=8.5 --omit-containers=db
> ddev start -y
> ddev composer create-project tempest/app
> ddev launch
> EOF
> chmod +x setup-tempest.sh
> ./setup-tempest.sh
> ```

## TYPO3

Create the project directory and configure DDEV:

```
PROJECT_NAME=my-typo3-site
mkdir -p ${PROJECT_NAME} && cd ${PROJECT_NAME}
ddev config --project-type=typo3 --docroot=public
```

Start DDEV (this may take a minute):

```
ddev start
```

Install TYPO3 via Composer:

```
ddev composer create-project "typo3/cms-base-distribution:^14"
```

Install the Camino default theme [recommended for TYPO3 Core](<https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/Installation/Install.html>):

```
ddev composer require typo3/theme-camino
```

Run the TYPO3 setup:

```
ddev typo3 setup \
    --admin-user-password="Demo123*" \
    --driver=mysqli \
    --server-type=other \
    --dbname=db \
    --username=db \
    --password=db \
    --port=3306 \
    --host=db \
    --admin-username=admin \
    --admin-email=admin@example.com \
    --project-name="My TYPO3 site" \
    --force
```

Launch the site content:

```
ddev launch /camino
```

Launch the backend:

```
ddev launch /typo3/
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-typo3.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> PROJECT_NAME=my-typo3-site
> mkdir -p ${PROJECT_NAME} && cd ${PROJECT_NAME}
> ddev config --project-type=typo3 --docroot=public
> ddev start -y
> ddev composer create-project "typo3/cms-base-distribution:^14"
> ddev composer require typo3/theme-camino
> ddev typo3 setup \
>     --admin-user-password="Demo123*" \
>     --driver=mysqli \
>     --server-type=other \
>     --dbname=db \
>     --username=db \
>     --password=db \
>     --port=3306 \
>     --host=db \
>     --admin-username=admin \
>     --admin-email=admin@example.com \
>     --project-name="My TYPO3 site" \
>     --force
> ddev launch /camino
> ddev launch /typo3/
> EOF
> chmod +x setup-typo3.sh
> ./setup-typo3.sh
> ```

This example uses a clone of a test repository, `github.com/ddev/test-typo3.git`. Replace that with your git repository.

```
PROJECT_GIT_URL=https://github.com/ddev/test-typo3.git
PROJECT_NAME=my-typo3-site
mkdir -p ${PROJECT_NAME} && cd ${PROJECT_NAME}
git clone ${PROJECT_GIT_REPOSITORY} .
ddev config --project-type=typo3 --docroot=public
ddev start
ddev composer install
ddev exec touch public/FIRST_INSTALL
ddev launch /typo3/install.php
```

## Wagtail (Python, Generic)

[Wagtail](<https://wagtail.org/>) is a popular, open-source content management system built on the Django web framework. This quickstart installs Wagtail into the web image, as described in [Python Packages from `requirements.txt`](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#python-packages-from-requirementstxt>), and runs the Django development server.

Create the project directory and configure DDEV:

```
export WAGTAIL_SITENAME=my-wagtail-site
mkdir -p ${WAGTAIL_SITENAME} && cd ${WAGTAIL_SITENAME}
ddev config --project-type=generic --webserver-type=generic \
    --webimage-extra-packages=python3-venv \
    --web-environment-add=DJANGO_SETTINGS_MODULE=mysite.settings.dev \
    --omit-containers=db
```

Add a placeholder `requirements.txt` that installs Wagtail so it can create the project, a Django setting to detect HTTPS behind the [Traefik](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/index.md>) router, and the DDEV configuration:

```
echo wagtail > requirements.txt
mkdir -p mysite/settings
echo 'SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")' > mysite/settings/local.py
cat <<'EOF' > .ddev/docker-compose.wagtail.yaml
services:
  web:
    build:
      additional_contexts:
        project: ${DDEV_APPROOT}
EOF
cat <<'EOF' > .ddev/web-build/Dockerfile.wagtail
COPY --from=project --chmod=644 requirements.txt /tmp/requirements.txt
RUN install -d -o "$username" /opt/wagtail \
    && runuser -u "$username" -- python3 -m venv /opt/wagtail \
    && runuser -u "$username" -- /opt/wagtail/bin/pip install --no-cache-dir -r /tmp/requirements.txt \
    && echo 'export PATH="/opt/wagtail/bin:$PATH"' > /etc/bashrc/wagtail.bashrc
EOF
cat <<'EOF' > .ddev/config.wagtail.yaml
web_extra_daemons:
    - name: "wagtail"
      command: "python manage.py runserver 0.0.0.0:8000"
      directory: /var/www/html
web_extra_exposed_ports:
    - name: "wagtail"
      container_port: 8000
      http_port: 80
      https_port: 443
EOF
```

Start DDEV (this may take a minute):

```
ddev start
```

Create the Wagtail project, which replaces the placeholder with its own `requirements.txt`:

```
ddev exec "rm -f requirements.txt && wagtail start mysite ."
```

Run database migrations and create a superuser:

```
ddev exec python manage.py migrate --noinput
ddev exec "DJANGO_SUPERUSER_PASSWORD=admin python manage.py createsuperuser --username=admin --email=admin@example.com --noinput"
```

Restart DDEV to rebuild the virtual environment from Wagtail’s `requirements.txt` and start the server:

```
ddev restart
```

Launch the Wagtail admin interface (login with `admin` and `admin`):

```
ddev launch /admin
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-wagtail.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> export WAGTAIL_SITENAME=my-wagtail-site
> mkdir -p ${WAGTAIL_SITENAME} && cd ${WAGTAIL_SITENAME}
> ddev config --project-type=generic --webserver-type=generic \
>     --webimage-extra-packages=python3-venv \
>     --web-environment-add=DJANGO_SETTINGS_MODULE=mysite.settings.dev \
>     --omit-containers=db
> echo wagtail > requirements.txt
> mkdir -p mysite/settings
> echo 'SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")' > mysite/settings/local.py
> cat <<'INNEREOF' > .ddev/docker-compose.wagtail.yaml
> services:
>   web:
>     build:
>       additional_contexts:
>         project: ${DDEV_APPROOT}
> INNEREOF
> cat <<'INNEREOF' > .ddev/web-build/Dockerfile.wagtail
> COPY --from=project --chmod=644 requirements.txt /tmp/requirements.txt
> RUN install -d -o "$username" /opt/wagtail \
>     && runuser -u "$username" -- python3 -m venv /opt/wagtail \
>     && runuser -u "$username" -- /opt/wagtail/bin/pip install --no-cache-dir -r /tmp/requirements.txt \
>     && echo 'export PATH="/opt/wagtail/bin:$PATH"' > /etc/bashrc/wagtail.bashrc
> INNEREOF
> cat <<'INNEREOF' > .ddev/config.wagtail.yaml
> web_extra_daemons:
>     - name: "wagtail"
>       command: "python manage.py runserver 0.0.0.0:8000"
>       directory: /var/www/html
> web_extra_exposed_ports:
>     - name: "wagtail"
>       container_port: 8000
>       http_port: 80
>       https_port: 443
> INNEREOF
> ddev start -y
> ddev exec "rm -f requirements.txt && wagtail start mysite ."
> ddev exec python manage.py migrate --noinput
> ddev exec "DJANGO_SUPERUSER_PASSWORD=admin python manage.py createsuperuser --username=admin --email=admin@example.com --noinput"
> ddev restart
> ddev launch /admin
> EOF
> chmod +x setup-wagtail.sh
> ./setup-wagtail.sh
> ```

## WordPress

There are several easy ways to use DDEV with WordPress:

DDEV has built-in support for [WP-CLI](<https://wp-cli.org/>), the command-line interface for WordPress.

Create the project directory and configure DDEV:

```
mkdir -p my-wp-cli-site && cd my-wp-cli-site
# Create a new DDEV project inside the newly-created folder
# (Primary URL automatically set to `https://<folder>.ddev.site`)
ddev config --project-type=wordpress
```

Start DDEV (this may take a minute):

```
ddev start
```

Download WordPress:

```
ddev wp core download
```

Install WordPress (or use `ddev launch` to install via browser):

```
# You can launch in browser to finish installation:
# ddev launch
# OR use the following installation command
ddev wp core install --url="$(ddev exec echo '$DDEV_PRIMARY_URL')" --title='My WordPress site' --admin_user=admin --admin_password=admin --admin_email=admin@example.com
```

Launch WordPress admin dashboard:

```
ddev launch wp-admin/
```

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-wordpress.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-wp-cli-site && cd my-wp-cli-site
> ddev config --project-type=wordpress
> ddev start -y
> ddev wp core download
> ddev wp core install --url="$(ddev exec echo '$DDEV_PRIMARY_URL')" --title='My WordPress site' --admin_user=admin --admin_password=admin --admin_email=admin@example.com
> ddev launch wp-admin/
> EOF
> chmod +x setup-wordpress.sh
> ./setup-wordpress.sh
> ```

[Bedrock](<https://roots.io/bedrock/>) is a modern, Composer-based installation in WordPress:

```
mkdir -p my-wp-bedrock-site && cd my-wp-bedrock-site
ddev config --project-type=wp-bedrock
ddev start
ddev composer create-project roots/bedrock
```

DDEV automatically manages the `.env` file with the correct database credentials and `WP_HOME` URL. No manual `.env` configuration is needed.

You can then run:

```
ddev wp core install --url="$(ddev exec echo '$DDEV_PRIMARY_URL')" --title='My Bedrock Site' --admin_user=admin --admin_password=admin --admin_email=admin@example.com
ddev launch /wp/wp-admin/
```

For more details, see [Bedrock installation](<https://docs.roots.io/bedrock/master/installation/>).

> [!TIP]
>
> **Prefer to run as a script?**
>
> To run the whole setup as a script, examine and run this script:
>
> ```
> cat > setup-wp-bedrock.sh << 'EOF'
> #!/usr/bin/env bash
> set -euo pipefail
> mkdir -p my-wp-bedrock-site && cd my-wp-bedrock-site
> ddev config --project-type=wp-bedrock
> ddev start -y
> ddev composer create-project roots/bedrock
> ddev wp core install --url="$(ddev exec echo '$DDEV_PRIMARY_URL')" --title='My Bedrock Site' --admin_user=admin --admin_password=admin --admin_email=admin@example.com
> ddev launch /wp/wp-admin/
> EOF
> chmod +x setup-wp-bedrock.sh
> ./setup-wp-bedrock.sh
> ```

To get started using DDEV with an existing WordPress project, clone the project’s repository.

```
PROJECT_GIT_URL=https://github.com/ddev/test-wordpress.git
git clone ${PROJECT_GIT_URL} my-wp-git-site
cd my-wp-git-site
ddev config --project-type=wordpress
ddev start
ddev wp core install --url="$(ddev exec echo '$DDEV_PRIMARY_URL')" --title='My WordPress site' --admin_user=admin --admin_password=admin --admin_email=admin@example.com
ddev launch wp-admin/
```

You’ll see a message like:

> An existing user-managed wp-config.php file has been detected! Project DDEV settings have been written to:
>
> /Users/rfay/workspace/bedrock/web/wp-config-ddev.php

Comment out any database connection settings in your `wp-config.php` file and add the following snippet to your `wp-config.php`, near the bottom of the file and before the include of `wp-settings.php`:

```
// Include for DDEV-managed settings in wp-config-ddev.php.
$ddev_settings = __DIR__ . '/wp-config-ddev.php';
if (is_readable($ddev_settings) && !defined('DB_USER')) {
require_once($ddev_settings);
}
```

If you don’t care about those settings, or config is managed elsewhere (like in a `.env` file), you can eliminate this message by adding a comment to `wp-config.php`:

```
// wp-config-ddev.php not needed
```

Now run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and continue [Importing a Database](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/#importing-a-database>) if you need to.

# Usage

# How DDEV Works

DDEV is a [Go](<https://go.dev>) application that stores its configuration in [files on your workstation](<#directory-tour>).  
It uses those blueprints to mount your project files into [Docker containers](<#container-architecture>) that facilitate the operation of a local development environment.

DDEV writes and uses [docker-compose](<https://docs.docker.com/compose/>) files for you, which is a detail you can cheerfully ignore unless you’re Docker-curious or [defining your own services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>).

## Directory Tour

DDEV stores configuration in two places: a single `.ddev` directory in your home folder (can be [moved](<#global-files>) to another location), and a `.ddev` directory for each project you set up.

The [global configuration directory](<#global-files>) is used to keep track of your projects and any of the [global settings](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>) that apply across all projects. You’ll probably spend more time working with the [per-project `.ddev` directories](<#project-files>) for their configuration and overrides.

### Project Files

A project’s `.ddev` directory can be intimidating at first, so let’s take a look at what lives in there.

> [!TIP]
>
> **Yours May Differ Slightly**
>
> You may have some directories or files that aren’t listed here, likely added by custom services.  
> For example, if you see a `solr` directory, it probably pertains to a custom Solr [add-on service](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>).

**`addon-metadata` directory**

Contains metadata about add-on services that have been added to the project. This allows commands like `ddev add-on list --installed` and `ddev add-on remove` to work, see [Using Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>).

**`apache` directory**

Default Apache configuration when using `webserver_type: apache-fpm`, which [can be customized](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-apache-configuration>).

**`commands` subdirectories**

Project custom [shell commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/index.md>) that can run on the host or inside a container.

**`config.yaml`**

The project’s main [configuration file](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>).

**`config.*.yaml` files**

[Environmental overrides](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) for parts of `config.yaml`.

**`db-build` directory**

Can be used to provide a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/index.md>) for the database container.

**`db_snapshots` directory**

Where snapshots go when you run the [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) command. You can safely delete anything in here that you don’t need.

**`docker-compose.*.yaml` files**

Where Docker-friendly users can provide their own [custom compose files](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>) that add or override services. Read more in [Additional Service Configurations &amp; Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>).

**`homeadditions` directory**

Files to be copied into the web container on startup. You could use this, for example, to override the default home directory contents (`.profile`, `.bashrc`, `.composer`, `.ssh`), or include scripts that you’d like to be available inside the container. (You can do the same thing globally in `$HOME/.ddev/homeadditions`.) Check out the [homeadditions docs](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/index.md>) for more. Changes made in the container aren’t copied back, see [Persisting Changes Across Restarts](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-changes-across-restarts>).

**`mutagen` directory**

Contains `mutagen.yml`, where you can [override the default Mutagen configuration](<https://ddev.github.io/ddev/en/stable/users/install/performance/#advanced-mutagen-configuration-options>).

**`mysql` directory**

Contains [optional `mysql` or `mariadb` configuration](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-mysqlmariadb-configuration-mycnf>).

**`nginx` directory**

Can be used for add-on [nginx snippets](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-nginx-configuration>).

**`nginx_full` directory**

Contains the nginx configuration used by the web container, which [can be customized](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-nginx-configuration>).

**`postgres` directory**

Contains `postgresql.conf`, which can be edited if needed. Remove the `#ddev-generated` line at the top to take it over.

**`providers` directory**

Contains examples and implementations to demonstrate how the [`ddev pull`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) command can work with [hosting providers](<https://ddev.github.io/ddev/en/stable/users/providers/index.md>).

**`traefik` directory**

Configures the [Traefik](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/index.md>)-based `ddev-router`. Full details in the [Traefik docs](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/index.md>).

**`web-build` directory**

Can be used to provide a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/index.md>) for the web container.

**`web-entrypoint.d` directory**

Custom scripts (named `*.sh`) in this directory will be run during web container startup, before the php-fpm server or other daemons are run. This can be useful, for example, for introducing environment variables into the context of the nginx and php-fpm servers. Use this carefully, because custom entrypoints can very easily break things.

**`xhprof` directory**

Contains the `xhprof_prepend.php` file that can be used to customize [xhprof](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xhprof-profiling/index.md>) behavior for different types of websites.

#### Hidden Project Files

Files beginning with `.` are hidden because they shouldn’t be fiddled with; most are regenerated, and thus overwritten, on every `ddev start`:

**`.dbimageBuild` directory**

The generated Dockerfile used to customize the `db` container on first start.

**`.ddev-docker-compose-base.yaml`**

The base docker-compose file used to describe a project.

**`.ddev-docker-compose-full.yaml`**

The result of preprocessing `.ddev-docker-compose-base.yaml` using `docker-compose config`. Mostly it replaces environment variables with their values.

**`.gitignore`**

The `.gitignore` is generated by DDEV and should generally not be edited or checked in. (It gitignores itself to make sure you don’t check it in.) It’s generated on every `ddev start` and will change as DDEV versions change, so if you check it in by accident it will always be showing changes that you don’t need to see in `git status`.

**`.homeadditions`**

Temporary directory used to consolidate global `homeadditions` with project-level `homeadditions`. You shouldn’t ever have to look here.

**`.webimageBuild` directory**

The generated Dockerfile used to customize the web container on first start.

### Global Files

There’s only one global `.ddev` directory, which normally lives in your home directory: `$HOME/.ddev`, but can be overwritten (first match wins):

1. `$DDEV_XDG_CONFIG_HOME/ddev` if `$DDEV_XDG_CONFIG_HOME` is set (all platforms)
2. `$HOME/.ddev`, which means:

   - `/Users/<username>/.ddev` on macOS
   - `/home/<username>/.ddev` on Linux/WSL2
   - `C:\Users\<username>\.ddev` on Windows
3. `$HOME/.config/ddev` on Linux/WSL2 only, if `$HOME/.ddev` doesn’t exist

To find your actual location, run:

```
ddev version | grep global-ddev-dir
```

> [!TIP]
>
> **Moving `$HOME/.ddev` to a custom location**
>
> To use a custom directory instead of `$HOME/.ddev`, set `$DDEV_XDG_CONFIG_HOME` to the parent directory. For example, to use `$HOME/.config/ddev`:
>
> ```
> ddev poweroff
> export DDEV_XDG_CONFIG_HOME="$HOME/.config"
> mv $HOME/.ddev ${DDEV_XDG_CONFIG_HOME}/ddev
> ```
>
> On Linux/WSL2, you can also move the directory to `$HOME/.config/ddev` without setting the variable:
>
> ```
> mv $HOME/.ddev $HOME/.config/ddev
> ```

**`global_config.yaml`**

This YAML file defines your global configuration, which consists of various [config settings](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>).

**`global_config.*.yaml`**

Files like `global_config.local.yaml` are merged over `global_config.yaml` in alphabetical order, with the same rules as [`config.*.yaml` files](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#extending-configyaml-with-custom-configyaml-files>): simple values are replaced and lists are merged, unless the file sets `override_config: true`. DDEV never writes their values into `global_config.yaml`.

**`project_list.yaml`**

This YAML file defines your project list that lets DDEV keep track of the projects you’ve added.

**`bin` directory**

This is where DDEV stores private executable binaries it needs, like [`mutagen`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#performance_mode>) and [`docker-buildx`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#docker_buildx_version>).

**`commands` directory**

Directory for storing DDEV commands that should be available in containers, like `npm`, `artisan`, `cake` and `drush` for example. These are organized in subdirectories named for where they’ll be used: `db`, `host`, and `web`. You can add your own [custom commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/index.md>) here.

**`db-build` directory**

Like the per-project `db-build` directory, can be used to provide a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#global-dockerfiles>) for the database container, applied to **every** project on this machine.

**`homeadditions` directory**

Like the per-project `homeadditions` directory, files you add here will automatically be copied into the web container’s home directory. Files from the *global* homeadditions directory will be copied into **every** web container’s home directory.

**`web-build` directory**

Like the per-project `web-build` directory, can be used to provide a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#global-dockerfiles>) for the web container, applied to **every** project on this machine.

#### Hidden Global Files

Again, these files are mostly regenerated on every `ddev start` so it’s best to leave them alone:

**`.gitignore`**

Prevents files from getting checked in when they shouldn’t be.

**`.global.lock`**

A lockfile that makes concurrent `ddev` commands take turns while they set up the shared router, SSH agent, and `ddev_default` network. It’s safe to delete when no `ddev` command is running.

**`.global.lock.info`**

Which `ddev` command holds `.global.lock`, so another command waiting for it can say what it’s waiting for. See [Waiting for Another DDEV Process](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#waiting-for-another-ddev-process>).

**`.router-compose-full.yaml`**

The complete, generated docker-compose directive used for DDEV’s router.

**`.router-compose.yaml`**

The base docker-compose directive used in generating `.router-compose-full.yaml`.

**`router-compose.*.yaml`**

`docker-compose` files with the name `router-compose.*.yaml` can be used to override stanzas in the `.router-compose.yaml` file.

**`.ssh-auth-compose-full.yaml`**

The complete, generated docker-compose directive used for DDEV’s SSH agent.

**`.ssh-auth-compose.yaml`**

The base docker-compose directive used in generating `.ssh-auth-compose-full.yaml`.

**`ssh-auth-compose.*.yaml`**

`docker-compose` files with the name `ssh-auth-compose.*.yaml` can be used to override stanzas in the `.ssh-auth-compose.yaml` file.

**`.update`**

An empty file whose purpose is mysterious and intriguing.

> [!TIP]
>
> **`.ddev_mutagen_data_directory`**
>
> DDEV uses a global `$HOME/.ddev_mutagen_data_directory` for storing [Mutagen](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) sync data.

## Container Architecture

It’s easiest to think of DDEV as a set of little networked computers (Docker containers) that are in a different network from your workstation but still reachable from it.

When you install or upgrade DDEV you’re mostly installing a single `ddev` binary. When you use it, it downloads the Docker images it needs, and then starts them based on what’s needed for your projects.

- The `ddev-webserver` container (one per project) runs `nginx` or `apache` and `php-fpm` for a single site, so it does all the basic work of a PHP-interpreting web server.
- The `ddev-dbserver` container (one per project) handles MariaDB/MySQL/PostgreSQL database management. It can be reached from the web server by the hostname `db` or with the more explicit name `ddev-<projectname>-db`.
- Additional add-on services may be there for a given project, for example `phpmyadmin`, `solr`, `elasticsearch`, or `memcached`.

Although it’s not common usage, different projects can communicate with each other as described in the [FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#can-different-projects-communicate-with-each-other>).

Now for the two oddball global containers (there’s only one of each):

- The `ddev-router` container is a “reverse proxy”. It takes incoming HTTP/S requests, looks up the hostname in the incoming URL, and routes it to the correct project’s `ddev-webserver`. Depending on the project’s configuration with [`additional_hostnames`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#additional_hostnames>) and [`additional_fqdns`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#additional_fqdns>), it can route many different URLs to a single project’s `ddev-webserver`. If, like most people, you use the named URLs like `https://something.ddev.site`, your request goes through the router. When you use the `127.0.0.1` URLs, the requests go directly to the `ddev-webserver`.
- The `ddev-ssh-agent` container runs an `ssh-agent` inside the Docker network so that after run [`ddev auth ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#auth-ssh>) all the different projects can use your SSH keys for outgoing requests—like private Composer access or SCP from a remote host.

Here’s a basic diagram of how it works inside the Docker network:

![DDEV Docker Network Architecture](<https://ddev.github.io/ddev/en/stable/images/container-diagram.png>)

## The `ddev-global-cache` Volume

`ddev-global-cache` is a Docker volume shared by all projects and mounted at `/mnt/ddev-global-cache`. The `web`, `db`, and `ddev-router` containers use it, and so do custom services that run [custom commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#container-commands>). Unlike the containers, it survives [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) and [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>).

| Directory | Scope | Contents |
| --- | --- | --- |
| `bashhistory/<project>-db`, `bashhistory/<project>-web` | Per project | Bash history |
| `composer` | Shared | Composer cache |
| `corepack` | Shared | Package managers installed by `corepack` |
| `global-commands` | Shared | [Global commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#global-commands>), copied from the host |
| `mkcert` | Shared | The mkcert certificate authority, copied from the host and used for HTTPS certificates |
| `mysqlhistory/<project>-db`, `mysqlhistory/<project>-web` | Per project | MySQL client history |
| `n_prefix/<project>-web` | Per project | Node.js versions downloaded by `n` |
| `npm` | Shared | npm cache |
| `pip` | Shared | pip cache, created only if you install pip, for example with [`webimage_extra_packages`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webimage_extra_packages>) |
| `terminus/cache` | Shared | Terminus cache |
| `traefik` | Shared | Router configuration and certificates, with files for each project |
| `yarn/berry`, `yarn/classic` | Shared | Yarn caches |

[`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) removes the project’s own directories and router files. To keep your own files in this volume, see [Persisting Changes Across Restarts](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-changes-across-restarts>).

To clear the volume, for example to free Docker provider disk space, remove it. (Any stored global cache for all projects will be lost, but will be rebuilt as needed.) This also removes the Bash and MySQL history of every project. DDEV creates the volume again on the next [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>):

```
ddev poweroff
docker volume rm ddev-global-cache
```

# Using the `ddev` Command

Type `ddev help` or `ddev --help` or `ddev -h` in a terminal window to see the available DDEV [commands](<https://ddev.github.io/ddev/en/stable/users/usage/commands/index.md>). There are commands to configure a project, start, stop, describe, etc. Each command also has help using `ddev help <command>` or `ddev command -h`. For example, `ddev help snapshot` will show help and examples for the snapshot command.

## Interactive Dashboard

Running `ddev` with no arguments launches an interactive terminal dashboard. The dashboard shows all your DDEV projects and their status, and lets you manage them with these keyboard shortcuts.

### Navigation

| Key | Action |
| --- | --- |
| <kbd>Enter</kbd> | Open project detail view |
| <kbd>↑</kbd> / <kbd>↓</kbd> or <kbd>k</kbd> / <kbd>j</kbd> | Move the selection, or scroll the detail and log views |
| <kbd>PgUp</kbd>/<kbd>b</kbd> / <kbd>PgDn</kbd>/<kbd>f</kbd>, <kbd>Home</kbd>/<kbd>g</kbd> / <kbd>End</kbd>/<kbd>G</kbd> | Scroll the list, detail or logs a screen at a time, or jump to the start or end |
| <kbd>u</kbd> / <kbd>d</kbd> | Scroll the detail or logs half a screen up or down |
| <kbd>Esc</kbd> / <kbd>Backspace</kbd> | Go back |
| <kbd>/</kbd> | Filter projects by name, type, status, or directory name; <kbd>Enter</kbd>, <kbd>Tab</kbd>, <kbd>↑</kbd> or <kbd>↓</kbd> ends typing, and <kbd>Esc</kbd> clears the filter |
| <kbd>r</kbd> | Refresh |
| <kbd>?</kbd> | Show or hide the full list of keys |
| <kbd>q</kbd> | Quit |

### Projects

| Key | Action |
| --- | --- |
| <kbd>s</kbd> / <kbd>S</kbd> | Start / Stop the project |
| <kbd>R</kbd> | Restart the project |
| <kbd>D</kbd> | Delete the project and its database, like [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>); confirm with <kbd>y</kbd>, or <kbd>O</kbd> to skip the snapshot |
| <kbd>l</kbd> | Launch project URL in browser |
| <kbd>m</kbd> | Launch Mailpit in browser |
| <kbd>x</kbd> | Launch XHGui in browser |
| <kbd>o</kbd> | Open project directory in the file manager |
| <kbd>v</kbd> / <kbd>p</kbd> | Open project in VS Code / PhpStorm |
| <kbd>e</kbd> | SSH into web container (detail view) |
| <kbd>L</kbd> | Follow logs (detail view) |
| <kbd>X</kbd> | Toggle Xdebug (detail view) |
| <kbd>c</kbd> | Copy the project URL (detail view) |
| <kbd>n</kbd> | Make a database snapshot, like [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>), while the project runs (detail view) |
| <kbd>N</kbd> | Restore the latest snapshot, like [`ddev snapshot restore --latest`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot-restore>); confirm with <kbd>y</kbd> (detail view) |
| <kbd>U</kbd> | Update the installed add-ons that have a newer release, like [`ddev add-on update`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#add-on-update>); confirm with <kbd>y</kbd> (detail view) |
| <kbd>a</kbd> / <kbd>A</kbd> | Start all / Stop all projects; confirm with <kbd>y</kbd> |
| <kbd>P</kbd> | Poweroff all DDEV projects and containers; confirm with <kbd>y</kbd> |
| <kbd>C</kbd> | Run `ddev config` interactively in the current directory |

Commands such as start and delete run in the terminal itself, so their output, errors included, stays in the terminal after you quit the dashboard.

In terminals that support [OSC 8 hyperlinks](<https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda>), project paths and URLs in the dashboard and detail view are clickable, as are the VS Code and PhpStorm links in the detail view. The editor links use the `vscode://` and `phpstorm://` URL schemes, so they work only when that editor is installed, and some terminals block those schemes. PhpStorm does not register `phpstorm://` on Windows, so there the PhpStorm link needs a separately installed handler. The <kbd>p</kbd> key avoids this by using PhpStorm’s command-line launcher when it is on your `PATH`, which [JetBrains Toolbox](<https://www.jetbrains.com/toolbox-app/>) can install.

To disable the dashboard and show the classic help text instead, set [`no_tui: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_tui>) in your global configuration (`$HOME/.ddev/global_config.yaml`), or set the environment variable `DDEV_NO_TUI=true`.

### Terminal Compatibility

The dashboard automatically detects your terminal’s color capabilities and adapts its output. If colors or styling don’t render correctly in your terminal, you have several options:

- **Disable colors**: Run `NO_COLOR=1 ddev` or `export NO_COLOR=1` in your shell to disable all color output while keeping the dashboard functional.
- **Use simple formatting globally**: Run `ddev config global --simple-formatting=true` to disable colors and table formatting across all DDEV commands, including the dashboard. See [`simple_formatting`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#simple_formatting>).
- **Set `TERM` appropriately**: If your terminal supports color but DDEV doesn’t detect it, make sure your `TERM` environment variable is set correctly (e.g., `xterm-256color`). Some SSH clients or multiplexers like `tmux` or `screen` may need explicit configuration.
- **Disable the dashboard entirely**: If the interactive dashboard doesn’t work well in your environment (e.g., a very limited terminal or CI), use `DDEV_NO_TUI=true` or set [`no_tui: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_tui>) in `$HOME/.ddev/global_config.yaml` to fall back to the classic help output.
- [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) configures a project’s type and docroot, either interactively or with flags.
- [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) starts up a project.
- [`ddev launch`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#launch>) opens a web browser showing the project.
- [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) shows current projects and their state.
- [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) gives all the info about the current project.
- [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) takes you into the web container.
- [`ddev exec <command>`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) executes a command inside the web container.
- [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>) stops a project and removes its memory usage (but does not throw away any data).
- [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) stops all resources that DDEV is using and stops the Mutagen daemon if it’s running.
- [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) destroys the database and DDEV’s knowledge of the project without touching your code.
- [`ddev add-on`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#add-on>) adds an add-on service.

## Lots of Other Commands

- [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>) gives direct access to the MySQL client and [`ddev psql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#psql>) to the PostgreSQL `psql` client.
- [`ddev sequelace`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#sequelace>), [`ddev tableplus`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tableplus>), [`ddev tablepro`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tablepro>), and [`ddev querious`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#querious>) (macOS only, if the app is installed) give access to the Sequel Ace, TablePlus, TablePro or Querious database browser GUIs.
- [`ddev dbeaver`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dbeaver>) (if installed) gives access to the DBeaver database browser GUI.
- [`ddev heidisql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#heidisql>) (Windows/WSL2/Linux, if installed) gives access to the HeidiSQL database browser GUI.
- [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) and [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>) import or export SQL or compressed SQL files.
- [`ddev composer`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>) runs Composer inside the container. For example, `ddev composer install` will do a full composer install for you without even needing Composer on your computer. See [developer tools](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#ddev-and-composer>).
- [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) makes a very fast snapshot of your database that can be easily and quickly restored with [`ddev snapshot restore`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot-restore>).
- [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) requires ngrok and at least a free account on [ngrok.com](<https://ngrok.com>) so you can let someone in the next office or on the other side of the planet see your project and what you’re working on. `ddev share -h` gives more info about how to set up ngrok.
- [`ddev xdebug`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>) enables Xdebug, `ddev xdebug off` disables it, and `ddev xdebug status` shows status. You can toggle Xdebug on and off easily using `ddev xdebug toggle`.
- [`ddev xhprof`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xhprof>) enables xhprof, `ddev xhprof off` disables it, and `ddev xhprof status` shows status.
- [`ddev xhgui`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xhgui>) enables XHGui, `ddev xhgui off` disables it, and `ddev xhgui status` shows status.
- [`ddev dr`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dr>) (Drupal 11.4+ only) gives direct access to the `dr` CLI, the next-generation Drupal CLI available in Drupal 11.4+.
- [`ddev drush`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#drush>) (Drupal and Backdrop only) gives direct access to the `drush` CLI.
- [`ddev artisan`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#artisan>) (Laravel only) gives direct access to the Laravel `artisan` CLI.
- [`ddev asterios`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#asterios>) (Asterios only) gives direct access to the Asterios `asterios` CLI.
- [`ddev magento`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#magento>) (Magento2 only) gives access to the `magento` CLI.
- [`ddev maho`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#maho>) (Maho only) gives direct access to the `maho` CLI.
- [`ddev console`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#console>) (Symfony and Shopware only) gives access to the `symfony console` CLI.
- [`ddev craft`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#craft>) (Craft CMS only) gives access to the `craft` CLI.
- [`ddev npm`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#npm>) gives direct access to the `npm` CLI.
- [`ddev npx`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#npx>) gives direct access to the `npx` CLI.
- [`ddev yarn`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#yarn>) gives direct access to the `yarn` CLI.
- [`ddev cake`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#cake>) (CakePHP only) gives direct access to the `cake` CLI.
- [`ddev sake`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#sake>) (Silverstripe CMS only) gives direct access to the `sake` CLI.
- [`ddev spark`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#spark>) (CodeIgniter) gives direct access to the `spark` CLI.
- [`ddev typo3`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#typo3>) (TYPO3 only) gives direct access to the `typo3` CLI.
- [`ddev wp`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#wp>) (WordPress and Bedrock only) gives direct access to the `wp` CLI.

## Node.js Tools

`node`, `nodejs`, `npm`, `npx` and `yarn` are preinstalled in the web container. You can configure the default value of the installed Node.js version with the [`nodejs_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#nodejs_version>) option in `.ddev/config.yaml` or with `ddev config --nodejs-version`. There is also a [`ddev yarn`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#yarn>) command.

## More Bundled Tools

In addition to the [*commands*](<https://ddev.github.io/ddev/en/stable/users/usage/commands/index.md>) listed above, there are lots of tools included inside the containers:

- [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) tells how to access **Mailpit**, which captures email in your development environment.
- Composer, Git, Node.js, npm, symfony, and dozens of other tools are installed in the web container, and you can access them via [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) or [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>).
- [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) gets you web server logs; `ddev logs -s db` gets database server logs.
- `sqlite3` and the `mysql` and `psql` clients are inside the web container (and `mysql` or `psql` client is also in the `db` container).

## Exporting a Database

You can export a database with [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>), which outputs to stdout or with options to a file:

```
ddev export-db --file=/tmp/db.sql.gz
ddev export-db --file=/tmp/db.sql
ddev export-db --compression=zstd >/tmp/db.sql.zst
ddev export-db >/tmp/db.sql.gz
```

## `ddev import-files`

To import static file assets for a project, such as uploaded images and documents, use the command [`ddev import-files`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-files>). This command will prompt you to specify the location of your import asset, then import the assets into the project’s upload directory. To define a custom upload directory, set the [`upload_dirs`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#upload_dirs>) config option. If no custom upload directory is defined, the default will be used:

- For Backdrop projects, this is the `files` directory.
- For Craft CMS projects, this is the `files` directory.
- For Drupal projects, this is the `sites/default/files` directory.
- For Magento 1 projects, this is the `media` directory.
- For Magento 2 projects, this is the `media` directory.
- For Shopware projects, this is the `media` directory.
- For Silverstripe CMS projects, this is the `assets` directory.
- For TYPO3 projects, this is the `fileadmin` directory.
- For WordPress projects, this is the `wp-content/uploads` directory.
- For WordPress Bedrock projects, this is the `app/uploads` directory.

Other project types need a custom configuration to be able to use this command.

```
$ ddev import-files
Provide the path to the source directory or archive you wish to import.
Please note: if the destination directory exists, it will be emptied and replaced with the
import assets specified here.
Path to file(s): ~/workspace/d10/.tarballs/files.tgz
You provided an archive. Do you want to extract from a specific path in your
archive? You may leave this blank if you wish to use the full archive contents.
Archive extraction path:
Successfully imported files for d10
```

`ddev import-files` supports the following file types: `.tar`, `.tar.gz`, `.tar.xz`, `.tar.bz2`, `.tar.zst`, `.tgz`, or `.zip`.

It can also import a directory containing static assets.

If using a Tar or ZIP archive, the archive should contain *only the files inside the files directory*. For example in a Drupal site with files at `sites/default/files`, the archive should only contain the contents of the `files` directory; it should not contain a single `files` directory. To do this with the `tar` command, `cd` into the directory and create the archive there. An example Tar file creation is:

```
cd web/sites/default/files
tar -czf ~/Downloads/files.tgz .
```

If you want to use `import-files` without answering prompts, use the `--source` or `-s` flag to provide the path to the import asset. If you’re importing an archive, and wish to specify the path within the archive to extract, you can use the `--extract-path` flag in conjunction with the `--source` flag. Example:

`ddev import-files --source=/tmp/files.tgz`

When multiple `upload_dirs` are defined and you want to import to another upload dir than the first one, use the `--target` or `-t` flag to provide the path to the desired upload dir:

`ddev import-files --target=../private --source=/tmp/files.tgz`

See `ddev help import-files` for more examples.

## Snapshotting and Restoring a Database

The project database is stored in a Docker volume, but can be snapshotted (and later restored) with the [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) command. A snapshot is automatically taken when you run [`ddev stop --remove-data`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>). For example:

```
ddev snapshot
Creating database snapshot d9_20220107124831-mariadb_10.3.gz
Created database snapshot d9_20220107124831-mariadb_10.3.gz

ddev snapshot restore d9_20220107124831
Stopping db container for snapshot restore of 'd9_20220107124831-mariadb_10.3.gz'...
Restored database snapshot d9_20220107124831-mariadb_10.3.gz
```

Snapshots are stored as gzipped files in the project’s `.ddev/db_snapshots` directory, and the file created for a snapshot can be renamed as necessary. For example, if you rename the above `d9_20220107124831-mariadb_10.3.gz` file to `working-before-migration-mariadb_10.3.gz`, then you can use `ddev snapshot restore working-before-migration`. (The description of the database type and version—`mariadb_10.3`, for example—must remain intact.) To restore the latest snapshot add the `--latest` flag (`ddev snapshot restore --latest`).

List snapshots for an existing project with `ddev snapshot --list`. (Add the `--all` option for an exhaustive list; `ddev snapshot --list --all`.) You can remove all of them with `ddev snapshot --cleanup`, or remove a single snapshot with `ddev snapshot --cleanup --name <snapshot-name>`.

> [!TIP]
>
> The default 120-second timeout may be inadequate for restores with very large snapshots or slower systems. You can increase this timeout by setting [`default_container_timeout`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#default_container_timeout>) to a higher value.
>
> A timeout doesn’t necessarily mean the restore failed; you can watch the snapshot restore complete by running `ddev logs -s db`.

## Interacting with Your Project

DDEV provides several commands to facilitate interacting with your project in the development environment. These commands can be run within the working directory of your project while the project is running in DDEV.

### Executing Commands in Containers

The [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) command allows you to run shell commands in the container for a DDEV service. By default, commands are executed on the web service container, in the docroot path of your project. This allows you to use [the developer tools included in the web container](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/index.md>). For example, to run the `ls` command in the web container, you would run `ddev exec ls` or `ddev . ls`.

To run a shell command in the container for a different service, use the `--service` (or `-s`) flag at the beginning of your `exec` command to specify the service the command should be run against. For example, to run the MySQL client in the database, container, you would run `ddev exec --service db mysql`. To specify the directory in which a shell command will be run, use the `--dir` flag. For example, to see the contents of the `/usr/bin` directory, you would run `ddev exec --dir /usr/bin ls`.

To run privileged commands, sudo can be passed into `ddev exec`. For example, to update the container’s apt package lists, use `ddev exec sudo apt-get update`.

Commands can also be executed using the shorter `ddev . <cmd>` alias.

Normally, `ddev exec` commands are executed in the container using Bash, which means that environment variables and redirection and pipes can be used. For example, a complex command like `ddev exec 'ls -l ${DDEV_FILES_DIR} | grep x >/tmp/junk.out'` will be interpreted by Bash and will work. However, there are cases where Bash introduces too much complexity and it’s best to run the command directly. In those cases, something like `ddev exec --raw ls -l "dir1" "dir2"` may be useful. With `--raw`, the `ls` command is executed directly instead of the full command being interpreted by Bash. But you cannot use environment variables, pipes, redirection, etc.

### SSH Into Containers

The [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) command opens an interactive Bash or sh shell session to the container for a DDEV service. The web service is connected by default, and the session can be ended by typing `exit`. To connect to another service, use the `--service` flag to specify the service you want to connect to. For example, to connect to the database container, you would run `ddev ssh --service db`. To specify the destination directory, use the `--dir` flag. For example, to connect to the database container and be placed into the `/home` directory, you would run `ddev ssh --service db --dir /home`.

You can also use your personal SSH keys within the web container. Run `ddev auth ssh` to add the keys from your `~/.ssh` directory and provide a passphrase, and those keys will be usable from within the web container. You generally only have to `ddev auth ssh` one time per computer reboot. This is a very popular approach for accessing private Composer repositories, or for using `drush` aliases against remote servers.

If your keys live in an SSH agent rather than in `~/.ssh`, as with 1Password or a hardware key, see [Using an Existing SSH Agent](<#using-an-existing-ssh-agent>).

### Using an Existing SSH Agent

If you already use an SSH agent, such as the macOS agent, 1Password, Secretive, `gpg-agent` with a YubiKey, or one forwarded with `ssh -A`, DDEV’s containers can use it directly. Set this once:

```
ddev config global --ssh-agent-upstream=host
ddev auth ssh      # lists the keys your containers can use
```

After that, every project’s containers use your agent when they start, with nothing to add per project. `ddev auth ssh` only shows which keys are available, and `ddev exec ssh -T git@github.com` tests them. Every container on the DDEV network can ask your agent to sign while this is on; agents that confirm each use, like 1Password, limit that exposure.

If `ddev auth ssh` says “Make sure that agent is running and holds your keys”, your agent is stopped or locked; open it or load your keys, and DDEV picks it up again without a restart. To go back to adding key files, run `ddev config global --ssh-agent-upstream=""` and then `ddev auth ssh`.

If a connection instead fails with “Too many authentication failures”, the server capped how many keys it will try, and relaying a whole agent offers more than the few keys you’d add by hand; see [Too Many Authentication Failures](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#too-many-authentication-failures>) to limit which key gets offered per host.

> [!TIP]
>
> **macOS: which agent do my containers get?**
>
> That depends on your Docker provider:
>
> | Provider | What to do | Agent containers get |
> | --- | --- | --- |
> | OrbStack | Nothing extra | The agent named by `IdentityAgent` in `~/.ssh/config`, such as 1Password, otherwise the macOS agent. Restart OrbStack after changing `~/.ssh/config`. |
> | Docker Desktop | Nothing extra | Always the macOS agent |
> | Colima | Start it with `colima start --ssh-agent` | Always the macOS agent |
> | Lima | Run `limactl edit <instance> --set .ssh.forwardAgent=true` once | Always the macOS agent |
> | Rancher Desktop, Podman | Not supported | DDEV warns and uses its own agent; add key files with `ddev auth ssh` as usual |
>
> To use 1Password, Secretive, or `gpg-agent`:
>
> - With OrbStack, set `IdentityAgent` in `~/.ssh/config` as your agent’s setup instructions describe, then restart OrbStack.
> - Docker Desktop, Colima, and Lima ignore `IdentityAgent`. Point the system-wide `SSH_AUTH_SOCK` at your agent as its documentation describes; for 1Password, see [Configure SSH\_AUTH\_SOCK globally for every client](<https://developer.1password.com/docs/ssh/agent/compatibility/>).
> - Exporting `SSH_AUTH_SOCK` in your shell profile doesn’t reach any of these providers.
>
> To use the macOS agent, load your keys into it, saving the passphrase in the Keychain:
>
> ```
> ssh-add --apple-use-keychain ~/.ssh/id_ed25519
> ssh-add -l
> ```

> [!TIP]
>
> **Linux: pointing at your own agent**
>
> `host` uses the agent in `$SSH_AUTH_SOCK` when a project starts. A forwarded agent (`ssh -A`) gets a new socket for each login, so run `ddev auth ssh` again after logging in again. When the socket is a symlink, as with VS Code Remote’s `/tmp/vscode-ssh-auth-sock-*`, DDEV uses the socket it points to. After VS Code or SSH reconnects, a terminal opened earlier still points to the old, dead socket, so run `ddev auth ssh` from a new terminal. A desktop agent’s socket doesn’t change, so you can set it directly, for example on Ubuntu with `ddev config global --ssh-agent-upstream=/run/user/$(id -u)/gcr/ssh`. An agent you start yourself with `eval $(ssh-agent -s)` works when you run `ddev` from that shell; to use it from any shell, start it on a fixed socket with `mkdir -p -m 700 ~/.ssh-agent && eval $(ssh-agent -a ~/.ssh-agent/agent.sock -s)` and set `ddev config global --ssh-agent-upstream=$HOME/.ssh-agent/agent.sock`. Keep the socket in its own directory rather than `~/.ssh`, because DDEV mounts the socket’s whole directory into the `ddev-ssh-agent` container.

> [!TIP]
>
> **Docker Desktop: using an agent forwarded with `ssh -A`**
>
> Docker Desktop relays the agent in the `SSH_AUTH_SOCK` it started with, not your shell’s, and a forwarded agent gets a new socket for each login. To follow each new login without restarting Docker Desktop, start it once on a fixed path and point that path at each login’s socket from `~/.ssh/rc`, which `sshd` runs at login:
>
> ```
> # Once. On macOS, use 'launchctl setenv SSH_AUTH_SOCK ...' and 'docker desktop restart' instead.
> mkdir -p -m 700 ~/.ssh-agent-forward
> systemctl --user set-environment SSH_AUTH_SOCK=$HOME/.ssh-agent-forward/agent.sock
> systemctl --user restart docker-desktop
>
> # In ~/.ssh/rc:
> if [ -n "$SSH_AUTH_SOCK" ]; then ln -sf "$SSH_AUTH_SOCK" ~/.ssh-agent-forward/agent.sock; fi
> ```
>
> The most recent `ssh -A` login wins, and after it ends, containers can’t reach an agent until you log in again. With X11 forwarding, `~/.ssh/rc` also has to run `xauth`, as `man sshd` describes. The Docker Desktop setting doesn’t last past a reboot.

> [!TIP]
>
> **WSL2: bridging a Windows agent**
>
> DDEV can’t reach Windows agents such as 1Password and the Windows OpenSSH agent directly, because they listen only on a Windows named pipe. Bridge that pipe to a Unix socket with `socat` in WSL2 and [`npiperelay`](<https://github.com/albertony/npiperelay>) on Windows, then point DDEV at the socket. DDEV doesn’t start the bridge for you. This works with Docker Desktop’s WSL integration as well as Docker installed inside WSL2, although Docker Desktop on Windows doesn’t forward an agent of its own.
>
> 1. Install `socat` in WSL2 with `sudo apt install socat`, and `npiperelay` in PowerShell with `winget install albertony.npiperelay`. `npiperelay` is x64-only; Windows on Arm runs it under emulation.
> 2. With [systemd enabled in WSL2](<https://learn.microsoft.com/en-us/windows/wsl/systemd>), run the bridge as a user service, which starts with WSL2 whether or not you open a shell. Run this in a WSL2 shell, where `npiperelay.exe` is on `PATH`; the service itself doesn’t get the Windows `PATH`, so the unit records the full path:
>
>    ```
>    mkdir -p ~/.config/systemd/user
>    cat > ~/.config/systemd/user/ssh-agent-bridge.service <<EOF
>    [Unit]
>    Description=Bridge the Windows SSH agent to ~/.1password/agent.sock
>
>    [Service]
>    ExecStartPre=/usr/bin/mkdir -p -m 700 %h/.1password
>    ExecStart=/usr/bin/socat UNIX-LISTEN:%h/.1password/agent.sock,fork,unlink-early EXEC:"$(command -v npiperelay.exe) -ei -s //./pipe/openssh-ssh-agent",nofork
>    Restart=on-failure
>    SuccessExitStatus=143
>
>    [Install]
>    WantedBy=default.target
>    EOF
>    systemctl --user enable --now ssh-agent-bridge
>    ```
>
>    Without systemd, add this to `~/.bashrc` instead, so that each new shell starts the bridge if it isn’t already running:
>
>    ```
>    export SSH_AUTH_SOCK=$HOME/.1password/agent.sock
>    ssh-add -l >/dev/null 2>&1
>    if [ $? -eq 2 ]; then
>      rm -f "$SSH_AUTH_SOCK"
>      mkdir -p -m 700 "$(dirname "$SSH_AUTH_SOCK")"
>      (setsid socat UNIX-LISTEN:"$SSH_AUTH_SOCK",fork EXEC:"npiperelay.exe -ei -s //./pipe/openssh-ssh-agent",nofork &) >/dev/null 2>&1
>    fi
>    ```
> 3. Check that `SSH_AUTH_SOCK=~/.1password/agent.sock ssh-add -l` lists your keys, then run:
>
>    ```
>    ddev config global --ssh-agent-upstream=$HOME/.1password/agent.sock
>    ddev auth ssh
>    ```
>
> To use the same agent for `ssh` and `git` in WSL2, add `export SSH_AUTH_SOCK=$HOME/.1password/agent.sock` to `~/.bashrc`. If the bridge stops, containers can’t use your keys until it runs again, and nothing in DDEV needs a restart.

> [!TIP]
>
> **Traditional Windows: key files, or piping from 1Password**
>
> `ssh_agent_upstream` doesn’t work here. Windows agents, including 1Password and the Windows OpenSSH agent, listen on a named pipe that Docker Desktop and other Windows providers can’t pass to containers. DDEV warns and uses its own agent, so add your key files from `%USERPROFILE%\.ssh` with `ddev auth ssh`. To use a key stored in 1Password without saving it to a file, pipe it from the [1Password CLI](<https://developer.1password.com/docs/cli/get-started/>), in PowerShell or Git Bash:
>
> ```
> op read "op://<vault>/<item>/private key?ssh-format=openssh" | ddev auth ssh -f -
> ```
>
> Turn on **Settings** \> **Developer** \> **Integrate with 1Password CLI** in the 1Password app first, and add `--account <account>.1password.com` to `op read` if you’re signed in to more than one account. Run the command again after `ddev poweroff` or a reboot, because DDEV’s agent forgets keys when it stops.

### `ddev logs`

The [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) command allows you to easily view error logs from the web container (both nginx/Apache and php-fpm logs are concatenated). To follow the logs in real time, run `ddev logs -f`. When you’re done, press <kbd>CTRL</kbd> + <kbd>C</kbd> to exit the log trail. Similarly, `ddev logs -s db` will show logs from a running or stopped database container.

## Stopping a Project

To remove a project’s containers, run [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>) in the project’s working directory. To remove any running project’s containers regardless of context, specify the project name as an argument: `ddev stop <projectname>`.

`ddev stop` is *not* destructive. It removes the Docker containers but does not remove the database for the project, and does nothing to your code. This allows you to have many configured projects with databases loaded without wasting Docker containers on unused projects. **`ddev stop` does not affect the project codebase and files.**

To remove the imported database for a project, use the flag `--remove-data`, as in `ddev stop --remove-data`. This command will destroy both the containers and the imported database contents.

# Managing CMS Settings

Any CMS-specific project type, meaning any of the non-generic [CMS Quickstarts](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>), has settings that DDEV manages to save you time and optimize configuration for local development.

Generally, DDEV will:

- Create a main settings file if none exists, like Drupal’s `settings.php`.
- Create a specialty config file with DDEV-specific settings, like `AdditionalSettings.php` for TYPO3 or `settings.ddev.php` for Drupal.
- Add an include of the specialty file if needed, like adding `settings.ddev.php` include to the bottom of Drupal’s `settings.php`.

While this reduces setup time for new users, makes it easier to try out a CMS, and speeds up project creation, you may still want to modify or override DDEV’s CMS-specific behavior.

## Controlling or Removing CMS Settings

There are several ways to back off DDEV’s CMS settings management:

1. **Take control of files by removing the `#ddev-generated` comment.** DDEV will automatically update any it’s added containing a `#ddev-generated` comment. This means you don’t need to touch that file, but also that any changes you make will be overwritten. As soon as you remove the comment, DDEV will ignore that file and leave you fully in control over it. (Don’t forget to check it into version control!)

   > **Reversing the change**
   >
   > If you change your mind and want DDEV to take over the file again, delete it and run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). DDEV will recreate its own version, which you may want to remove from your Git project.
2. **Disable settings management.** You can tell DDEV to use a specific project type without creating settings files by either setting [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) to `true` or running [`ddev config --disable-settings-management`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).
3. **Switch to the generic PHP project type.** If you don’t want DDEV’s CMS-specific settings, you can switch your project to the generic `php` type by editing [`type: php`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#type>) in the project’s settings or running [`ddev config --project-type=php`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). DDEV will no longer create or tweak any settings files. You’ll lose any perks from the nginx configuration for the CMS, but you can always customize [nginx settings](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-nginx-configuration>) or [Apache settings](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#custom-apache-configuration>) separately.
4. **Un-set the `$IS_DDEV_PROJECT` environment variable.** This environment variable is set `true` by default in DDEV’s environment, and can be used to fence off DDEV-specific behavior. When it’s empty, the important parts of `settings.ddev.php` and `AdditionalSettings.php` (for TYPO3) are not executed. This means that DDEV’s `settings.ddev.php` won’t be invoked if it somehow ends up in a production environment or in a non-DDEV local development environment.

> [!TIP]
>
> **Ignore `.ddev/.gitignore`**
>
> The `.ddev/.gitignore` file is created when you run `ddev start` and `disable_settings_management` is `false`. You should *not* check this file in, since it ignores itself and DDEV’s temporary and automatically-managed files. This makes it easier for teams to share the `.ddev` folder via Git, even if the `.ddev/.gitignore` file changes with different versions.

## CMS-Specific Help and Techniques

### Backdrop Specifics

#### Configuration considerations

By default, Backdrop stores both active and staging configuration in the filesystem. In this case, if you are updating the database (either from a live site, or reloading while working locally) it can be important to also refresh the active configuration directory to make sure your database structure is in line with what your configuration is describing.

Backdrop also allows you to store your active configuration in the database ([as of Backdrop 1.28.0](<https://docs.backdropcms.org/change-records/swappable-config-storage>)), which can be simpler while developing locally, especially if you are making use of DDEV’s snapshot feature. In this case, the database and the active configuration are effectively bundled and refreshing the database also refreshes the active configuration.

### Drupal Specifics

#### Drupal Settings Files

By default, DDEV will create settings files for your project that work out of the box. It creates a `sites/default/settings.ddev.php` and adds an include in `sites/default/settings.php` to bring that in. There are guards to prevent the `settings.ddev.php` from being active when the project is not running under DDEV, but it still should not be checked in and is gitignored.

#### Database requirements for Drupal 9.5+

- Using MySQL or MariaDB, Drupal requires `SET GLOBAL TRANSACTION ISOLATION LEVEL READ COMMITTED` and DDEV does this for you on [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).
- Using PostgreSQL, Drupal requires the`pg_trm` extension. DDEV creates this extension automatically for you on `ddev start`.

#### Twig Debugging

With the default Drupal configuration, it’s very difficult to debug Twig templates; you need to use `development.services.yml` instead of `services.yml`. Add this line in your `settings.php` or `settings.local.php`. See discussion at [drupal.org](<https://www.drupal.org/forum/support/module-development-and-code-questions/2019-09-02/ddev-twig-debugging>) and the Drupal documentation.

```
$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/development.services.yml';
```

#### Drush and Xdebug

Drush 13+ disables Xdebug even when [Xdebug is enabled on DDEV](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>).

As per [Drush docs](<https://www.drush.org/13.x/commands/#xdebug>) you can:

- Enable it for a single Drush command by running: `ddev drush --xdebug`
- Set `DRUSH_ALLOW_XDEBUG=1` [environment variable](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>), allowing every Drush call to be run with Xdebug when the PHP extension is enabled.

#### Multisite

1. Start with the [DDEV Drupal 8 Multisite Recipe](<https://github.com/ddev/ddev-contrib/tree/master/recipes/drupal8-multisite>).
2. Update configuration files.

   1. Update each `site/{site_name}/settings.php`:

      ```
      /**
       * DDEV environments will have $databases (and other settings) set
       * by an auto-generated file. Make alterations here for this site
       * in a multisite environment.
       */
      elseif (getenv('IS_DDEV_PROJECT') == 'true') {
        /**
         * Alter database settings and credentials for DDEV environment.
         * Includes loading the DDEV-generated `default/settings.ddev.php`.
         */
        include $app_root . '/' . $site_path . '/settings.databases.ddev.inc';
      }
      ```
   2. Add a `settings.databases.ddev.inc` in each `site/{site_name}/`:

      ```
      /**
       * Fetch DDEV-generated database credentials and other settings.
       */
      require $app_root . '/sites/default/settings.ddev.php';

      /**
       * Alter default database for this site. `settings.ddev.php` will have
       * “reset” this to 'db'.
       */
      $databases['default']['default']['database'] = 'site_name';
      ```
   3. Update your [`web_environment`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_environment>) config option if you’re using site aliases:

      ```
      web_environment:
          # Make DDEV Drush shell PIDs last for entire life of the container
          # so `ddev drush site:set @alias` persists for all Drush connections.
          # https://chrisfromredfin.dev/posts/drush-use-ddev/
          - DRUSH_SHELL_PID=PERMANENT
      ```

### MODX Specifics

#### MODX Settings File

On [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>), DDEV manages MODX Revolution’s main configuration file, `core/config/config.inc.php`, for both MODX 2.x and 3.x. It writes the DDEV database credentials (database name, user, and password are all `db`; host is `db`) along with the MODX path and URL constants, so a project whose database has been imported or seeded connects and boots straight away, including the `/manager/` backend.

The generated file carries the `#ddev-generated` signature. If you want to take over the file and manage it yourself, remove that signature line and DDEV will respect your version and won’t overwrite it. DDEV also leaves a config file that was written by the MODX installer (which has no signature) alone.

The `config.core.php` stub files (at the web root and in `core/`, `manager/`, and `connectors/`) only define `MODX_CORE_PATH` and `MODX_CONFIG_KEY`; DDEV does not touch them.

### TYPO3 Specifics

#### Settings Files

On [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>), DDEV creates a `config/system/additional.php` file with database configuration in it.

#### Setup a Base Variant (since TYPO3 9.5)

Since TYPO3 9.5 you have to setup a `Site Configuration` for each site you like to serve. To be able to browse the site on your local environment, you have to set up a `Base Variant` in your `Site Configuration` depending on your local context. In this example we assume a `Application Context` `Development/DDEV` which can be set in the DDEV’s `config.yaml`:

```
web_environment:
    - TYPO3_CONTEXT=Development/DDEV
```

This variable will be available after the project start or restart.

Afterwards add a `Base Variant` to your `Site Configuration`:

```
baseVariants:
  -
    base: 'https://example.com.ddev.site/'
    condition: 'applicationContext == "Development/DDEV"'
```

See also [TYPO3 Documentation](<https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/SiteHandling/BaseVariants.html>).

### WordPress Specifics

#### WP-CLI and changing the docroot in config.yaml

[`ddev wp`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#wp>) defaults WP-CLI’s `path` to your project’s docroot, so WP-CLI still finds WordPress when the docroot is something other than the project root (`''`).

If WordPress does not live at the docroot, override that default with a `wp-cli.yml` file in the project root directory. [Bedrock](<https://roots.io/bedrock/>), for example, serves from `web` but keeps WordPress in `web/wp`, so its `wp-cli.yml` contains:

```
path: web/wp
```

A `--path` flag, an [alias](<https://make.wordpress.org/cli/handbook/references/config/#config-files>), and `wp-cli.local.yml` all take precedence over the DDEV default in the same way.

#### WordPress Environment Type

By default, [`wp_get_environment_type()`](<https://developer.wordpress.org/reference/functions/wp_get_environment_type/>) returns `production`. However, you can override it in one of two ways:

1. Setting an environment variable, such as with the following [ddev command](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>):

   ```
   ddev config --web-environment-add="WP_ENVIRONMENT_TYPE=local"
   ```
2. Defining the `WP_ENVIRONMENT_TYPE` constant:

   To do this, modify your `wp-config-ddev.php` file by [removing](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#what-if-i-dont-like-the-settings-files-or-gitignores-ddev-creates>) the `#ddev-generated` line and adding this code snippet:

   ```
   defined( 'WP_ENVIRONMENT_TYPE' ) || define( 'WP_ENVIRONMENT_TYPE', 'local' );
   ```

# Commands

You can tell DDEV what to do by running its commands. This page details each of the available commands and their options, or flags.

> [!TIP]
>
> **Using TUI (Terminal UI)**
>
> Running `ddev` without any arguments will launch the [interactive dashboard](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#interactive-dashboard>) in your terminal.
>
> To disable the dashboard and show the classic help text instead, set [`no_tui: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_tui>) in your global configuration (`$HOME/.ddev/global_config.yaml`), or set the environment variable `DDEV_NO_TUI=true`.

Type `ddev help` or `ddev --help` or `ddev -h` to see this list in your terminal:

```
→  ddev help
Create and maintain a local web development environment.
Docs: https://docs.ddev.com
Support: https://docs.ddev.com/en/stable/users/support

Usage:
  ddev [command]

Available Commands:
  auth             A collection of authentication commands
  blackfire        Enable or disable blackfire.io profiling (global shell web container command)
  clean            Removes items ddev has created
  composer         Executes a composer command within the web container
...
```

Use [`ddev help`](<#help>) to learn more about a specific command, like this example for [`ddev describe`](<#describe>):

```
→  ddev help describe
Get a detailed description of a running ddev project. Describe provides basic
information about a ddev project, including its name, location, url, and status.
It also provides details for MySQL connections, and connection information for
additional services like Mailpit. You can run 'ddev describe' from
a project directory to describe that project, or you can specify a project to describe by
running 'ddev describe <projectname>'.

Usage:
  ddev describe [projectname] [flags]

Aliases:
  describe, status, st, desc

Examples:
ddev describe
ddev describe <projectname>
ddev status
ddev st

Flags:
  -h, --help   help for describe

Global Flags:
  -j, --json-output   If true, user-oriented output will be in JSON format.
```

## Global Flags

Two flags are available for every command:

- `--help` or `-h`: Outputs more information about a command rather than executing it.
- `--json-output` or `-j`: Format user-oriented output in JSON.

---

## `add-on`

*Aliases: `addon`, `add-ons`, `addons`.*

[Add-on](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>) commands.

Environment variables:

- `DDEV_GITHUB_TOKEN`: [GitHub token](<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens>) for `ddev add-on` requests to avoid rate limiting. No privileges required for public repositories, scopes are only needed for [private repositories](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/#private-add-ons>).

  ```
  export DDEV_GITHUB_TOKEN=<your-github-token>
  ddev add-on list
  ```
- `GH_TOKEN`: Alternative GitHub token variable (lower priority than `DDEV_GITHUB_TOKEN`).
- `GITHUB_TOKEN`: Alternative GitHub token variable (lowest priority).

### `add-on get`

*Alias: `add-on install`.*

Download an add-on (service, provider, etc.). Dependencies declared in the add-on’s `install.yaml` are installed automatically unless `--skip-deps` is used.

Flags:

- `--skip-deps`: Skip installing add-on dependencies (default `false`)
- `--project <projectName>`: Specify a project to install the add-on into. Defaults to checking for a project in the current directory.
- `--version <version>`: Specify a version, branch name, or commit SHA to download
- `--default-branch`: Install from the last commit in the default branch (default `false`)
- `--pr <number>`: Install from a pull request number
- `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`)

Note: The `--version`, `--default-branch`, and `--pr` flags are mutually exclusive.

Example:

```
# Download the official Redis add-on
ddev add-on get ddev/ddev-redis

# Get debug info about `ddev add-on get` failure
ddev add-on get ddev/ddev-redis --verbose

# Download the official Redis add-on, version v1.0.4
ddev add-on get ddev/ddev-redis --version v1.0.4

# Download the official Redis add-on from the main branch
ddev add-on get ddev/ddev-redis --version main

# Download the official Redis add-on from a specific commit SHA
ddev add-on get ddev/ddev-redis --version b50ac77

# Download the official Redis add-on from the latest commit in the default branch
ddev add-on get ddev/ddev-redis --default-branch

# Download the official Redis add-on from pull request #54
ddev add-on get ddev/ddev-redis --pr 54

# Download the Drupal Solr add-on from its v1.2.3 release tarball
ddev add-on get https://github.com/ddev/ddev-drupal-solr/archive/refs/tags/v1.2.3.tar.gz

# Download the Drupal Contrib add-on from its main branch tarball
ddev add-on get https://github.com/ddev/ddev-drupal-contrib/tarball/main

# Download the OpenSearch add-on from a pull request #15 tarball
ddev add-on get https://github.com/ddev/ddev-opensearch/tarball/refs/pull/15/head

# Copy an add-on available in another directory
ddev add-on get /path/to/package

# Copy an add-on from a tarball in another directory
ddev add-on get /path/to/tarball.tar.gz

# Download the official Redis add-on and install it into a project named "my-project"
ddev add-on get ddev/ddev-redis --project my-project

# Install an add-on without installing its dependencies
ddev add-on get ddev/ddev-redis-insight --skip-deps
```

**Automatic Dependency Installation:**

When an add-on declares dependencies in its `install.yaml`, DDEV will automatically install any missing dependencies before installing the add-on itself. Dependencies support the same formats as `ddev add-on get`:

- GitHub repositories: `ddev/ddev-redis`
- Direct URLs: `https://example.com/addon.tar.gz`

DDEV will detect and prevent circular dependencies with clear error messages.

In general, you can run `ddev add-on get` multiple times without doing any damage. Updating an add-on can be done by running `ddev add-on get <add-on-name>`, or use `ddev add-on update` to update every installed add-on at once. If you have changed an add-on file and removed the `#ddev-generated` marker in the file, that file will not be touched and DDEV will let you know about it.

> [!TIP]
>
> **How to install add-ons from private repositories?**
>
> See [Private Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/#private-add-ons>) for details.

### `add-on update`

Check installed add-ons for a newer release and install it. If no add-on names are provided, all installed add-ons are checked. Add-ons installed from a local directory or from a non-GitHub tarball URL can’t be checked automatically and are skipped.

Flags:

- `--dry-run`: Show which add-ons would be updated without installing anything (default `false`)
- `--project <projectName>`: Specify a project to update the add-ons for. Defaults to checking for a project in the current directory.
- `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`)
- `--yes`, `-y`: Skip confirmation prompt.

Example:

```
# Check and update all installed add-ons
ddev add-on update

# Update a single installed add-on
ddev add-on update redis
ddev add-on update ddev/ddev-redis

# See what would be updated without installing anything
ddev add-on update --dry-run

# Update add-ons for a specific project
ddev add-on update --project my-project
```

### `add-on remove`

Remove an installed add-on. Accepts the full add-on name, the short name of the repository, or with owner/repository format.

Flags:

- `--project <projectName>`: Specify a project to remove the add-on from. Defaults to checking for a project in the current directory.
- `--verbose`, `-v`: Output verbose error information with Bash `set -x` (default `false`)

Example:

```
ddev add-on remove redis
ddev add-on remove ddev-redis
ddev add-on remove ddev/ddev-redis
ddev add-on remove ddev/ddev-redis --project my-project
```

### `add-on list`

List available or installed DDEV add-ons.

Flags:

- `--installed`: List installed add-ons
- `--project <projectName>`: Specify the project for which to list add-ons. Can only be used with the `--installed` flag. Defaults to checking for a project in the current directory.
- `--wrap-table`, `-W`: Display table with wrapped text instead of truncating.

Example:

```
# List all available add-ons
ddev add-on list

# List installed add-ons
ddev add-on list --installed

# List installed add-ons for a specific project
ddev add-on list --installed --project my-project

# List with full untruncated add-on names and descriptions
ddev add-on list --wrap-table
```

### `add-on search`

Search available DDEV add-ons by name or description.

Flags:

- `--wrap-table`, `-W`: Display table with wrapped text instead of truncating.

Example:

```
# Search for Redis-related add-ons
ddev add-on search redis

# Search for database-related add-ons
ddev add-on search database

# Search with multiple terms (all must be present)
ddev add-on search redis web

# Search with multiple terms using quotes (currently same behavior)
ddev add-on search "redis insight"

# Search with full untruncated output
ddev add-on search redis --wrap-table
```

## `aliases`

Shows all aliases for each command in the current context (global or project).

```
# Print a list of all available command aliases
ddev aliases
```

## `artisan`

*Alias: `art`.*

Run the `artisan` command; available only in projects of type `laravel`, and only available if `artisan` is in the project root.

```
# Show all artisan subcommands
ddev artisan list
```

## `asterios`

*Alias: `ast`.*

Run the `asterios` command; available only in projects of type `asterios`, and only available if `asterios` is in the project root.

```
# Show all asterios subcommands
ddev asterios list
```

## `auth`

Authentication commands.

### `auth ssh`

Add [SSH key authentication](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#ssh-into-containers>) to the `ddev-ssh-agent` container.

The command can be executed multiple times to add more keys, or you can use the `-f` flag for several individual keys for example `ddev auth ssh -f /path/to/first_id_rsa -f /path/to/second_id_rsa`.

If [`ssh_agent_upstream`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#ssh_agent_upstream>) is set, `ddev auth ssh` without flags lists the keys in that agent instead of adding keys.

To add a key held in a secret manager or CI variable without writing it to a file, pipe it in with `-f -`. The key must not have a passphrase. On traditional Windows, where `ssh_agent_upstream` isn’t available, this is how to use a key stored in 1Password; see [Using an Existing SSH Agent](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>).

Example:

```
# Add your SSH keys to the SSH agent container
ddev auth ssh
# Add your SSH keys from ~/custom/path/to/ssh directory
ddev auth ssh -d ~/custom/path/to/ssh
# Add your SSH keys from ~/.ssh/id_ed25519 and ~/.ssh/id_rsa files
ddev auth ssh -f ~/.ssh/id_ed25519 -f ~/.ssh/id_rsa
# Add a key from 1Password's CLI, or any command that prints a private key
op read "op://Private/deploy key/private key?ssh-format=openssh" | ddev auth ssh -f -
```

Flags:

- `--ssh-key-file`, `-f`: Path to SSH private key file, use the flag multiple times to add more keys, or `-` to read one key without a passphrase from stdin.
- `--ssh-key-path`, `-d`: Path to directory with SSH private key(s), use the flag multiple times to add more directories.

## `blackfire`

Enable or disable [Blackfire profiling](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/blackfire-profiling/index.md>) (global shell web container command).

```
# Display Blackfire profiling status
ddev blackfire status

# Start Blackfire profiling
ddev blackfire on

# Stop Blackfire profiling
ddev blackfire off
```

> [!TIP]
>
> There are synonyms for the `on` and `off` arguments that have the exact same effect:
>
> - `on`: `start`, `enable`, `true`
> - `off`: `stop`, `disable`, `false`

## `cake`

Run the `cake` command; available only in projects of type `cakephp`, and only available if `cake.php` is in bin folder.

```
# Show all cake subcommands
ddev cake
```

## `clean`

Removes items DDEV has created. (See [Uninstalling DDEV](<https://ddev.github.io/ddev/en/stable/users/usage/uninstall/index.md>).)

Flags:

- `--all`, `-a`: Clean all DDEV projects.
- `--dry-run`: Run the clean command without deleting.
- `--yes`, `-y`: Skip confirmation prompt.

Example:

```
# Preview cleaning all projects without actually removing anything
ddev clean --dry-run --all

# Clean all projects
ddev clean --all

# Clean my-project and my-other-project
ddev clean my-project my-other-project
```

## `composer`

*Alias: `co`.*

Executes a [Composer command](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#ddev-and-composer>) within the web container.

`ddev composer create-project` is a special command that is an adaptation of `composer create-project`. See [DDEV and Composer](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#ddev-and-composer>) for more information.

Example:

```
# Install Composer packages
ddev composer install
```

Example of `ddev composer create-project`:

```
# Create a new Drupal project in the current directory
ddev composer create-project drupal/recommended-project .
```

## `config`

Create or modify a DDEV project’s configuration in the current directory. By default, `ddev config` will not change configuration that already exists in your `.ddev/config.yaml`, it will only make changes you specify with flags. However, if you want to autodetect everything, `ddev config --update` will usually do everything you need.

> [!TIP]
>
> **You can also set these via YAML!**
>
> These settings, plus a few more, can be set by editing stored [Config Options](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>).

Example:

```
# Start interactive project configuration
ddev config

# Accept defaults on a new project. This is the same as hitting <RETURN>
# on every question in `ddev config`
ddev config --auto

# Detect docroot, project type (except for `generic` type),
# and expected defaults for an existing project
ddev config --update

# Configure a Drupal project with a `web` document root
ddev config --docroot=web --project-type=drupal

# Switch the project’s default `nginx-fpm` to `apache-fpm`
ddev config --webserver-type=apache-fpm
```

Flags:

- `--additional-fqdns`: Comma-delimited list of project FQDNs or `--additional-fqdns=""` to remove any configured FQDNs.
- `--additional-hostnames`: Comma-delimited list of project hostnames or `--additional-hostnames=""` to remove any configured additional hostnames.
- `--auto`: Automatically run config without prompting.
- `--bind-all-interfaces`: Bind host ports on all interfaces, not only on the localhost network interface.
- `--composer-root`: The relative path, from the project root, to the directory containing `composer.json`. (This is where all Composer-related commands are executed.)
- `--composer-root-default`: Unset a `web` service Composer root directory override, the same as `--composer-root=""`.
- `--composer-version`: Specify override for Composer version in the web container. This may be `""`, `"2"`, `"2.2"`, `"stable"`, `"preview"`, `"snapshot"`, or a specific version.
- `--corepack-enable`: Whether to run `corepack enable` on Node.js configuration.
- `--database`: Specify the database `type:version` to use (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#database>)).
- `--db-image`: Set the `db` container image ([for advanced use only](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#dbimage>)).
- `--db-image-default`: Set the default `db` container image, the same as `--db-image=""`.
- `--db-working-dir`: Override the default working directory for the `db` service.
- `--db-working-dir-default`: Unset a `db` service working directory override, the same as `--db-working-dir=""`.
- `--dbimage-extra-packages`: Comma-delimited list of Debian packages that should be added to `db` container when the project is started or `--dbimage-extra-packages=""` to remove previously configured packages.
- `--ddev-version-constraint`: Specify a `ddev_version_constraint` to validate `ddev` against.
- `--default-container-timeout`: Default time in seconds that DDEV waits for all containers to become ready on start (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#default_container_timeout>)).
- `--disable-settings-management`: Prevent DDEV from creating or updating CMS settings files.
- `--disable-upload-dirs-warning`: Disable warnings about `upload-dirs` not being set when using `--performance-mode=mutagen`.
- `--docker-buildx-version`: Control which `docker-buildx` plugin to use (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#docker_buildx_version>)).
- `--docroot`: Provide the relative docroot of the project, like `docroot` or `htdocs` or `web`, defaults to empty, the current directory.
- `--fail-on-hook-fail`: Decide whether `ddev start` should be interrupted by a failing hook.
- `--host-db-port`: The `db` container’s localhost-bound port.
- `--host-https-port`: The `web` container’s localhost-bound HTTPS port.
- `--host-webserver-port`: The `web` container’s localhost-bound HTTP port.
- `--mailpit-http-port`: Router port to be used for Mailpit HTTP access (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#mailpit_http_port>)).
- `--mailpit-https-port`: Router port to be used for Mailpit HTTPS access (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#mailpit_https_port>)).
- `--ngrok-args`: Provide extra args to `ngrok` in `ddev share` (deprecated: use [`share_provider_args`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#share_provider_args>) in `.ddev/config.yaml`).
- `--no-project-mount`: Whether to skip mounting project code into the `web` container.
- `--nodejs-root`: The relative path, from the project root, to the directory containing the Node.js version file (see [`nodejs_root`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#nodejs_root>)).
- `--nodejs-version`: Specify the Node.js version to use (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#nodejs_version>)).
- `--omit-containers`: Comma-delimited list of container types that should not be started when the project is started.
- `--performance-mode`: Performance optimization mode, possible values are `global`, `none`, `mutagen`.
- `--performance-mode-reset`: Reset performance mode to global configuration.
- `--php-version`: PHP version that will be enabled in the `web` container (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#php_version>)).
- `--project-name`: Provide the project name of project to configure (normally the same as the last part of directory name).
- `--project-tld`: Set the top-level domain to be used for projects (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#project_tld>)).
- `--project-type`: Provide [the project type](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#type>) of project to configure. This is autodetected and this flag is necessary only to override the detection.
- `--router-http-port`: The router HTTP port for this project (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_http_port>)).
- `--router-https-port`: The router HTTPS port for this project (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_https_port>)).
- `--share-default-provider`: Set the default share provider for the project (`ngrok`, `cloudflared`, or custom). Can be overridden globally with `ddev config global --share-default-provider=<provider>`.
- `--share-provider-args`: Provide extra args to the share provider in `ddev share`.
- `--show-config-location`: Output the location of the `.ddev/config.yaml` file if it exists, or error that it doesn’t exist.
- `--timezone`: Specify timezone for containers and PHP, like `Europe/London` or `America/Denver` or `GMT` or `UTC`. If unset, DDEV will attempt to derive it from the host system timezone.
- `--update`: Update project settings based on detection and `project-type` overrides (except for `generic` type).
- `--upload-dirs`: Set the project’s upload directories, the destination directories of the `ddev import-files` command, or `--upload-dirs=""` to remove previously configured values.
- `--use-dns-when-possible`: Use DNS for hostname resolution instead of `/etc/hosts` when possible (default `true`).
- `--web-environment`: Set the environment variables in the `web` container: `--web-environment="TYPO3_CONTEXT=Development,SOMEENV=someval"` or `--web-environment=""` to remove previously configured values.
- `--web-environment-add`: Append environment variables to the `web` container: `--web-environment-add="TYPO3_CONTEXT=Development,SOMEENV=someval"`
- `--web-image`: Set the `web` container image ([for advanced use only](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webimage>)).
- `--web-image-default`: Set the default `web` container image, the same as `--web-image=""`.
- `--web-working-dir`: Override the default working directory for the `web` service.
- `--web-working-dir-default`: Unset a `web` service working directory override, the same as `--web-working-dir=""`.
- `--webimage-extra-packages`: Comma-delimited list of Debian packages that should be added to `web` container when the project is started or `--webimage-extra-packages=""` to remove any previously configured packages.
- `--webserver-type`: Set the project’s desired web server type: `nginx-fpm`, `apache-fpm`, `generic` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webserver_type>)).
- `--working-dir-defaults`: Unset all service working directory overrides.
- `--xdebug-enabled`: Whether Xdebug is enabled in the `web` container.
- `--xhprof-mode`: XHProf mode, possible values are `global`, `prepend`, `xhgui` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xhprof_mode>)).
- `--xhprof-mode-reset`: Reset XHProf mode to global configuration.

### `config global`

Change global configuration.

```
# Opt out of sharing anonymized usage information
ddev config global --instrumentation-opt-in=false

# Skip the SSH agent for all projects
ddev config global --omit-containers=ddev-ssh-agent
```

- `--fail-on-hook-fail`: If true, `ddev start` will fail when a hook fails.
- `--instrumentation-opt-in`: Whether to allow [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>) with `--instrumentation-opt-in=true` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#instrumentation_opt_in>)).
- `--internet-detection-timeout-ms`: Increase timeout when checking internet timeout, in milliseconds (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#internet_detection_timeout_ms>)).
- `--letsencrypt-email`: Email associated with Let’s Encrypt, `ddev global --letsencrypt-email=me@example.com`.
- `--mailpit-http-port`: The default Mailpit HTTP port for all projects, can be overridden by project configuration (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#mailpit_http_port>)).
- `--mailpit-https-port`: The default Mailpit HTTPS port for all projects, can be overridden by project configuration (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#mailpit_https_port>)).
- `--no-bind-mounts`: If `true`, don’t use bind-mounts. Useful for environments like remote Docker where bind-mounts are impossible.
- `--no-tui`: If `true`, disable the interactive dashboard and show the classic help text instead (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#no_tui>)).
- `--omit-containers`: For example, `--omit-containers=ddev-ssh-agent` or `--omit-containers=""`.
- `--omit-project-name-by-default`: If `true`, `ddev config` will not write the `name` field to `.ddev/config.yaml` unless explicitly set with `--project-name` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#omit_project_name_by_default>)).
- `--omit-snapshot-on-delete`: If `true`, `ddev delete` will not take a snapshot before deleting a project (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#omit_snapshot_on_delete>)).
- `--performance-mode`: Performance optimization mode, possible values are `none`, `mutagen`.
- `--performance-mode-reset`: Reset performance optimization mode to operating system default (`none` for Linux and WSL2, `mutagen` for macOS and traditional Windows).
- `--project-tld`: Set the default top-level domain to be used for all projects, can be overridden by project configuration (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#project_tld>)).
- `--router-bind-all-interfaces`: Bind host router ports on all interfaces, not only on the localhost network interface.
- `--router-http-port`: The default router HTTP port for all projects, can be overridden by project configuration (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_http_port>)).
- `--router-https-port`: The default router HTTPS port for all projects, can be overridden by project configuration (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_https_port>)).
- `--simple-formatting`: If `true`, use simple formatting for tables and implicitly set `NO_COLOR=1`.
- `--ssh-agent-upstream`: Make `ddev-ssh-agent` relay to an existing SSH agent: `host` for the host’s agent, or the path to an agent socket; empty uses DDEV’s own agent (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#ssh_agent_upstream>)).
- `--table-style`: Table style for `ddev list` and `ddev describe`, possible values are `default`, `bold`, `bright` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#table_style>)).
- `--traefik-monitor-port`: Can be used to change the Traefik monitor port in case of port conflicts, for example `ddev config global --traefik-monitor-port=11999` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#traefik_monitor_port>)).
- `--use-hardened-images`: If `true`, use more secure ‘hardened’ images for an actual internet deployment.
- `--use-letsencrypt`: Enables experimental Let’s Encrypt integration, `ddev config global --use-letsencrypt` or `ddev config global --use-letsencrypt=false`.
- `--web-environment`: Set the environment variables in the `web` container: `--web-environment="TYPO3_CONTEXT=Development,SOMEENV=someval"`
- `--web-environment-add`: Append environment variables to the `web` container: `--web-environment-add="TYPO3_CONTEXT=Development,SOMEENV=someval"`
- `--wsl2-no-windows-hosts-mgt`: WSL2 only; make DDEV ignore Windows-side hosts file ([for advanced use only](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#wsl2_no_windows_hosts_mgt>)).
- `--xdebug-ide-location`: For less usual IDE locations specify where the IDE is running for Xdebug to reach it ([for advanced use only](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>)).
- `--xhprof-mode`: XHProf mode, possible values are `prepend`, `xhgui` (see [default](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xhprof_mode>)).
- `--xhprof-mode-reset`: Reset XHProf mode to default.

## `console`

Run the `console` command; available only in projects of type `symfony` and `shopware6`, and only available if `bin/console` exists.

```
# Show all Symfony console subcommands
ddev console list
```

## `craft`

Run a [Craft CMS command](<https://craftcms.com/docs/4.x/console-commands.html>) inside the web container (global shell web container command).

Example:

```
# Run pending Craft migrations and apply pending project config changes
ddev craft up
```

## `dbeaver`

Open [DBeaver](<https://dbeaver.io/>) with the current project’s database (global shell host container command). This command is only available if `DBeaver.app` is installed as `/Applications/DBeaver.app` for macOS, if `dbeaver.exe` is installed to all users as `C:/Program Files/dbeaver/dbeaver.exe` for WSL2 and Windows, and if `dbeaver` (or another binary like `dbeaver-ce`) available inside `/usr/bin` for Linux (Flatpak and snap support included).

Example:

```
# Open the current project’s database in DBeaver
ddev dbeaver
```

## `delete`

Remove all information, including the database, for an existing project.

Flags:

- `--all`, `-a`: Delete all projects.
- `--clean-containers`: Clean up all DDEV Docker containers not required by this version of DDEV. (default `true`)
- `--omit-snapshot`, `-O`: Omit/skip database snapshot.
- `--yes`, `-y`: Skip confirmation prompt.

Example:

```
# Delete my-project and my-other-project
ddev delete my-project my-other-project

# Delete the current project without taking a snapshot or confirming
ddev delete --omit-snapshot --yes
```

### `delete images`

With `--all`, it deletes all `ddev/ddev-*` Docker images.

Flags:

- `--all`, `-a`: If set, deletes all Docker images created by DDEV.
- `--yes`, `-y`: Skip confirmation prompt.

Example:

```
# Delete images
ddev delete images

# Delete images and skip confirmation
ddev delete images -y

# Delete all DDEV-created images
ddev delete images --all
```

## `describe`

*Aliases: `status`, `st`, `desc`.*

Get a detailed description of a running DDEV project.

Example:

```
# Display details for the current project
ddev describe

# Display details for my-project
ddev describe my-project
```

## `dotenv`

Commands for managing the contents of `.env` files.

See [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) for which filename reaches which service, the order the files override each other in, and where to keep a secret.

### `dotenv get`

Get the value of an environment variable from a `.env` file. Provide the path relative to the project root when specifying the file.

Example:

```
# Get APP_KEY from $DDEV_APPROOT/.env
ddev dotenv get .env --app-key

# Get ENV_KEY from $DDEV_APPROOT/.ddev/.env.web
ddev dotenv get .ddev/.env.web --env-key

# Get REDIS_TAG from $DDEV_APPROOT/.ddev/.env.redis
ddev dotenv get .ddev/.env.redis --redis-tag

# Get API_KEY from the gitignored $DDEV_APPROOT/.ddev/.env.web.local
ddev dotenv get .ddev/.env.web.local --api-key
```

### `dotenv global get`

Get the value of an environment variable from a global `.env` file. Name the file as `.ddev/<file>`, the same way as in a project; it is read from the [global DDEV directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>).

Example:

```
# Get API_URL from the global .env.web
ddev dotenv global get .ddev/.env.web --api-url

# Get API_KEY from the gitignored global .env.web.local
ddev dotenv global get .ddev/.env.web.local --api-key
```

### `dotenv global set`

*Alias: `dotenv global add`.*

Create or update a global `.env` file, which applies to every project, with values specified via long flags from the command line. Flags in the format `--env-key=value` will be converted to environment variable names like `ENV_KEY="value"`. Name the file as `.ddev/<file>`, the same way as in a project; it is written to the [global DDEV directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>).

Example:

```
# Set API_URL for the web service of every project
ddev dotenv global set .ddev/.env.web --api-url=https://example.com

# Set two variables for the db service of every project
ddev dotenv global set .ddev/.env.db --extra value --another-key "extra value"

# Set API_KEY in a gitignored file, for the web service of every project
ddev dotenv global set .ddev/.env.web.local --api-key=secret
```

### `dotenv set`

*Alias: `dotenv add`.*

Create or update a `.env` file with values specified via long flags from the command line. Flags in the format `--env-key=value` will be converted to environment variable names like `ENV_KEY="value"`. Provide the path relative to the project root when specifying the file.

Example:

```
# Set APP_KEY in the application's own $DDEV_APPROOT/.env
ddev dotenv set .env --app-key=value

# Set two variables for the web service
ddev dotenv set .ddev/.env.web --extra value --another-key "extra value"

# Set REDIS_TAG for the redis service
ddev dotenv set .ddev/.env.redis --redis-tag 7-bookworm

# Set API_URL for the web service, in a file labeled for one add-on
ddev dotenv set .ddev/.env.web.myaddon --api-url=https://example.com

# Set API_KEY in a gitignored file, for the web service
ddev dotenv set .ddev/.env.web.local --api-key=secret
```

## `dr`

Run the Drupal `dr` CLI; available only in projects of type `drupal11` and `drupal12`, and only if `dr` is available in the project (Drupal 11.4+).

```
# Show dr status
ddev dr system:status
```

## `drush`

Run the `drush` command; available only in projects of type `drupal*` and `backdrop`, and only available if `drush` is in the project. On projects of type `drupal`, `drush` should be installed in the project itself, (`ddev composer require drush/drush`). On projects of type `drupal7` `drush` 8 is provided by DDEV.

```
# Show drush status/configuration
ddev drush st
```

## `exec`

*Alias: `.`.*

[Execute a shell command in the container](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#executing-commands-in-containers>) for a service. Uses the web service by default.

To run your command in a different project, run `ddev exec --project <project> <cmd>`. To run your command in a different service container, run `ddev exec --service <service> <cmd>`. Use the `--raw` flag if you’d like to run a raw, uninterpreted command in a container.

Flags:

- `--dir`, `-d`: Define the execution directory within the container.
- `--raw`: Use raw exec (do not interpret with Bash inside container). (default `true`)
- `--project`, `-p`: Specify a project where to run the command. Defaults to the project in the current directory.
- `--service`, `-s`: Define the service to connect to. (e.g. `web`, `db`) (default `"web"`)
- `--quiet`, `-q`: Suppress detailed error message.
- `--user`, `-u`: Defines the user to run shell as.

Example:

```
# List the web container's docroot contents
ddev exec ls /var/www/html

# List the web container's docroot contents for a specific project
ddev exec --project my-other-project ls /var/www/html

# List the web container's vendor directory contents
ddev exec --dir /var/www/html/vendor ls

# Output a long, recursive list of the files in the web container
ddev exec --raw -- ls -lR

# Suppress detailed error message:
# "Failed to execute command `exit 1`: exit status 1"
ddev exec -q "exit 1"

# List the db container's /root directory contents as root user
ddev exec -s db -u root ls -la /root
```

## `export-db`

Dump a database to a file or to stdout.

With `--file` and no `--compression`, the compression type comes from the file extension: `.gz`, `.zst`, `.xz`, `.bz2`, or `.sql`/`.mysql` for none. Any other extension, and output to stdout, uses gzip.

Flags:

- `--compression`: Compression type: `gzip`, `zstd`, `xz`, `bzip2`, or `none`. `zstd` is not available with MariaDB 5.5.
- `--database`, `-d`: Target database to export from (default `"db"`)
- `--file`, `-f`: Path to a SQL dump file to export to

The older `--gzip`, `--gzip=false`, `--xz`, and `--bzip2` flags still work.

Example:

```
# Dump and compress the current project’s database to `/tmp/db.sql.gz`
ddev export-db --file=/tmp/db.sql.gz

# Dump the current project’s database with zstd compression
ddev export-db --file=/tmp/db.sql.zst

# Dump the current project’s database, without compressing it, to `/tmp/db.sql`
ddev export-db --file /tmp/db.sql

# Dump and compress the current project’s `foo` database instead of `db`
ddev export-db --database=foo --file=/tmp/db.sql.gz

# Output the current project’s database and use `>` to write to `/tmp/db.sql.gz`
ddev export-db > /tmp/db.sql.gz

# Output the current project’s database with zstd compression
ddev export-db --compression=zstd > /tmp/db.sql.zst

# Dump my-project’s database, without compressing it, to `/tmp/my-project.sql`
ddev export-db my-project --file=/tmp/my-project.sql
```

## `heidisql`

Open [HeidiSQL](<https://www.heidisql.com/>) with the current project’s database (global shell host container command). This command is available on Windows, WSL2, and Linux.

Requirements by platform:

- **Windows**: HeidiSQL installed at `C:\Program Files\HeidiSQL\Heidisql.exe`
- **WSL2**: HeidiSQL accessible via `/mnt/c/Program Files/HeidiSQL/heidisql.exe`
- **Linux**: HeidiSQL available at `/usr/bin/heidisql` or at `/usr/local/bin/heidisql`

Example:

```
# Open the current project's database in HeidiSQL
ddev heidisql
```

## `help`

Help about any command.

Example:

```
# Illuminate the virtues of the `describe` command
ddev help describe
```

## `hostname`

Manage your hostfile entries.

Flags:

- `--remove`, `-r`: Remove the provided hostname - ip correlation.
- `--remove-inactive`, `-R`: Remove hostnames of inactive projects.

Example:

```
ddev hostname somesite.example.com 127.0.0.1
```

`ddev hostname` runs a special `ddev-hostname` or `ddev-hostname.exe` executable to elevate privileges. The extra executable is installed/updated by DDEV’s normal installation process or by the Windows installation process. On WSL2, `ddev-hostname.exe` is provided by the `ddev-wsl2` package and by the Windows installer. Install the package with `sudo apt-get update && sudo apt-get install -y ddev-wsl2` or the equivalent for your Linux system.

## `import-db`

[Import a SQL file](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/index.md>) into the project.

Flags:

- `--database`, `-d`: Target database to import into (default `"db"`)
- `--extract-path`: Path to extract within the archive
- `--file`, `-f`: Path to a SQL dump in `.sql`, `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tgz`, or `.zip` format
- `--no-drop`: Do not drop the database before importing
- `--no-progress`: Do not output progress

Example:

```
# Start the interactive import utility
ddev import-db

# Import the `.tarballs/db.sql` dump to the project database
ddev import-db --file=.tarballs/db.sql

# Import the compressed `.tarballs/db.sql.gz` dump to the project database
ddev import-db --file=.tarballs/db.sql.gz

# Import the compressed `.tarballs/db.sql.gz` dump to a `other_db` database
ddev import-db --database=additional_db --file=.tarballs/db.sql.gz

# Import the `db.sql` dump to the project database
ddev import-db < db.sql

# Import the `db.sql` dump to the `my-project` default database
ddev import-db my-project < db.sql

# Uncompress `db.sql.gz` and pipe the result to the `import-db` command
gzip -dc db.sql.gz | ddev import-db
```

## `import-files`

Pull the uploaded files directory of an existing project to the default public upload directory of your project. More usage information and a description of the Tar or ZIP archive is in the [usage section](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#ddev-import-files>).

Flags:

- `--extract-path`: Path to extract within the archive.
- `--source`, `-s`: Path to the source directory or source archive in `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`, `.tgz`, or `.zip` format.
- `--target`, `-t`: Target upload dir, defaults to the first upload dir.

Example:

```
# Extract+import `/path/to/files.tar.gz` to the project’s first upload directory
ddev import-files --source=/path/to/files.tar.gz

# Import `/path/to/dir` contents to the project’s first upload directory
ddev import-files --source=/path/to/dir

# Import `.tarballs/files.tar.xz` contents to the project’s `../private` upload directory
ddev import-files --source=.tarballs/files.tar.xz --target=../private

# Import `/path/to/dir` contents to the project’s `sites/default/files` upload directory
ddev import-files -s=.tarballs/files.tar.gz -t=sites/default/files
```

## `launch`

Launch a browser with the current site (global shell host container command). If the current project is not running, it will be started first.

Flags:

- `--mailpit`, `-m`: Open Mailpit.
- `--print-url`: Print the URL instead of opening a browser. The output is the resolved URL itself, with no prefix, so it can be used directly in scripts. Useful where no browser is available (SSH sessions, containers, CI).
- `--qr`: Print the URL and its QR code instead of opening a browser. Only useful for a URL a phone can reach, which `*.ddev.site` is not.

The environment variable `DDEV_LAUNCH_PRINT_URL=true` behaves like the `--print-url` flag. Unlike the flag it is inherited by nested `ddev launch` invocations (for example from custom commands or add-ons that call `ddev launch` internally), so wrappers and external tools can capture the URL. Unlike `DDEV_DEBUG=true` or `DDEV_VERBOSE=true`, which print the URL with a `FULLURL` prefix and enable global debug logging, it prints only the URL.

> [!TIP]
>
> **How to disable HTTP redirect to HTTPS?**
>
> Recommendations for:
>
> - [Google Chrome](<https://stackoverflow.com/q/73875589>)
> - [Mozilla Firefox](<https://stackoverflow.com/q/30532471>)
> - [Safari](<https://stackoverflow.com/q/46394682>)

Example:

```
# Open your project’s base URL in the default browser
ddev launch

# Open Mailpit in the default browser
ddev launch --mailpit

# Print your project’s base URL instead of opening a browser
ddev launch --print-url

# Print a QR code for a URL, to scan with a phone
ddev launch --qr https://your.example.com

# Open your project’s base URL appended with `temp/phpinfo.php`
ddev launch temp/phpinfo.php

# Open the full URL (any website) in the default browser
ddev launch https://your.ddev.site

# Open your project’s base URL using a specific port
ddev launch :3000
```

## `list`

*Aliases: `l`, `ls`.*

List projects.

Flags:

- `--active-only`, `-A`: If set, only currently active projects will be displayed.
- `--continuous`: If set, project information will be emitted until the command is stopped.
- `--continuous-sleep-interval`, `-I`: Time in seconds between `ddev list --continuous` output lists. (default `1`)
- `--type`, `-t`: Show only projects of this type (e.g. `drupal`, `wordpress`, `php`).
- `--wrap-table`, `-W`: Display table with wrapped text if required.

Example:

```
# List all projects
ddev list

# List all running projects
ddev list --active-only

# List all WordPress projects
ddev list --type wordpress
```

## `logs`

Get the logs from your running services.

Flags:

- `--follow`, `-f`: Follow the logs in real time.
- `--service`, `-s`: Defines the service to retrieve logs from (e.g. `web`, `db`). (default `"web"`)
- `--tail`: How many lines to show.
- `--time`, `-t`: Add timestamps to logs.

Example:

```
# Display recent logs from the current project’s web server
ddev logs

# Stream logs from the current project’s web server in real time
ddev logs -f

# Display recent logs from the current project’s database server
ddev logs -s db

# Display recent logs from my-project’s database server
ddev logs -s db my-project
```

## `magento`

Run the `magento` command; available only in projects of type `magento2`, and only works if `bin/magento` is in the project.

```
# Show all magento subcommands
ddev magento list
```

## `maho`

Run the `maho` command; available only in projects of type `maho`, and only works if the `maho` script is in the project root (it is copied there by Composer on install).

```
# Show all maho subcommands
ddev maho list

# Flush the cache
ddev maho cache:flush
```

## `mailpit`

Launch a browser with mailpit for the current project (global shell host container command).

Example:

```
# Open Mailpit in the default browser
ddev mailpit
```

## `mariadb`

Run MariaDB client in the database container (global shell db container command). This is only available on projects that use the `mariadb` database type. (This is the same as the `mysql` command, but MariaDB is changing the name of their CLI client.)

Example:

```
# Run the database container’s MariaDB client as root user
ddev mariadb

# Run the database container’s MariaDB client as db user
ddev mariadb -udb -pdb

# Pipe the `SHOW TABLES;` command to the MariaDB client to see a list of tables
echo 'SHOW TABLES;' | ddev mariadb
```

## `mutagen`

Commands for [Mutagen](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) status and sync, etc.

### `mutagen logs`

Show Mutagen logs for debugging.

Flags:

- `--verbose`: Show full Mutagen logs.

Example:

```
# Stream Mutagen’s logs in real time
ddev mutagen logs

# Stream Mutagen’s more detailed logs in real time
ddev mutagen logs --verbose
```

### `mutagen monitor`

Monitor Mutagen status.

Example:

```
# Start Mutagen’s sync process and monitor its status in real time
ddev mutagen sync && ddev mutagen monitor
```

### `mutagen reset`

Stops a project and removes the Mutagen Docker volume.

```
# Reset Mutagen data for the current project
ddev mutagen reset

# Reset Mutagen data for my-project
ddev mutagen reset my-project
```

### `mutagen status`

*Alias: `mutagen st`.*

Shows Mutagen sync status.

Flags:

- `--verbose`, `-l`: Extended/verbose output for Mutagen status.

Example:

```
# Display Mutagen sync status for the current project
ddev mutagen status

# Display Mutagen sync status for my-project
ddev mutagen status my-project
```

### `mutagen sync`

Explicit sync for Mutagen.

Flags:

- `--verbose`: Extended/verbose output for Mutagen status.

Example:

```
# Initiate Mutagen sync for the current project
ddev mutagen sync

# Initiate Mutagen sync for my-project
ddev mutagen sync my-project
```

### `mutagen version`

Display the version of the Mutagen binary and the location of its components.

Example:

```
# Print Mutagen details
ddev mutagen version
```

## `mysql`

Run MySQL client in the database container (global shell db container command). This is only available on projects that use the `mysql` or `mariadb` database types.

Example:

```
# Run the database container’s MySQL client as root user
ddev mysql

# Run the database container’s MySQL client as db user
ddev mysql -udb -pdb

# Pipe the `SHOW TABLES;` command to the MySQL client to see a list of tables
echo 'SHOW TABLES;' | ddev mysql
```

## `npm`

Run [`npm`](<https://docs.npmjs.com/cli/commands/npm>) inside the web container (global shell web container command).

Example:

```
# Install JavaScript packages using `npm`
ddev npm install

# Update JavaScript packages using `npm`
ddev npm update
```

## `npx`

Run [`npx`](<https://docs.npmjs.com/cli/commands/npx>) inside the web container (global shell web container command).

Example:

```
# Initialize Biome in the project
ddev npx @biomejs/biome init

# Create a new Next.js app
ddev npx create-next-app@latest
```

## `php`

Run `php` inside the web container (global shell web container command).

Example:

```
# Output the web container’s PHP version
ddev php --version
```

## `poweroff`

*Alias: `powerdown`.*

Completely stop all projects and containers.

> [!TIP]
>
> This is the equivalent of running `ddev stop -a --stop-ssh-agent`.

Example:

```
# Stop all projects and containers
ddev poweroff
```

## `psql`

Run PostgreSQL client in the database container (global shell db container command). This is only available on projects that use the `postgres` database type.

Example:

```
# List available databases
ddev psql -l

# List tables in the default 'db' database
echo "\dt;" | ddev psql
```

## `pull`

Pull files and database using a configured [provider plugin](<https://ddev.github.io/ddev/en/stable/users/providers/index.md>).

Flags:

- `--environment=ENV1=val1,ENV2=val2`
- `--skip-confirmation`, `-y`: Skip confirmation step.
- `--skip-db`: Skip pulling database archive.
- `--skip-files`: Skip pulling file archive.
- `--skip-import`: Download archive(s) without importing them.

Example:

```
# Pull a backup from the configured Upsun project to use locally
ddev pull upsun

# Pull from Pantheon without confirming
ddev pull pantheon -y

# Pull the Upsun database only without confirming
ddev pull upsun --skip-files -y

# Pull the Acquia files only without confirming
ddev pull acquia --skip-db -y

# Download archives from Upsun without importing them
ddev pull upsun --skip-import

# Pull from Upsun overriding environment and token on the command line
ddev pull upsun --environment="PLATFORM_ENVIRONMENT=main,UPSUN_CLI_TOKEN=abcdeyourtoken"

# Pull from Pantheon overriding environment and token on the command line
ddev pull pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev,TERMINUS_MACHINE_TOKEN=abcdeyourtoken"

# Pull from Lagoon overriding project and environment on the command line
ddev pull lagoon --environment="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main"
```

## `push`

Push files and database using a configured [provider plugin](<https://ddev.github.io/ddev/en/stable/users/providers/index.md>).

Flags:

- `--environment=ENV1=val1,ENV2=val2`
- `--skip-confirmation`, `-y`: Skip confirmation step.
- `--skip-db`: Skip pushing database archive.
- `--skip-files`: Skip pushing file archive.

Example:

```
# Push local files and database to the configured Upsun project
ddev push upsun

# Push to Pantheon without confirming
ddev push pantheon -y

# Push database only to Upsun without confirming
ddev push upsun --skip-files -y

# Push files only to Acquia without confirming
ddev push acquia --skip-db -y

# Push to Upsun overriding environment and token on the command line
ddev push upsun --environment="PLATFORM_ENVIRONMENT=main,UPSUN_CLI_TOKEN=abcdeyourtoken"

# Push to Pantheon overriding environment and token on the command line
ddev push pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev,TERMINUS_MACHINE_TOKEN=abcdeyourtoken"

# Push to Lagoon overriding project and environment on the command line
ddev push lagoon --environment="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main"
```

## `querious`

Open [Querious](<https://www.araelium.com/querious>) with the current project’s MariaDB or MySQL database (global shell host container command). This is only available if `Querious.app` is installed as `/Applications/Querious.app`, and only for projects with `mysql` or `mariadb` databases.

Example:

```
# Open the current project’s database in Querious
ddev querious
```

## `restart`

Restart one or several projects.

With `--service`, only the named services get new containers, with their images built as `ddev start` builds them, and the rest of the project keeps running. This also brings back a service that is unhealthy or has crashed. A service in an [optional profile](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#optional-services>) has to be started first, with `ddev start --profiles` or `ddev restart --profiles`. Restarting `web` restarts the whole project, with the optional services that were started.

Flags:

- `--all`, `-a`: Restart all projects.
- `--no-cache`: Rebuild custom Docker image layers without cache.
- `--omit-snapshot`, `-O`: With `--reset-database`, skip the snapshot of the database being removed.
- `--profiles`: Start optional comma-separated Docker Compose profiles.
- `--reset-database`: Remove the project’s existing database and start over with a new one.
- `--seed-snapshot`: Seed a brand-new database volume from this snapshot name or file, instead of the stock starter database.
- `--service`, `-s`: Restart only these comma-separated services.
- `--skip-confirmation`, `-y`: Skip any confirmation steps.

Example:

```
# Restart the current project
ddev restart

# Restart the current project without using Docker cache
ddev restart --no-cache

# Restart my-project and my-other-project
ddev restart my-project my-other-project

# Restart all projects
ddev restart --all

# Restart the current project with the busybox profile, without Docker cache
ddev restart --profiles=busybox --no-cache

# Restart only the db service
ddev restart --service=db

# Restart only the solr and redis services, without Docker cache
ddev restart -s solr,redis --no-cache

# Throw away the current database and restart with a new, empty one
ddev restart --reset-database

# Reset and initialize with external snapshot without confirmation
ddev restart --reset-database --seed-snapshot=/tmp/newsnapshot-mariadb_11.8.zst -y
```

## `sake`

Run the `sake` command, only available for Silverstripe CMS projects and if the `sake` command is available in the `vendor/bin` folder.

Common commands:

- Build database: `ddev sake dev/build` (or `ddev sake db:build` from Silverstripe CMS 6 onwards)
- List of available tasks: `ddev sake dev/tasks` (or `ddev sake tasks` from Silverstripe CMS 6 onwards)

## `self-upgrade`

Output instructions for updating or upgrading DDEV. The command doesn’t perform the upgrade, but tries to provide instructions relevant to your installation.

Example:

```
→  ddev self-upgrade

DDEV appears to have been installed with install_ddev.sh, you can run that script again to update.
curl -fsSL https://ddev.com/install.sh | bash
```

## `sequelace`

Open [SequelAce](<https://sequel-ace.com/>) with the current project’s database (global shell host container command). This command is only available if `Sequel Ace.app` is installed as `/Applications/Sequel Ace.app`, and only for projects with `mysql` or `mariadb` databases.

Example:

```
# Open the current project’s database in SequelAce
ddev sequelace
```

## `share`

[Share the current project](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>) on the internet via a tunnel provider like ngrok or cloudflared.

The tunnel URL is also printed as a QR code, which you can scan to open it on a phone or tablet.

DDEV supports multiple share providers:

- **ngrok** (default) - Requires an [ngrok.com](<https://ngrok.com>) account
- **cloudflared** - Free, no account required. Requires [cloudflared](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation>) to be installed
- **Custom providers** - Add your own providers in `.ddev/share-providers/`

Flags:

- `--provider`: Share provider to use (ngrok, cloudflared, or custom).
- `--provider-args`: Arguments to pass to the share provider (overrides config file settings).
- `--ngrok-args`: (Deprecated) Use `--provider-args` instead.

The default provider can be configured globally with `ddev config global --share-default-provider=<provider>` or per-project with `ddev config --share-default-provider=<provider>`. See [`share_default_provider`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#share_default_provider>) for more details.

Provider-specific arguments can be configured in `.ddev/config.yaml` with [`share_provider_args`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#share_provider_args>).

Examples:

```
# Share the current project with the default provider (ngrok)
ddev share

# Share with cloudflared
ddev share --provider=cloudflared

# Share with cloudflared using a custom domain (named tunnel)
ddev share --provider=cloudflared --provider-args="--tunnel my-tunnel --hostname mysite.example.com"

# Share with ngrok, using domain `foo.ngrok-free.app`
ddev share --provider-args="--domain foo.ngrok-free.app"

# Share the current project using ngrok's basic-auth argument
ddev share --provider-args="--basic-auth username:pass1234"

# Share my-project with ngrok
ddev share my-project
```

## `snapshot`

Create a database snapshot for one or more projects.

This uses `xtrabackup` or `mariadb-backup` to create a database snapshot in the `.ddev/db_snapshots` directory. These are compatible with server backups using the same tools and can be restored with the [`snapshot restore`](<#snapshot-restore>) command.

See [Snapshotting and Restoring a Database](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#snapshotting-and-restoring-a-database>) for more detail, or [Database Management](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/index.md>) for more on working with databases in general.

Flags:

- `--all`, `-a`: Snapshot all projects. (Will start stopped or paused projects.)
- `--cleanup`, `-C`: Cleanup snapshots.
- `--list`, `-l`: List snapshots.
- `--name`, `-n`: Provide a name for the snapshot.
- `--uncompressed`: Write the snapshot as an uncompressed mariadb-backup/xtrabackup stream instead of compressing it. This skips decompression on restore, but the file can be roughly as large as the database’s datadir, many times bigger than a compressed snapshot. Not available for PostgreSQL projects. See [Snapshots](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#snapshots>) for when this unusual trade-off makes sense.
- `--yes`, `-y`: Skip confirmation prompt.

`ddev snapshot --list` also shows each snapshot’s compression: `zstd`, `gzip`, or `none` for an uncompressed snapshot. If the project is a Git worktree and a sibling worktree of the same project has snapshots of its own, those are listed too, with a `Worktree` column naming which one each came from.

Example:

```
# Take a database snapshot for the current project
ddev snapshot

# Take a database snapshot for the current project, named `my_snapshot_name`
ddev snapshot --name my_snapshot_name

# Take a snapshot for the current project, cleaning up existing snapshots
ddev snapshot --cleanup

# Delete a single snapshot by name without deleting all snapshots
ddev snapshot --cleanup --name my_snapshot_name

# Take a snapshot for the current project, cleaning existing snapshots and skipping prompt
ddev snapshot --cleanup -y

# List the current project’s snapshots
ddev snapshot --list

# Take a snapshot for each project
ddev snapshot --all

# Take an uncompressed snapshot, trading disk space for a faster restore
ddev snapshot --uncompressed
```

### `snapshot restore`

Restores a database snapshot, either by name from the `.ddev/db_snapshots` directory or by the path to a snapshot file elsewhere on disk. If the project is a Git worktree, snapshots from the same project checked out in other worktrees of the same repository are available too, whether picked interactively, restored by name, or via `--latest`.

Flags:

- `--force`, `-f`: Restore a snapshot made by a different version of the same database server, which may not succeed.
- `--latest`: Use the latest snapshot.

Example:

```
# Restore the most recent snapshot
ddev snapshot restore --latest

# Restore the previously-taken `my_snapshot_name` snapshot
ddev snapshot restore my_snapshot_name

# Restore a snapshot taken on an older version of the same database server
ddev snapshot restore --force my_snapshot_name

# Restore a snapshot file from outside the project
ddev snapshot restore ~/tmp/mysnapshot-mariadb_11.8.zst
```

A snapshot normally has to match the project’s configured database type and version exactly. `--force` lifts that for a different version of the same server, which the underlying restore doesn’t itself check for; the database may fail to come up, in which case [`ddev start --reset-database`](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#starting-over-with-a-new-database>) starts over. Restoring across database types (a MySQL snapshot into MariaDB, say) is still refused.

## `spark`

Run the `spark` command; available only in projects of type `codeigniter`, and only available if `spark` is in the project root.

```
# Show all spark subcommands
ddev spark list
```

## `ssh`

Starts a shell session in a service container. Uses the web service by default.

Flags:

- `--dir`, `-d`: Defines the destination directory within the container.
- `--service`, `-s`: Defines the service to connect to. (default `"web"`)
- `--user`, `-u`: Defines the user to run shell as.

Example:

```
# SSH into the current project’s web container
ddev ssh

# SSH into the current project’s database container
ddev ssh -s db

# SSH into the current project’s database container as root user
ddev ssh -s db -u root

# SSH into the web container for my-project
ddev ssh my-project

# SSH into the docroot of the current project’s web container
ddev ssh -d /var/www/html
```

## `start`

*Alias: `add`*.

Start a DDEV project.

If you run `ddev start` in a directory that has no DDEV project but looks like a web project, DDEV shows the configuration `ddev config --auto` would create (name, URL, project type, docroot, PHP version, database, and web server) and asks whether to use it, customize it with the `ddev config` questions, or cancel. DDEV recognizes a directory as a web project when it detects a supported project type, or finds a `composer.json`, a `package.json`, or an `index.php` or `index.html` at the root or in a common docroot such as `web` or `public`. Without a terminal to ask in, as in CI or a script, or with `--skip-confirmation` (`-y`), `ddev start` doesn’t configure anything; use `ddev config --auto && ddev start` there instead.

Flags:

- `--all`, `-a`: Start all projects.
- `--no-cache`: Rebuild custom Docker image layers without cache.
- `--omit-snapshot`, `-O`: With `--reset-database`, skip the snapshot of the database being removed.
- `--profiles`: Start optional comma-separated Docker Compose profiles.
- `--reset-database`: Remove the project’s existing database and start over with a new one.
- `--seed-snapshot`: Seed a brand-new database volume from this snapshot name or file, instead of the stock starter database.
- `--skip-confirmation`, `-y`: Skip any confirmation steps.

Example:

```
# Start the current project
ddev start

# Start the current project without using Docker cache
ddev start --no-cache

# Start my-project and my-other-project
ddev start my-project my-other-project

# Start all projects
ddev start --all

# Throw away the current database and start over with a new, empty one
ddev start --reset-database

# Start over with a database seeded from a snapshot instead
ddev start --reset-database --seed-snapshot=my_snapshot_name
```

See [Seeding a Fresh Database from a Snapshot](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#seeding-a-fresh-database-from-a-snapshot>) and [Starting Over with a New Database](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#starting-over-with-a-new-database>).

## `stop`

*Aliases: `rm`, `remove`.*

Stop and remove the containers of a project. Does not lose or harm anything unless you add `--remove-data`.

Flags:

- `--all`, `-a`: Stop and remove all running or container-stopped projects and remove from global projects list.
- `--omit-snapshot`, `-O`: Omit/skip database snapshot.
- `--remove-data`, `-R`: Remove stored project data (MySQL, logs, etc.).
- `--snapshot`, `-S`: Create database snapshot.
- `--stop-ssh-agent`: Stop the `ddev-ssh-agent` container.
- `--unlist`, `-U`: Remove the project from global project list, so it won’t appear in [`ddev list`](<#list>) until started again.

Example:

```
# Stop the current project
ddev stop

# Stop my-project, my-other-project, and my-third-project
ddev stop my-project my-other-project my-third-project

# Stop all projects
ddev stop --all

# Stop all projects and the `ddev-ssh-agent` container
ddev stop --all --stop-ssh-agent

# Stop all projects and remove their data
ddev stop --remove-data
```

## `tableplus`

Open [TablePlus](<https://tableplus.com>) with the current project’s database (global shell host container command). This command is only available if `TablePlus.app` is installed as `/Applications/TablePlus.app`.

Example:

```
# Open the current project’s database in TablePlus
ddev tableplus
```

## `tablepro`

Open [TablePro](<https://tablepro.app>) with the current project’s database (global shell host container command). This command is only available if `TablePro.app` is installed as `/Applications/TablePro.app`.

Example:

```
# Open the current project’s database in TablePro
ddev tablepro
```

## `tui`

Launch the [interactive TUI dashboard](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#interactive-dashboard>).

Example:

```
# Launch DDEV TUI
ddev tui
```

## `typo3`

Run the `typo3` command; available only in projects of type `typo3`, and only works if `typo3` is in the `$PATH` inside the container; normally it’s in `vendor/bin/typo3` so will be found.

```
# Show typo3 site configuration
ddev typo3 site:show
```

## `utility`

*Aliases: `ut`, `debug`, `d`,`dbg`.*

A collection of utility and debugging commands, often useful for [troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/index.md>).

### `utility addon-update-checker`

Fetch and run the DDEV add-on update checker script from [https://ddev.com/s/addon-update-checker.sh](<https://ddev.com/s/addon-update-checker.sh>). This is a tool for add-on developers to verify their add-on’s scripts and tooling are up to date with the [`ddev-addon-template`](<https://github.com/ddev/ddev-addon-template>).

If the target directory contains `install.yaml`, the checker runs there. Otherwise, it scans immediate subdirectories for `install.yaml` and runs the checker in each one, which is useful when working in a workspace with multiple add-ons checked out alongside each other.

Flags:

- `--dir`, `-d`: Directory of the add-on to check, or a workspace containing multiple add-on directories (defaults to current directory).

Example:

```
# Run in the current add-on directory
ddev utility addon-update-checker

# Run in a specific add-on directory
ddev utility addon-update-checker -d /path/to/my-addon

# Run across all add-ons in a workspace
ddev utility addon-update-checker -d /path/to/my-addons-workspace
```

### `utility cd`

Uses shell built-in `cd` to change to a project directory. For example, `ddevcd some-project` will change directories to the project root of the project named `some-project`.

Note that this command can’t work until you make a small addition to your `.bashrc`, `.zshrc`, or `config.fish`.

```
# To see the explanation of what you need to do
ddev utility cd
# Where some-project is a project from the `ddev list`
ddevcd some-project
```

### `utility check-custom-config`

Display custom configuration files in the current project’s `.ddev` directory.

By default, shows only files that would warn on startup: user-created files and files with an unexpected `#ddev-generated` marker. Recognized add-on files and files with a `#ddev-silent-no-warn` marker are excluded.

Flags:

- `--all`: Show all custom configuration, annotating files with:

  - `(add-on <name>)` for files installed by a named add-on
  - `(#ddev-generated)` for add-on files that also carry a `#ddev-generated` marker
  - `(unexpected #ddev-generated)` for files with a `#ddev-generated` marker not recognized as a DDEV or add-on file
  - `(#ddev-silent-no-warn)` for files silenced with a `#ddev-silent-no-warn` marker

```
# Show only files that would warn on startup
ddev utility check-custom-config
# Show all files including add-on, unexpected #ddev-generated, and silenced files
ddev utility check-custom-config --all
```

### `utility check-db-match`

Verify that the database in the db server matches the configured [type and version](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/index.md>).

Example:

```
# Check whether project’s running database matches configuration
ddev utility check-db-match
```

### `utility compose-config`

Prints the current project’s docker-compose configuration.

Example:

```
# Print docker-compose config for the current project
ddev utility compose-config

# Print docker-compose config for `my-project`
ddev utility compose-config my-project
```

### `utility configyaml`

Prints the project [`config.*.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>) usage.

**Arguments:** `[project_name]`

**Flags:**

- `--full-yaml`: Output complete processed YAML configuration instead of individual fields
- `--omit-keys=<keys>`: Comma-separated list of keys to omit from output (e.g., `web_environment`)

**Examples:**

```
# Print config for the current project
ddev utility configyaml

# Print config specifically for `my-project`
ddev utility configyaml my-project

# Print complete YAML configuration
ddev utility configyaml --full-yaml

# Hide sensitive environment variables
ddev utility configyaml --omit-keys=web_environment

# Combine flags: full YAML output without sensitive keys
ddev utility configyaml --full-yaml --omit-keys=web_environment
```

### `utility delete-volume`

Delete a Docker volume belonging to the current project, identified by either its short docker-compose name (e.g. `solr`) or its full Docker volume name (e.g. `ddev-myproject_solr`). If no name is given, pick one from an interactive list of the project’s volumes. If the project is running, you’ll be asked to stop it first, since a container-mounted volume can’t be removed. Shared volumes used by every project, like `ddev-global-cache`, can’t be deleted with this command.

Flags:

- `--yes`, `-y`: Skip confirmation prompts.

Example:

```
# Choose a volume to delete from an interactive list
ddev utility delete-volume

# Delete the "solr" volume for the current project, prompting for confirmation
ddev utility delete-volume solr

# Delete by full Docker volume name, skipping confirmation
ddev utility delete-volume ddev-myproject_solr --yes
```

### `utility diagnose`

Run quick diagnostics on your DDEV installation and current project. This command provides concise, actionable output for common troubleshooting scenarios.

The command checks:

- Docker environment and connectivity
- Network configuration and DNS resolution
- HTTPS/mkcert setup
- Current project health (if in a project directory)

For comprehensive output suitable for issue reports, use [`ddev utility test`](<#utility-test>) instead.

**Environment variables:**

- `DDEV_DIAGNOSE_FULL=true`: Include test project creation in diagnostics (slower but more thorough)

**Examples:**

```
# Run diagnostics in a project directory
ddev utility diagnose

# Run with full diagnostics including test project creation
DDEV_DIAGNOSE_FULL=true ddev utility diagnose

# Run from anywhere (checks Docker and environment only)
ddev utility diagnose
```

### `utility dockercheck`

Diagnose DDEV Docker provider setup.

Example:

```
# Output contextual details for the Docker provider
ddev utility dockercheck
```

### `utility download-ddev`

Download the `ddev` and `ddev-hostname` binaries built by CI or a release, for testing a specific build without replacing your installed DDEV. It only downloads the binaries into a directory (`~/tmp/ddev-download-ddev/<version>` by default, so a download can’t accidentally end up on `$PATH` or as a stray file in a Git checkout, and each build stays separate from the ones downloaded before it) and prints how to use them in the current shell; it does not modify your installed DDEV.

Flags:

- `--pr <number>`: Download the build from a pull request number
- `--branch <name>`: Download the build from a branch name
- `--commit <sha>`: Download the build from a commit SHA, full or abbreviated
- `--tag <tag>`: Download a release tag, for example `v1.25.3`
- `--stable`: Download the latest stable release (default `false`)
- `--head`: Download the latest main build (default `false`)
- `--output <dir>`, `-o <dir>`: Output directory, used as given (default: `~/tmp/ddev-download-ddev/<version>`, where `<version>` is the build, for example `pr-8611`, `v1.25.3`, or `main`)
- `--os <os>`: OS override: `macos`, `linux`, or `windows` (default: current OS)
- `--arch <arch>`: Architecture override: `amd64` or `arm64` (default: current architecture)
- `--owner <owner>`: GitHub owner/org (default `ddev`; for PR builds this is the base repository, not a fork)
- `--repo <repo>`: GitHub repository (default `ddev`)

Note: Exactly one source flag (`--pr`, `--branch`, `--commit`, `--tag`, `--stable`, or `--head`) is required, and they are mutually exclusive.

Releases and `main` builds are signed; PR and other branch builds are not. No source needs a GitHub token, but a [GitHub token](<#add-on>) avoids the low anonymous rate limit and downloads CI builds from GitHub directly rather than through nightly.link. If the GitHub API lookup fails, `--pr` falls back to the build links posted on the pull request, and `--head` to nightly.link’s latest `main` build, which is sometimes out of date.

Examples:

```
# Download this PR's build for your current OS and architecture into ~/tmp/ddev-download-ddev/pr-8611
ddev utility download-ddev --pr 8611

# Download the latest main build into ~/tmp/head
ddev utility download-ddev --head --output ~/tmp/head

# Download a specific released version
ddev utility download-ddev --tag v1.25.3

# Download the latest stable release
ddev utility download-ddev --stable

# Cross-download a macOS arm64 build of a branch
ddev utility download-ddev --branch 20250101_feature --os macos --arch arm64 --output ~/tmp/ddev-macos-arm64
```

### `utility download-images`

Download the basic Docker images required by DDEV. This can be useful on a new machine to prevent `ddev start` or other commands having to download the various images.

Example:

```
# Download DDEV’s basic Docker images
ddev utility download-images
# Download DDEV’s Docker images for `my-project`
ddev utility download-images my-project
# Download DDEV’s Docker images for all projects
ddev utility download-images --all
```

### `utility fix-commands`

Refreshes [custom command](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/index.md>) definitions without running [`ddev start`](<#start>).

Example:

```
# Refresh the current project’s custom commands
ddev utility fix-commands
```

### `utility get-volume-db-version`

Get the database type and version found in the `ddev-dbserver` database volume, which may not be the same as the configured database [type and version](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/index.md>).

Example:

```
# Print the database volume's engine and version
ddev utility get-volume-db-version
```

### `utility gob-decode`

Decode and display the contents of Go gob-encoded binary files used by DDEV, such as `.remote-config` files (remote configuration cache), `.amplitude.cache` files (analytics event cache), `.sponsorship-data` files (contributor sponsorship information), and `.addon-data` files (add-on registry cache).

The decoder automatically detects the file type and uses the appropriate structure. The output is displayed as formatted JSON for readability.

*(Hidden - show hidden utility commands with `ddev utility --show-hidden`)*

Example:

```
# Decode a remote config file
ddev utility gob-decode $HOME/.ddev/.remote-config

# Decode a sponsorship data file
ddev utility gob-decode $HOME/.ddev/.sponsorship-data

# Decode an add-on registry cache file
ddev utility gob-decode $HOME/.ddev/.addon-data

# Decode an amplitude cache file
ddev utility gob-decode $HOME/.ddev/.amplitude.cache

# Decode any gob file with path expansion
ddev utility gob-decode ~/path/to/file.gob
```

### `utility hyperlink`

Print a URL, or the URLs in piped text, as terminal hyperlinks when supported. Useful in [custom host commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/index.md>).

*(Hidden - show hidden utility commands with `ddev utility --show-hidden`)*

Example:

```
# Print a URL as a link
ddev utility hyperlink https://docs.ddev.com

# Link the URLs in piped text
echo "See https://docs.ddev.com" | ddev utility hyperlink
```

### `utility match-constraint`

Check if the currently installed ddev matches the specified [version constraint](<https://github.com/Masterminds/semver#checking-version-constraints>).

Example:

```
if ddev utility match-constraint "< 1.25" >/dev/null 2>&1; then
  # do something for ddev versions below 1.25
  ...
else
  # do something for ddev versions 1.25+
  ...
fi
```

> [!TIP]

You can also configure a [ddev version constraint per project](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#ddev_version_constraint>).

### `utility message-conditions`

Show message conditions of this version of DDEV.

*(Hidden - show hidden utility commands with `ddev utility --show-hidden`)*

Example:

```
# Show message conditions for the current DDEV version
ddev utility message-conditions
```

### `utility migrate-database`

Migrate a MySQL or MariaDB database to a different `dbtype:dbversion`. Works only with MySQL and MariaDB, not with PostgreSQL. It will export your database, create a snapshot, destroy your current database, and import into the new database type. It only migrates the ‘db’ database. It will update the database version in your project’s `config.yaml` file.

Example:

```
# Migrate the current project's database to MariaDB 10.7
ddev utility migrate-database mariadb:10.7
```

### `utility mutagen`

Allows access to any [Mutagen command](<https://mutagen.io/documentation/introduction>).

Example:

```
# Run Mutagen's `sync list` command
ddev utility mutagen sync list
```

### `utility mutagen-diagnose`

Diagnose Mutagen sync configuration and performance issues. This command analyzes your Mutagen setup and provides actionable recommendations for improving sync performance.

The command checks:

- Volume sizes and disk usage (warns if \>5GB, critical if \>10GB)
- Upload directories configuration
- Sync session status and problems
- Large files being synced that could impact performance (\>50MB)
- Ignore pattern configuration

**Flags:**

- `--all`, `-a`: Show all Mutagen volumes system-wide instead of just the current project

**Examples:**

```
# Diagnose the current project's Mutagen configuration
ddev utility mutagen-diagnose

# Show all Mutagen volumes across all projects
ddev utility mutagen-diagnose --all
```

See the [Mutagen troubleshooting documentation](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen-troubleshooting>) for more details.

### `utility port-diagnose`

Identify processes occupying ports needed by DDEV. When run inside a project directory, checks that project’s configured ports (HTTP, HTTPS, Mailpit, XHGui). When run outside a project, checks the default ports 80 and 443. On WSL2, both the Linux and Windows sides are checked.

Some port conflicts are only visible with elevated privileges (e.g. `docker-proxy` under rootful Docker CE). The tool will ask for permission before running any `sudo` command, showing the exact command it intends to run. Use `--allow-sudo` to pre-approve this without an interactive prompt.

Flags:

- `--allow-sudo`: Permit `sudo` use for elevated port detection without an interactive prompt.

Example:

```
# Check ports for the current project (or defaults 80/443 outside a project)
ddev utility port-diagnose
# Allow sudo for elevated detection without interactive prompt
ddev utility port-diagnose --allow-sudo
```

See also: [Troubleshooting port conflicts](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>).

### `utility rebuild`

*Alias: `utility refresh`.*

Rebuilds the project’s Docker cache with verbose output and restarts the project or the specified services.

Services that have a container get a new one with the rebuilt image. Rebuilding `web` restarts the whole project, with the optional services that were started.

Flags:

- `--all`, `-a`: Rebuild all services and restart the project.
- `--cache`: Keep Docker cache.
- `--service`, `-s`: Rebuild these comma-separated services and restart them. (default `web`)

Example:

```
# Rebuild the current project's web service without cache
ddev utility rebuild

# Rebuild the current project's web service with cache
ddev utility rebuild --cache

# Rebuild the current project's db service without cache
ddev utility rebuild --service db

# Rebuild the current project's solr and redis services without cache
ddev utility rebuild -s solr,redis

# Rebuild the current project's all services without cache
ddev utility rebuild --all
```

### `utility remote-data`

Download and display remote configuration and sponsorship data used by DDEV from GitHub repositories.

The downloaded content is displayed as formatted JSON to stdout. Optionally updates the local cached storage file (enabled by default).

*(Hidden - show hidden utility commands with `ddev utility --show-hidden`)*

Flags:

- `--type`, `-t`: Type of data to download: `remote-config` (default), `sponsorship-data`, or `addon-data`.
- `--update-storage`: Update local cached storage file (default `true`).

Examples:

```
# Download remote config (default type)
ddev utility remote-data

# Download sponsorship data without updating local storage
ddev utility remote-data --type=sponsorship-data --update-storage=false

# Download add-on registry data
ddev utility remote-data --type=addon-data
```

### `utility test`

Run diagnostics using the embedded [test script](<https://github.com/ddev/ddev/blob/main/cmd/ddev/cmd/scripts/test_ddev.sh>).

Example:

```
# Run DDEV's diagnostic suite
ddev utility test
```

### `utility testcleanup`

Removes all diagnostic projects created with `ddev utility test`.

Example:

```
# Remove all DDEV's diagnostic projects
ddev utility testcleanup
```

### `utility tls-diagnose`

Diagnose TLS/HTTPS certificate trust issues. Checks mkcert installation and `CAROOT` configuration, OS trust store installation, certificate file validity, and live HTTPS connectivity when a project is running.

On WSL2, also checks WSL2-specific CA sharing requirements: whether `$CAROOT` points to the Windows filesystem, whether `CAROOT` is in `$WSLENV`, whether the Windows certificate store contains the mkcert CA, and whether Windows-side and WSL2-side CA fingerprints match.

Example:

```
# Run from any directory for mkcert, trust store, and cert file checks
ddev utility tls-diagnose

# Run from a running project directory to also check live HTTPS connectivity
cd my-project && ddev utility tls-diagnose
```

See also: [Browser Shows Certificate Error for DDEV Sites](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#browser-certificate-error>).

### `utility xdebug-diagnose`

Diagnose Xdebug configuration (experimental)

Example:

```
# Run quick check
ddev utility xdebug-diagnose

# Run more complete interactive check
ddev utility xdebug-diagnose --interactive
```

## `version`

Print DDEV and component versions.

Example:

```
# Print DDEV and platform version details
ddev version
```

> [!TIP]
>
> `ddev --version` is a more concise command that only outputs the DDEV version without component versions.

## `wp`

Run the [WP-CLI `wp` command](<https://wp-cli.org/>); available only in projects of type `wordpress` and `wp-bedrock`.

```
# Install WordPress site using `wp core install`
ddev wp core install --url='$DDEV_PRIMARY_URL' --title='New-WordPress' --admin_user=admin --admin_email=admin@example.com --prompt=admin_password
```

> [!TIP]
>
> See [WordPress Specifics](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/#wordpress-specifics>) for more information.

## `xdebug`

Enable or disable [Xdebug](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>) (global shell web container command).

- The `on` argument is equivalent to `enable` and `true`.
- The `off` argument is equivalent to `disable` and `false`.

```
# Display whether Xdebug is running
ddev xdebug status

# Display detailed Xdebug diagnostic information
ddev xdebug info

# Turn Xdebug on
ddev xdebug

# Turn Xdebug on
ddev xdebug on

# Turn Xdebug off
ddev xdebug off

# Toggle Xdebug on and off
ddev xdebug toggle
```

The `ddev xdebug info` command displays detailed diagnostic information from Xdebug’s `xdebug_info()` function, including enabled features, optional features, diagnostic log, step debugging status, and all Xdebug configuration directives. This may be useful for troubleshooting Xdebug configuration issues. `xdebug info` is only supported on Xdebug 3+.

## `xhgui`

Enable or disable [XHGui](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xhprof-profiling/index.md>)

`ddev xhgui` only is useful if [xhprof\_mode](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xhprof_mode>) is set to `xhgui`.

- The `on` argument is equivalent to `enable` and `true`.
- The `off` argument is equivalent to `disable` and `false`.

```
# Display whether XHGui is enabled and running
ddev xhgui status

# Turn XHGui on
ddev xhgui

# Launch the XHGui UI
ddev xhgui launch

# Turn XHGui on
ddev xhgui on

# Turn XHGui off
ddev xhgui off
```

## `xhprof`

Enable or disable [Xhprof](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xhprof-profiling/index.md>) (global shell web container command).

- The `on` argument is equivalent to `enable` and `true`.
- The `off` argument is equivalent to `disable` and `false`.

```
# Display whether Xhprof is running
ddev xhprof status

# Turn Xhprof on
ddev xhprof

# Turn Xhprof on
ddev xhprof on

# Turn Xhprof off
ddev xhprof off
```

## `yarn`

Run [`yarn` commands](<https://yarnpkg.com/cli>) inside the web container in the root of the project (global shell host container command).

> [!TIP]
>
> Use `--cwd` for another directory, or you can change directories to the desired directory and `ddev yarn` will act on the same relative directory inside the container.

> [!TIP]
>
> If you want to define your Yarn version on a per project basis, set `corepack_enable: true` in `.ddev/config.yaml` or `ddev config --corepack-enable`

Example:

```
# Use Yarn to install JavaScript packages
ddev yarn install

# Use Yarn to add the Lerna package
ddev yarn add lerna

# Use yarn in a relative directory
cd web/core && ddev yarn add lerna

# Use Yarn to add the Lerna package from the `web/core` directory
ddev yarn --cwd web/core add lerna

# Use latest yarn or specified yarn
ddev config --corepack-enable && ddev restart
ddev yarn set version stable
ddev yarn --version
```

# Database Management

DDEV provides lots of flexibility for managing your databases between your local, staging and production environments. You may commonly use the [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) and [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>) commands, but there are plenty of other adaptable ways to work with your databases.

If your project does *not* require a database, you can exclude it with the the [`omit_containers` configuration option](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#omit_containers>).

> [!TIP]
>
> You can run `ddev [command] --help` for more info on many of the topics below.

## Database Imports

Import a database with one command, from one of the following file formats:  
**`.sql`, `.sql.gz`, `.sql.bz2`, `.sql.xz`, `.sql.zst`, `.mysql`, `.mysql.gz`, `.tar`, `.tar.gz`, `.tar.zst`, and `.zip`**.

Here’s an example of a database import using DDEV:

```
ddev import-db --file=dumpfile.sql.gz
```

You can also:

- Use [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>) or `ddev psql` or the `mysql` and `psql` commands inside the `web` and `db` containers.
- Use a [database client](<#database-clients>) or [database GUI](<#database-guis>) to import and browse data.

## Database Backends and Defaults

You can use a [variety of different database types](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/#database-server-types>), including MariaDB (5.5–10.8, 11.4, 11.8, 12.3), MySQL (5.5–8.0, 8.4, 9.7), and PostgreSQL (9–18). If you want to *change* database type, you need to export your database, run [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) to remove the project (and its existing database), change to a new database type, run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) again, and [import your data](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>).

(For very old database types see [Using DDEV to spin up a legacy PHP application](<https://ddev.com/blog/legacy-projects-with-unsupported-php-and-mysql-using-ddev/>).)

DDEV creates a default database named `db` and default permissions for the `db` user with password `db`, and it’s on the (inside Docker) hostname `db`.

## Extra Databases

You can easily create and populate additional databases. For example, `ddev import-db --database=backend --file=backend.sql.gz` will create the database named `backend` with permissions for that same `db` user and import from the `backend.sql.gz` dumpfile.

You can export in the same way: `ddev export-db -f mysite.sql.gz` will export your default database (`db`). The compression type comes from the file extension (`.gz`, `.zst`, `.xz`, `.bz2`, or `.sql` for none), or set it with `--compression`. `ddev export-db --database=backend -f backend-export.sql.gz` will dump the database named `backend`.

## Snapshots

Snapshots let you easily save the entire status of all of your databases, which can be great when you’re working incrementally on migrations or updates and want to save state so you can start right back where you were.

Snapshots can be named for easier reference later on. For example, [`ddev snapshot --name=two-dbs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) would make a snapshot named `two-dbs` in the `.ddev/db_snapshots` directory. It includes the entire state of the db server, so in the case of our two databases above, both databases and the system level `mysql` or `postgres` database will all be snapshotted. Then if you want to delete everything with `ddev delete -O` (omitting the snapshot since we have one already), and then [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) again, we can `ddev snapshot restore two-dbs` and we’ll be right back where we were.

Use the [`ddev snapshot restore`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot-restore>) command to interactively choose among snapshots, or append `--latest` to restore the most recent snapshot: `ddev snapshot restore --latest`. It also accepts the path to a snapshot file outside the project: `ddev snapshot restore ~/tmp/mysnapshot-mariadb_11.8.zst`.

Snapshots are stored as compressed (zstd, or gzip on very old database versions) files in the project’s `.ddev/db_snapshots` directory, and any or all snapshots can be removed with the `ddev snapshot --cleanup` command or by manually deleting the files when you want to save disk space or have no further use for them.

### Sharing Snapshots Between Git Worktrees

If a project is a [Git worktree](<https://git-scm.com/docs/git-worktree>), `ddev snapshot restore` also offers snapshots belonging to the same project checked out in the repository’s other worktrees, so a snapshot taken in one working copy doesn’t have to be manually copied to restore it in another. This works whether you pick interactively, restore by name, or use `--latest`, and `ddev snapshot --list` shows the other worktrees’ snapshots too, each labeled with the worktree it came from:

```
# In ~/repo/web
ddev snapshot --name=before-migration

# In ~/repo-feature-branch/web, a worktree of the same repository
ddev snapshot restore
# 'before-migration' from ~/repo/web is offered alongside this project's own snapshots

ddev snapshot restore before-migration
# also works directly by name, without the interactive picker
```

Only worktrees of the same repository are considered — a separate clone at the same relative path is not, even if it happens to have the same project name. If more than one sibling worktree has a snapshot with the same name, the most recently created one is used, without asking which. This is a convenience on top of the path-based restore above: `ddev snapshot restore <path>` and `ddev start --seed-snapshot=<path>` already work with a snapshot from anywhere on disk, worktree or not.

### Uncompressed Snapshots

`ddev snapshot`, `ddev snapshot restore`, and the reserved `seed` snapshot all compress the database backup by default, which is the right trade-off for almost everyone. Decompression still costs real time, though — routinely 30-40% of a restore or first `ddev start`, and it competes for the same CPU cores the database restore itself needs right after. `--uncompressed` skips it:

```
ddev snapshot --uncompressed
```

This is an unusual, deliberate trade-off, not a general recommendation: an uncompressed snapshot can be roughly as large as the database’s uncompressed datadir — many times bigger than the same snapshot compressed with zstd. It’s worth it mainly when disk space is cheap relative to CPU time, for example a low-core-count host, or a seed that’s read straight off fast local disk and never crosses a network (so compression buys nothing on the transfer side either). `ddev snapshot --list` shows each snapshot’s compression (`zstd`, `gzip`, or `none`) so you can tell which kind you’re looking at. Restoring an uncompressed snapshot with `ddev snapshot restore` needs no extra flag — the file’s extension (`.mbstream`/`.xbstream` instead of `.zst`/`.gz`) already tells DDEV there’s nothing to decompress. Not available for PostgreSQL projects.

The reserved `seed` snapshot honors the same flag, and a `dbimage` built with a baked-in seed (see [Seeding a Custom Starter Database](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#seeding-a-custom-starter-database-in-dbimage>)) can use an uncompressed seed the same way.

### Seeding a Fresh Database from a Snapshot

The first time a project’s database volume is created — a brand-new project, or after `ddev delete` and [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) — DDEV can restore a snapshot into it instead of using its normal empty starter database. This is a direct restore of the database files, much quicker than importing a SQL dump on every fresh start.

`seed` is a reserved snapshot name used for this. If a snapshot named `seed` exists in `.ddev/db_snapshots`, it’s used automatically, with nothing to remember at start time:

```
ddev snapshot --name=seed
ddev delete -Oy
ddev start
```

To use a different snapshot for one start, name it with `--seed-snapshot`, which takes either a snapshot name from `.ddev/db_snapshots` or the path to a snapshot file elsewhere on disk:

```
ddev start --seed-snapshot=large-dataset
ddev start --seed-snapshot=~/datasets/production-mariadb_11.8.zst
```

`--seed-snapshot` applies to that command only and is never written to `config.yaml`. It only seeds a brand-new database volume; if the project already has a database, DDEV says so rather than silently ignoring the flag. Use [`ddev start --reset-database`](<#starting-over-with-a-new-database>) to throw the existing database away first, or [`ddev snapshot restore`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot-restore>) to restore over it.

A snapshot can only seed the database type and version it was made from, which is why the standard `-<type>_<version>.{zst,gz}` suffix `ddev snapshot` gives it has to stay on the filename.

You can choose to commit the resulting `seed-*` file in `.ddev/db_snapshots` to your repository if you want teammates and CI to get the same starting dataset on their first `ddev start`, but it may be large and you may want to use another distribution technique.

A `seed` snapshot is listed as [custom configuration](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/index.md>), so `ddev start` and [`ddev utility check-custom-config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-check-custom-config>) both show it. When `ddev start` actually seeds a fresh database volume, it says so, naming the snapshot and its size and warning that a large one may take a while:

```
Initializing new database volume from the 'seed' snapshot /path/to/project/.ddev/db_snapshots/seed-mariadb_11.8.zst (2.2 GiB)...
A large database may take a while; the 600s timeout is set by default_container_timeout.
```

### Starting Over with a New Database

`ddev start --reset-database` removes the project’s database and starts over with a new one. It snapshots the existing database first, unless you add `--omit-snapshot`/`-O`, and asks for confirmation unless you add `--skip-confirmation`/`-y`. The same flags work on [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).

Use it when you want a clean database, or when you’ve changed `database:` in `config.yaml` and `ddev start` refuses because the existing database was created by a different database server. The snapshot it takes is made with the database version that’s actually in the volume, so you can still restore it after you put the configuration back.

```
ddev config --database=postgres:17
ddev start --reset-database
```

To combine it with a seed, so the new database starts out with a dataset of your choosing rather than empty:

```
ddev start --reset-database --seed-snapshot=large-dataset
```

## Database Clients

The `ddev mysql` and `ddev psql` commands give you direct access to the `mysql` and `psql` clients in the database container, which can be useful for quickly running commands while you work. You might run `ddev mysql` to use interactive commands like `DROP DATABASE backend;` or `SHOW TABLES;`, or do things like `echo "SHOW TABLES;" | ddev mysql` or `ddev mysql -udb -pdb` to run with `db` user privileges.

The `web` and `db` containers are each ready with MySQL/PostgreSQL clients, so you can [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) or `ddev ssh -s db` and use `mysql` or `psql`.

## `mysqldump` and `pg_dump`

The `web` and `db` containers come with `mysqldump`. You could run [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) to enter the web container, for example, then `mkdir /var/www/html/.tarballs` and run `mysqldump db >/var/www/html/.tarballs/db.sql` or run `mysqldump db | gzip >/var/www/html/.tarballs/db.sql.gz` to create database dumps. Because `/var/www/html` is mounted into the container from your project root, the `.tarballs` directory will also show up in the root of the project on your host machine.

The PostgreSQL database container includes normal `pg` commands like `pg_dump`.

## Database GUIs

If you’d like to use a GUI database client, you’ll need the right connection details and there may even be a command to launch it for you:

- phpMyAdmin, formerly built into DDEV core, can be installed by running `ddev add-on get ddev/ddev-phpmyadmin`.
- Adminer can be installed with `ddev add-on get ddev/ddev-adminer`
- The [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) command displays the `Host:` details you’ll need to connect to the `db` container externally, for example if you’re using an on-host database browser like SequelAce.
- macOS users can use [`ddev sequelace`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#sequelace>) to launch the free [Sequel Ace](<https://sequel-ace.com/>) database browser, [`ddev tableplus`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tableplus>) to launch [TablePlus](<https://tableplus.com>), [`ddev tablepro`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tablepro>) to launch [TablePro](<https://tablepro.app>), [`ddev querious`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#querious>) to launch [Querious](<https://www.araelium.com/querious>), [`ddev dbeaver`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dbeaver>) to launch [DBeaver](<https://dbeaver.io/>). (Each must be installed for the command to exist.)
- WSL2 and Linux users can use [`ddev dbeaver`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dbeaver>) to launch [DBeaver](<https://dbeaver.io/>). (Must be installed for the command to exist.)
- PhpStorm (and all JetBrains tools) have a nice database browser. (If you use the [DDEV Integration plugin](<https://plugins.jetbrains.com/plugin/18813-ddev-integration>) this is all done for you.)

  - Choose a static [`host_db_port`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#host_db_port>) setting for your project. For example `host_db_port: 59002` (each project’s database port should be different if you’re running more than one project at a time). Use [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) for it to take effect.
  - Use the “database” tool to create a source from “localhost”, with the proper type `mysql` or `postgresql` and the port you chose, username `db` + password `db`.
  - Explore away!
- VS Code or any of its forks (Cursor, Windsurf, etc.) has [DevDb](<https://marketplace.visualstudio.com/items?itemName=damms005.devdb>), an extension that lets you access your database directly inside the editor.
- There’s a sample custom command that will run the free MySQL Workbench on macOS, Windows or Linux. To use it, run:

  - `cp $HOME/.ddev/commands/host/mysqlworkbench.example $HOME/.ddev/commands/host/mysqlworkbench`
  - `ddev mysqlworkbench`

## Database Query Examples

You can query, update, or alter databases in DDEV like you would do on a regular server, using `ddev mysql`, `ddev mariadb`, or `ddev psql` or using those command-line tools inside the web or DB containers. Some examples are given below.

- Create a new empty database named `newdatabase`:

  ```
  ddev mysql -e 'CREATE DATABASE newdatabase; GRANT ALL ON newdatabase.* TO "db"@"%";'
  ```
- Show tables whose name begins with `node` :

  ```
  ddev mysql -e 'SHOW TABLES LIKE "node%";'
  ```
- Use `ddev mysql` or `ddev mariadb` and issue interactive queries:

  ```
  ddev mariadb

  Reading table information for completion of table and column names
  You can turn off this feature to get a quicker startup with -A

  Welcome to the MariaDB monitor.  Commands end with ; or \g.
  Your MariaDB connection id is 28
  Server version: 10.11.10-MariaDB-ubu2204-log mariadb.org binary distribution

  Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

  Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

  MariaDB [db]> SELECT * FROM node WHERE type="article";
  +-----+------+---------+--------------------------------------+----------+
  | nid | vid  | type    | uuid                                 | langcode |
  +-----+------+---------+--------------------------------------+----------+
  |  11 |   56 | article | 8af917ea-b150-4006-aeb9-877b53ebf289 | en       |
  |  12 |   54 | article | 27a53763-9fd8-4813-853b-b476f0a73849 | en       |
  +-----+------+---------+--------------------------------------+----------+
  2 rows in set (0.007 sec) 
  ```

# Built-in Developer Tools

Run [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) to see the project information and services available for your project and how to access them.

## Command-line Tools in the Containers

Hundreds of useful developer tools are included inside the containers and can be used via [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) or [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>). Some of those include:

- MySQL client (`mysql`) - Command-line interface for interacting with MySQL/MariaDB.
- PostgreSQL client (`psql`) - Command-line tool for PostgreSQL.
- [PHIVE](<https://github.com/phar-io/phive>) - Command-line tool for “PHAR Installation and Verification Environment”.
- `npm` and `yarn` (these also have `ddev` shortcuts like [`ddev npm`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#npm>) and [`ddev yarn`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#yarn>)).
- `node` (for front-end build tools like [Vite](<https://ddev.github.io/ddev/en/stable/users/usage/vite/index.md>), see the [Vite Integration](<https://ddev.github.io/ddev/en/stable/users/usage/vite/index.md>) documentation)
- `sqlite3`

DDEV also installs some tools only for the project types that need them, such as [Drush](<http://www.drush.org>), [WP-CLI](<http://wp-cli.org/>), [n98-magerun](<https://github.com/netz98/n98-magerun>), and [n98-magerun2](<https://github.com/netz98/n98-magerun2>). See [Project-Specific Utilities](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#project-specific-utilities>) for the full list.

These tools can be accessed for single commands using [`ddev exec <command>`](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#executing-commands-in-containers>) or [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#ssh-into-containers>) for an interactive `bash` or `sh` session.

You can also add tools that are not provided by default using [`webimage_extra_packages` or a custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/index.md>).

## DDEV and Composer

DDEV provides a built-in command to simplify use of PHP’s dependency manager, [Composer](<https://getcomposer.org/>), without requiring it to be installed on the host machine. Generally, executing any Composer command through DDEV is as simple as prepending the command with `ddev`. DDEV will execute the command at the project root in the web container, passing (almost) all arguments and flags to Composer. To execute Composer in other directories within the container, use `ddev ssh` or `ddev exec -d <dir>`. For example:

- `ddev composer help` runs Composer’s help command to learn more about what’s available.
- `ddev composer require <package>` tells Composer to require a specific PHP package for the current project.

Additionally, Composer can be used to initialize new projects with `ddev composer create-project`. This command supports limited argument and flag options, and will install a new project to the composer root (normally `/var/www/html`). The package and version arguments are required:

`ddev composer create-project [options] [--] [<package> [<directory> [<version>]]]`

For example:

`ddev composer create-project --no-dev typo3/cms-base-distribution . "^9"`

When using `ddev composer create-project` your project should be essentially empty or the command will refuse to run, to avoid loss of your files.

`ddev composer create-project` does these things in this order:

1. `composer create-project --no-plugins --no-scripts --no-install` clones a bare Composer package without any additional actions.
2. `composer run-script post-root-package-install` runs if `--no-scripts` is not given as a flag to `ddev composer create-project`.
3. `composer install` runs if `--no-install` is not given as a flag to `ddev composer create-project`.
4. `composer run-script post-create-project-cmd` runs if `--no-scripts` is not given as a flag to `ddev composer create-project`.

All flags that you provide to `ddev composer create-project` are checked for validity. All invalid flags will be ignored. If they are valid for `composer create-project`, they will be also passed to `composer run-script` and `composer install`, but only if these commands support these flags.

To execute a fully-featured `composer create-project` command, you can execute the command from within the container after executing [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), or pass the full command to [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), like so:

`ddev exec composer create-project ...`

**composer.json Location**: It’s most common for `composer.json` to be in the project root, but you can specify an alternate Composer root using DDEV’s `composer_root` option in `.ddev/config.yaml`, or `ddev config --composer-root <dir>`. The `composer_root` value is the *relative* path from the project root to the directory containing `composer.json`. If yours is at `docroot/composer.json`, for example, the `composer_root` value should be `docroot`.

> [!TIP]
>
> **How to debug Composer itself?**
>
> To use Xdebug with Composer, [see instructions](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/#composer>).

### Composer Limitations

> [!WARNING]
>
> **Container changes do not persist**
>
> Changes made outside your project directory are lost when the container restarts. Some Composer commands make such changes, see below. For other cases, see [Persisting Changes Across Restarts](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-changes-across-restarts>).

#### Composer Global Packages Do Not Persist

If you run `ddev composer global require` (or `composer global require` inside the web container), global packages will be installed at the home directory within the container (`$HOME/.composer`) and will disappear when the container restarts.

To keep them, [store `~/.composer` in `ddev-global-cache`](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-home-subdirectories-in-ddev-global-cache>), or install the tools with a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#examples>).

#### Composer Self-Update Changes Do Not Persist

Running `ddev composer self-update` (or `composer self-update` inside the web container) will update Composer within the container, but the change will be lost when the container restarts. Don’t try to keep `/usr/local/bin/composer` across restarts, because then `composer_version` and DDEV upgrades can’t update it.

The Composer version is cached after the first image build and automatically updates only when DDEV is upgraded.

If you need to update Composer:

1. Check the [`composer_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#composer_version>) setting in `.ddev/config.yaml` and set it to your desired version:

   - `composer_version: ""` (empty) - equivalent to `composer self-update --stable`
   - `composer_version: "2"` (v2) - equivalent to `composer self-update --2`
   - `composer_version: "2.2"` (v2.2 LTS) - equivalent to `composer self-update --2.2`
   - `composer_version: "2.9.3"` (specific) - equivalent to `composer self-update 2.9.3`. This is the most consistent option for teams, as it ensures all members use the exact same version regardless of when they first build the image, avoiding inconsistencies in dependency resolution.
2. [Restart](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) to install it:

   ```
   ddev restart
   ```

   To get a newer release without changing the value, for example with `""` or `"2"`, restart with `--no-cache` or [rebuild](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-rebuild>). This rebuilds the whole image and takes longer:

   ```
   ddev restart --no-cache
   # or
   ddev utility rebuild
   ```

### Composer from `vendor/bin/composer`

If your `composer.json` specifies `composer/composer`, the version in `vendor/bin/composer` can be run with:

```
ddev exec vendor/bin/composer --version
```

If a custom [`composer_root`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#composer_root>) is set, use:

```
ddev exec '$DDEV_COMPOSER_ROOT/vendor/bin/composer --version'
```

### Windows OS (Traditional Windows) and `ddev composer`

DDEV attempts to help with Composer and some configurations of Docker Desktop for Windows that introduce complex filesystem workarounds.

Use [`ddev composer`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>) (Composer inside the container) instead of using `composer` on the host side, because it uses the right version of PHP and all its extensions for your project:

- On some older configurations of Docker Desktop for Windows, symlinks are created in the container as “simulated symlinks”, or XSym files. These special text files behave as symlinks inside the container (on CIFS filesystem), but appear as simple text files on the Windows host. (On the CIFS filesystem used by Docker for Windows, inside the container, there is no capability to create real symlinks even though Windows now has this capability.)
- DDEV attempts to clean up for this situation. Since Windows 10/11+ (in developer mode) can create real symlinks, DDEV scans your repository after a `ddev composer` command and attempts to convert XSym files into real symlinks. On older versions of Windows 10, it can only do this if your Windows 10 workstation is set to “Developer Mode”.
- To enable developer mode on Windows 10/11+, search for “developer” in settings: ![Finding developer mode](<https://ddev.github.io/ddev/en/stable/images/developer-mode-1.png>)

  ![Setting developer mode](<https://ddev.github.io/ddev/en/stable/images/developer-mode-2.png>)

## Email Capture and Review (Mailpit)

[Mailpit](<https://github.com/axllent/mailpit>) is a mail catcher that’s configured to capture and display emails sent by PHP in the development environment.

After your project is started, access the Mailpit web interface at `https://mysite.ddev.site:8026`, or run [`ddev mailpit`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mailpit>) to launch it in your default browser.

Mailpit will **not** intercept emails if your application is configured to use SMTP or a third-party ESP integration.

For Drupal 9+, `settings.ddev.php` automatically overrides [Symfony Mailer](<https://www.drupal.org/project/symfony_mailer>) and [Symfony Mailer Lite](<https://www.drupal.org/project/symfony_mailer_lite>) transport configurations to use Mailpit; for other SMTP modules (like [SMTP](<https://www.drupal.org/project/smtp>)), update your application’s SMTP server configuration to use `localhost` and Mailpit’s port `1025`.

For Laravel projects, Mailpit will capture Swift messages via SMTP. Update your `.env` to use Mailpit with the following settings:

```
MAIL_MAILER=smtp
MAIL_HOST=localhost
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null
```

> [!NOTE]
>
> **Mailpit auto-tagging behavior**
>
> Mailpit automatically extracts [tags](<https://mailpit.axllent.org/docs/usage/tagging/#disable-auto-tagging>) from email addresses using *plus addressing*. For example, an email sent to `address+1@example.com` will be tagged with `1` (the part after `+`). This can be useful for filtering, but may be unexpected if you’re not aware of it.
>
> If this behavior is distracting, you can disable it by setting the following [environment variable](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>):
>
> ```
> MP_TAGS_DISABLE=plus-addresses
> ```
>
> The easiest way is to set it globally for all DDEV projects:
>
> ```
> ddev config global --web-environment-add=MP_TAGS_DISABLE=plus-addresses
> ```

## Using Development Tools on the Host Machine

It’s possible in many cases to use development tools installed on your host machine on a project provisioned by DDEV. Tools that interact with files and require no database connection, such as Git or Composer, can be run from the host machine against the codebase for a DDEV project with no additional configuration necessary.

### Database Connections from the Host

If you need to connect to your project’s database from your workstation, run [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) to show the database connection information, like `Host: localhost:49156`.

Each project’s database port is unique, and randomly chosen from available ports on your system when you run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).

You can force this port to be the same on every [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) by setting [`host_db_port`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#host_db_port>) in the project’s `.ddev/config.yaml`. For example, `host_db_port: "49156"` or `ddev config --host-db-port=49156`. This value needs to be different on each running DDEV project, and unless it is set, the database port will change on every `ddev start`.

You can use this port with various tools that need a direct port, like `mysql` or `psql` clients, but it’s usually easiest to use [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>), `ddev psql`, `ddev sequelace`, [`ddev tableplus`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tableplus>), [`ddev tablepro`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#tablepro>), etc, which set everything up for you.

(If you use PhpStorm and its integrated database browser, use the [DDEV Integration Plugin](<https://plugins.jetbrains.com/plugin/18813-ddev-integration>) to manage all of this for you.)

## DDEV and Terminus

[Terminus](<https://docs.pantheon.io/terminus>) is a command-line tool providing advanced interaction with [Pantheon](<https://pantheon.io/>) services. `terminus` is available inside the project’s container, allowing users to get information from, or issue commands to their Pantheon-hosted sites. This is an especially helpful feature for Windows users since Terminus is only officially supported on Unix-based systems.

> [!TIP]
>
> **How to change Terminus version?**
>
> See [How to Downgrade Terminus in DDEV’s Web Container and Customize Other Bundled Tools](<https://ddev.com/blog/ddev-bundled-tools-using-custom-versions/>).

To use Terminus, you’ll first need to:

1. Use a machine token. (See [Pantheon provider discussion](<https://ddev.github.io/ddev/en/stable/users/providers/pantheon/index.md>).)
2. Run [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) to tunnel into your container.
3. Issue a command using the keyword `terminus`. For help using Terminus, try `terminus list` to get a list of possible commands.

Terminus also allows you to issue [Drush](<https://www.drush.org/>), [WP-CLI](<https://wp-cli.org/>), and [Composer](<https://getcomposer.org/>) commands to your Pantheon server. These are all usable from within the container as well, but will require authentication via either your Pantheon password or an SSH key. To use your host machine’s SSH key, you can use the `ddev auth ssh` command [described here](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#ssh-into-containers>).

# Opt-In Usage Information

When you start DDEV for the first time or install a new release, you’ll be asked whether to send usage and error information to DDEV’s developers.

> [!TIP]
>
> **See [DDEV Live Usage Statistics](<https://ddev.com/usage-stats/>)**

Regardless of your choice, you can change this at any time using one of these approaches:

- `ddev config global --instrumentation-opt-in=false` (or `=true`), which sets [`instrumentation_opt_in`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#instrumentation_opt_in>) in `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>))
- `export DDEV_NO_INSTRUMENTATION=true` to disable it regardless of the config file setting

Usage information is also never collected in automated workflows where `CI=true` is set in the environment.

If you choose to share diagnostics, it helps us tremendously in our effort to improve the tool. DDEV tracks three kinds of events: `Identify` (about your machine), `Command` (which command you ran), and `Project` (your project’s configuration). Here’s an example of what we might see:

```
// Sent once per machine, to identify the environment DDEV runs in.
client.Track(&analytics.Track{
  DeviceId:   "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  AppVersion: "v1.25.3",
  Platform:   "arm64",
  OSName:     "darwin",
  Language:   "en_US.UTF-8",
  ProductID:  "ddev cli",
  Event:      "Identify",
  Properties: map[string]interface{}{
    "DDEV Environment": "darwin",
    "Docker Platform":  "docker-desktop",
    "Docker Version":   "27.3.1",
    "Timezone":         "PST",
    // "User" is only sent if you've set `instrumentation_user` yourself
    "User": "jane@example.com",
    // "WSL Distro" is only sent when DDEV runs inside WSL2
    "WSL Distro": "Ubuntu",
  },
})

// Sent on every command run.
client.Track(&analytics.Track{
  DeviceId:   "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  AppVersion: "v1.25.3",
  Platform:   "arm64",
  OSName:     "darwin",
  Language:   "en_US.UTF-8",
  ProductID:  "ddev cli",
  Event:      "Command",
  Properties: map[string]interface{}{
    // Positional arguments are sent as-is for built-in commands.
    // For your own custom commands the command name is replaced
    // with "custom-command" and the arguments are dropped entirely.
    "Arguments":    []string{},
    "Called As":    "start",
    "Command Name": "start",
    "Command Path": "ddev start",
  },
})

// Sent when a project starts, describing its configuration.
client.Track(&analytics.Track{
  DeviceId:   "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
  AppVersion: "v1.25.3",
  Platform:   "arm64",
  OSName:     "darwin",
  Language:   "en_US.UTF-8",
  ProductID:  "ddev cli",
  Event:      "Project",
  Properties: map[string]interface{}{
    "ID":                          "fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
    "Performance Mode":            "mutagen",
    "PHP Version":                 "8.5",
    "Project Type":                "php",
    "Webserver Type":              "nginx-fpm",
    "XHProf Mode":                 "xhgui",
    "Add-ons":                     []string{"redis"},
    "Add-on Repositories":         []string{"ddev/ddev-redis"},
    "Bind All Interfaces":         false,
    "CI":                          false,
    "Containers":                  []string{"db", "redis", "web"},
    "Containers Omitted":          []string{},
    "Corepack Enable":             true,
    "Database Type":               "mariadb",
    "Database Version":            "11.8",
    "DB Image Extra Packages":     []string{"netcat"},
    "DDEV Version Constraint":     ">= 1.25.3",
    "Disable Settings Management": false,
    "Fail On Hook Fail":           false,
    "No Project Mount":            false,
    "Nodejs Version":              "24",
    "Router":                      "traefik",
    "Router Disabled":             false,
    "WebExtraDaemonsDetails":      []string{"{\"Name\":\"vite\",\"Command\":\"npm run dev\",\"Directory\":\"/var/www/html\"}"},
    "WebExtraDaemonsNames":        []string{"vite"},
    "WebExtraExposedPortsDetails": []string{"{\"Name\":\"vite\",\"WebContainerPort\":5173,\"HTTPPort\":5172,\"HTTPSPort\":5173}"},
    "WebExtraExposedPortsNames":   []string{"vite"},
    "Webimage Extra Packages":     []string{"php${DDEV_PHP_VERSION}-tidy"},
  },
})
```

If you have any issues or concerns with it, we’d like to know.

# FAQ

Frequently-asked questions organized into high-level functionality, investigating issues, daily usage, and connecting with our community.

## Features &amp; Requirements

### What operating systems will DDEV work with?

DDEV works nearly anywhere Docker will run, including macOS, WSL2, Windows 10/11 Pro/Enterprise and Home, and every Linux variant we’ve ever tried. It also runs in many Linux-like environments, like ChromeOS (in Linux machine). DDEV works the same on each of these platforms since the important work is done inside identical Docker containers. This means that a team using diverse environments can share everything without trouble.

### Does DDEV change or deploy my code?

You are responsible for your code and its deployment. DDEV does not alter any code or fix any bugs in it. DDEV *does* add DDEV-specific settings for some CMSes if the [settings management](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/index.md>) is enabled. These items are excluded by `.gitignore` so they won’t affect a deployed project, but in most cases they would do no harm if deployed, because they check to see if they’re running in DDEV context.

### Why do I have to type `ddev` in front of so many commands?

When you are using commands like `ddev composer`, `ddev drush`, `ddev npm`, or `ddev yarn`, you are telling DDEV to execute that very command inside the web container. That is where the exact tool for the exact environment required by your project lives. It’s possible to execute `composer install` without prepending `ddev` in your project folder, but often you won’t have the same PHP version on your host computer as your project is configured to use inside the container, or perhaps you’ll have a different version of `composer` even. This can lead into workarounds like having to use `composer --ignore-platform-reqs` or even introducing incompatibilities into your project. With tools like `ddev composer` you are able to run several projects at the same time, each with different configurations, but when you use the tool inside the container, you get the exact configuration for the project you’ve configured. You can run any tool inside the web container with `ddev exec`, but many commands like `ddev composer` have two-word shortcuts.

However, if you prefer not to use `ddev` in front of commands, you can `ddev ssh` and execute the commands inside the web container.

### Where is my database stored in my DDEV project?

The MariaDB, MySQL, or PostgreSQL database for your project lives in a Docker volume, which means it does not appear in your DDEV project’s filesystem, and is not checked in. This configuration is for performance and portability reasons, but it means that if you change Docker providers or do a factory reset on your Docker provider, you will lose databases. By default many Docker providers do not keep Docker volumes where they are backed up by normal backup solutions. Remember to keep backups using `ddev export-db` or `ddev snapshot`. See [How can I migrate from one Docker provider to another](<#how-can-i-migrate-from-one-docker-provider-to-another>).

### What Docker providers can I use?

We have automated testing and support for a staggering range of Docker providers.

| Docker Provider | Support Level |
| --- | --- |
| OrbStack (macOS) | officially tested and supported on macOS |
| Docker Desktop for Mac | officially tested and supported on Apple Silicon |
| Docker Desktop for Windows | officially tested and supported on WSL2 and traditional Windows |
| Colima (macOS) | officially tested and supported |
| Docker-ce (Linux/WSL2) | officially supported with automated tests on WSL2/Ubuntu. Recommended. |
| Rancher Desktop (macOS) | officially tested and supported on macOS |

#### Minimally Supported

The following environments do not have automated test coverage and are only minimally supported:

- Docker Desktop for Linux. Although Docker Desktop for Linux appears to work successfully in limited manual testing, we recommend the documented [docker-ce](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>) installation instead.
- Rancher Desktop for Windows works in limited manual testing, but does not have automated testing. This is the only open-source Docker provider for traditional Windows.

### How can I migrate from one Docker provider to another?

There are many Docker providers on DDEV’s supported platforms. For example, on macOS people use Docker Desktop and OrbStack along with Colima and Rancher Desktop. On Windows WSL2, people may use Docker Desktop or Docker CE inside WSL2. In all cases, if you want to switch between Docker providers, save your database and make sure the Docker providers don’t interfere with each other:

1. Save away your projects’ databases. You can run `ddev snapshot --all` to make snapshots of all *registered* projects (that show up in `ddev list`). If you prefer a different way of saving database dumps, that works too!
2. Stop the Docker provider you’re moving from. For example, exit Docker Desktop.
3. Start the Docker provider you’re moving to.
4. Start projects and restore their databases. For example, you could run `ddev snapshot restore --latest` to load a snapshot taken in step one.

### Do I need to install PHP, Composer, nginx, or Node.js/npm on my workstation?

No. Tools like PHP, Composer, nginx, and Node.js/npm live inside DDEV’s Docker containers, so you only need to [install Docker](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>) and [install DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>).

For most users we recommend that you do *not* install PHP or composer on your workstation, so you get in the habit of using `ddev composer`, which will use the configured composer and PHP versions for your project, which can be different for each project. See [DDEV and Composer](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#ddev-and-composer>).

### Do I lose data when I run `ddev poweroff`, `ddev stop`, or `ddev restart`?

No. Your code continues to live on your workstation, and your database is safely stored on a Docker volume—both unaffected by these commands.

### How can I connect to my database?

The answer depends on where you’re connecting *from*.

The [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) command includes database connection details in a row like this:

```
│ db         │ OK   │ InDocker: ddev-mysite-db:3306 │ mariadb:10.3       │
│            │      │ Host: localhost:63161         │ User/Pass: 'db/db' │
│            │      │                               │ or 'root/root'     │
```

Inside your project container, where the app itself is running, the database hostname is `db` (**not** `127.0.0.1`) and the port is the default for your database engine—`3306` for MySQL/MariaDB, `5432` for PostgreSQL.

Outside your project’s web container, for example a database GUI on your workstation, the hostname is `localhost` and the port is unique to that project. In the example above, it’s `63161`.

The username, password, and database are each `db` regardless of how you connect.

### Can I use additional databases with DDEV?

Yes, you can create additional databases and manually do whatever you need on them. They’re created automatically if you use `ddev import-db` with the `--database` option. In this example, `extradb.sql.gz` is extracted and imported to a newly-created database named `extradb`:

```
ddev import-db --database=extradb --file=.tarballs/extradb.sql.gz
```

You can use [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>) or `ddev psql` to execute queries, or use the MySQL/PostgreSQL clients within `ddev ssh` or `ddev ssh -s db`. See the [Database Management](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/index.md>) page.

### Can different projects communicate with each other?

Yes, this is commonly required for situations like Drupal migrations or server-side API calls between projects.

See [Inter-Project Communication](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/#inter-project-communication>) for detailed information about database and HTTP/S communication between projects.

### Can I run DDEV with other development environments at the same time?

Yes, as long as they’re configured to use different ports. It doesn’t matter whether your other environments use Docker or not, it should only be a matter of avoiding port conflicts.

It’s probably easiest, however, to shut down one before using the other.

For example, if you use Lando for one project, do a `lando poweroff` before using DDEV, and then run [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) before using Lando again. If you run nginx or Apache locally, stop them before using DDEV. The [troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/index.md>) section goes into more detail about identifying and resolving port conflicts.

### Can AI assistants read the DDEV docs?

Yes. The docs are also published as Markdown for AI assistants and coding agents:

- [`llms.txt`](<https://ddev.github.io/ddev/en/stable/llms.txt>) lists every page, with a link to its Markdown version.
- [`llms-full.txt`](<https://ddev.github.io/ddev/en/stable/llms-full.txt>) contains all pages in one file.

## Performance &amp; Troubleshooting

### How can I get the best performance?

Docker’s normal mounting can be slow on macOS and traditional Windows. DDEV provides its Mutagen feature to work around this, giving fantastic webserving performance. See the [Performance](<https://ddev.github.io/ddev/en/stable/users/install/performance/index.md>) section for how Mutagen works. It’s enabled by default on macOS and Windows.

### How can I troubleshoot what’s going wrong?

See these sections:

- [General troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/index.md>)
- [Xdebug troubleshooting](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/#troubleshooting-xdebug>)
- [Docker troubleshooting](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#troubleshooting-docker>)
- [Traefik troubleshooting](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/#troubleshooting-traefik-routing>)
- [Mutagen troubleshooting](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen-troubleshooting>)

### How can I check that Docker is working?

See the [troubleshooting section](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#troubleshooting-docker>) on the Docker Installation page.

### Why do I get a 403 or 404 on my project after `ddev launch`?

Most likely because the docroot is misconfigured, or there’s no `index.php` or `index.html` in it. Open your `.ddev/config.yaml` file and check the [`docroot`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#docroot>) value, which should be a relative path to the directory containing your project’s `index.php`.

### Why do I see nginx headers when I’ve set `webserver_type: apache-fpm`?

Apache runs in the web container, but when you use the `https://*.ddev.site` URL, it goes through `ddev-router`, which is an nginx reverse proxy. That’s why you see nginx headers even though your web container’s using Apache. Read more in [this Stack Overflow answer](<https://stackoverflow.com/a/52780601/215713>).

### Why are my Apache HTTP → HTTPS redirects stuck in an infinite loop?

It’s common to set up HTTP-to-TLS redirects in an `.htaccess` file, which leads to issues with the DDEV proxy setup. The TLS endpoint of a DDEV project is always the `ddev-router` container and requests are forwarded through plain HTTP to the project’s web server. This results in endless redirects, so you need to change the root `.htaccess` file for Apache correctly handles these requests for your local development environment with DDEV. The following snippet should work for most scenarios—even outside of DDEV—and could replace an existing redirect:

```
# http:// -> https:// plain or behind proxy for Apache 2.2 and 2.4
# behind proxy
RewriteCond %{HTTP:X-FORWARDED-PROTO} ^http$
RewriteRule (.*) https://%{HTTP_HOST}/$1 [R=301,L]

# plain
RewriteCond %{HTTP:X-FORWARDED-PROTO} ^$
RewriteCond %{REQUEST_SCHEME} ^http$ [NC,OR]
RewriteCond %{HTTPS} off
RewriteRule (.*) https://%{HTTP_HOST}/$1 [R=301,L]
```

### My browser redirects `http` URLs to `https`

Several browsers want you to use `https`, so they will automatically redirect you to the `https` version of a site. This may not be what you want, and things may break on redirect. For example, the Apache SOLR web UI often doesn’t work with `https`, and when it redirects it things might break.

To solve this for your browser, see:

- [Google Chrome](<https://stackoverflow.com/q/73875589>)
- [Mozilla Firefox](<https://stackoverflow.com/q/30532471>)
- [Safari](<https://stackoverflow.com/q/46394682>)

### Why is `ddev-webserver` such a huge Docker image?

When you update DDEV you’ll see it pull a `ddev-webserver` image which is almost half a gigabyte compressed, and this can be an inconvenient thing to wait for when you’re doing an upgrade, especially if you have a slow internet connection.

The reason that `ddev-webserver` is so big is that it’s built for your daily requirements for a local development environment. It lets you switch PHP versions or switch between `nginx` and `apache` web servers with a simple `ddev restart`, rather than a lengthy build process. It lets you use Xdebug with a simple `ddev xdebug on`. It has many, many features and tools that make it easy for you as a developer, but that one would not include in a production image.

## Workflow

### How can I update/upgrade DDEV?

See **[Upgrading DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-upgrade/index.md>)** for your operating system and installation technique.

You can use the [`ddev self-upgrade`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#self-upgrade>) command for quick instructions tailored to your installation.

### How can I install a specific version of DDEV?

#### Debian, Ubuntu, or WSL2

For Debian/Ubuntu/WSL2 with DDEV installed via apt, you can run `sudo apt-get update && sudo apt-get install ddev=<version>`, for example `sudo apt-get install ddev=1.23.4` to run a previous, older version of DDEV.

#### Homebrew

Homebrew itself abandoned the ability to specify versions a few years ago, but you can still install an older release by checking out its formula from the tap’s own Git history, then pinning it so `brew upgrade` doesn’t move it:

```
# downgrade to v1.23.5
cd "$(brew --repository ddev/ddev)"
git checkout "$(git rev-list -n 1 --grep='v1.23.5' HEAD)"
HOMEBREW_NO_AUTO_UPDATE=1 brew reinstall ddev/ddev/ddev
brew pin ddev/ddev/ddev
git switch master
```

To go back to the latest release:

```
brew unpin ddev/ddev/ddev
brew update && brew upgrade ddev/ddev/ddev
```

If you want the very latest, unreleased version of DDEV instead, install from `HEAD`:

```
# switch to HEAD
brew uninstall --force ddev
brew install ddev/ddev/ddev --HEAD

# go back to the latest release
brew uninstall --force ddev
brew install ddev/ddev/ddev
```

Your projects are not affected by these changes.

#### Any platform

On any platform you can download the binaries for a specific release with [`ddev utility download-ddev`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-download-ddev>), for example `ddev utility download-ddev --tag v1.25.3`, which writes `ddev` and `ddev-hostname` to `~/tmp/ddev-download-ddev/v1.25.3` so you can try that version before moving them into your `$PATH`.

### Why do I have an old DDEV?

You may have installed DDEV several times using different techniques. Use `which -a ddev` to find all installed binaries. For example, you could install a DDEV in WSL2 with Homebrew, forget about it for a while, install it manually, and then install it again with `apt`:

```
$ which -a ddev
/home/linuxbrew/.linuxbrew/bin/ddev # installed with Homebrew
/usr/local/bin/ddev # installed manually with install_ddev.sh script
/usr/bin/ddev # installed with apt or yum/rpm
/bin/ddev # don't touch it, it's a link to /usr/bin/ddev
```

You can check each binary version by its full path (`/usr/bin/ddev --version`) to find old versions. Remove them preferably in the same way you installed them, i.e. `/home/linuxbrew/.linuxbrew/bin/ddev` should be removed with Homebrew: `brew uninstall ddev`. A manually installed DDEV can be removed by deleting the `ddev` binary.

Restart the terminal (or run `hash -r`) after uninstalling other versions of DDEV for the changes to take effect.

If you see duplicates in the `which -a ddev` output, it means that some directories are added to your `$PATH` more than once. You can either ignore this or remove the extra directory from your `$PATH`.

### Should I check in the `.ddev` directory? How about add-ons?

Most teams check in the project `.ddev` directory. That way all team members will have the exact same configuration for the project, even if they’re on different operating systems or architectures or Docker providers.

DDEV [add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>) are installed via the `.ddev` directory, so checking things in will get them as well, and that’s also recommended practice.

Do *not* alter or check in the `.ddev/.gitignore` as it is automatically generated to DDEV and does its best to figure out what files you “own” (like the `.ddev/config.yaml`) and which files DDEV “owns”, so do not have to be committed.

### How can I back up or restore all project databases?

You can back up all projects that show in `ddev list` with `ddev snapshot -a`. This only snapshots projects displayed in `ddev list`; any projects not shown there will need to be started so they’re be registered in `ddev list`.

### How can I share my local project with someone?

See [Sharing Your Project](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>).

### How do I make DDEV match my production environment?

You can change the major PHP version and choose between nginx+fpm (default) and Apache+fpm and choose the MariaDB/MySQL/PostgreSQL version add [extra services like Solr and Memcached](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>). You won’t be able to make every detail match your production server, but with database server type and version, PHP version and web server type you’ll be close.

The [lightly maintained rfay/ddev-php-patch-build add-on](<https://github.com/rfay/ddev-php-patch-build>) may allow you to use a specific PHP patch version.

### How do I completely destroy a project?

Use [`ddev delete <project>`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) to destroy a project. By default, a [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) of your database is taken, but you can skip this using `ddev delete --omit-snapshot` or `ddev delete --omit-snapshot -y`. See `ddev delete -h` for options. It’s up to you to then delete the code directory.

### What if I don’t like the settings files or gitignores DDEV creates?

You have several options:

- Use the [`disable_settings_management: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) option in the project’s `.ddev/config.yaml` file. This disables DDEV from updating CMS-related settings files.
- Use the more generic “php” project type rather than a CMS-specific one; it basically means “don’t try to create settings files for me”. The “php” type works great for experienced developers.
- Take over the settings file or `.gitignore` by deleting the line `#ddev-generated` in it, then check in the file. If that line is removed, DDEV will not try to replace or change the file. (If you don’t want DDEV to warn you about customized files, add `#ddev-silent-no-warn` to the file.)

### How can I change a project’s name?

Delete it and migrate it to a new project with your preferred name:

1. Export the project’s database: `ddev export-db --file=/path/to/db.sql.gz`.
2. Delete the project: `ddev delete <project>`. (This takes a snapshot by default for safety.)
3. Remove the `.ddev/traefik/config` directory, `rm -r .ddev/traefik/config`, since it may have name-based configuration.
4. Rename the project: `ddev config --project-name=<new_name>`.
5. Start the new project with `ddev start`.
6. Import the database dump from step one: `ddev import-db --file=/path/to/db.sql.gz`.

### How can I move a project to another directory?

Run [`ddev stop --unlist`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>), then move the directory, then run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) in the new directory.

### How can I move a project to another workstation?

Take a snapshot, move the project files, and restore the snapshot in a new project on the target workstation:

1. `ddev start && ddev snapshot`.
2. `ddev stop --unlist`.
3. Move the project directory to another computer any way you want.
4. On the new computer, run `ddev start && ddev snapshot restore --latest`.
5. Optionally, on the old computer, run `ddev delete --omit-snapshot` to remove its copy of the database.

### How can I move a project from traditional Windows to WSL2?

WSL2 has intolerably slow access to the Traditional Windows NTFS/CIFS filesystem, but the WSL2 filesystem is blazingly fast. It’s really important to move your project to the WSL2 native filesystem. This is exactly the same as moving a project from one computer to another described above. Make a backup of the database, `ddev snapshot && ddev stop --unlist`, and then copy your project to the new WSL2 location. For example, if your project is at `C:\Users\you\sites\someproject` you could do this in your WSL2 distro:

```
cd $HOME
mkdir -p sites && cd sites
cp -r "/mnt/c/you/sites/someproject" .
cd someproject
ddev start
ddev snapshot restore --latest
```

### Why does DDEV want to edit `/etc/hosts`?

If you see “The hostname  is not currently resolvable” and you can successfully `ping <hostname>`, it may be that DNS resolution is slow.

DDEV doesn’t have control over your computer’s name resolution, so it doesn’t have any way to influence how your browser gets an IP address from a hostname. It knows you have to be connected to the internet to do that, and uses a test DNS lookup of `<somethingrandom>.ddev.site` as a way to guess whether you’re connected to the internet. If it’s unable to do a name lookup, or if the hostname associated with your project is not `*.ddev.site`, it will try to create entries in `/etc/hosts`, since it’s assuming you can’t look up your project’s hostname(s) via DNS. If your internet (and name resolution) is actually working, but DNS is slow, run `ddev config global --internet-detection-timeout-ms=3000` to set the timeout to 3 seconds (or higher). See [this GitHub issue](<https://github.com/ddev/ddev/issues/2409#issuecomment-662448025>) for more. (If DNS rebinding is disallowed on your network/router, this won’t be solvable without network/router changes. Help in [comment 1](<https://github.com/ddev/ddev/issues/2409#issuecomment-675083658>) and [comment 2](<https://github.com/ddev/ddev/issues/2409#issuecomment-686718237>).) For more detailed troubleshooting information, please see the [troubleshooting section](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#ddev-starts-but-browser-cant-access-url>).

### How can I configure a project with the defaults without hitting <kbd>RETURN</kbd> a bunch of times?

Use `ddev config --auto` to set the docroot and project type based on the discovered code. If anything in `.ddev/config.yaml` is wrong, you can edit that directly or use [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) commands to update settings.

You can also use `ddev config --update` if the code is already in place and it will autodetect the project type and other needed settings.

### I want to use the same code with various project names

If you remove the `name` line from your project’s `.ddev/config.yaml`, then the project will take the name of the directory it is in.

This allows you to have multiple check-outs of the same project, each with different names.

It can also allow team members to have the same project run using different hostnames and URLs.

### What happens when one DDEV project is nested inside another?

Avoid nesting one DDEV project inside another; it only causes confusion. It usually happens by accident, with a Git submodule or dependency that ships its own `.ddev/config.yaml`.

DDEV only uses a project that shows up in `ddev list`, so inside an unregistered nested project it warns and uses the registered project around it instead. To use the nested project, run `ddev start` in its directory and confirm the prompt, which adds it to `ddev list`.

## Getting Involved

### How do I get support?

See the [support options](<https://ddev.github.io/ddev/en/stable/users/support/index.md>), including [Discord](<https://ddev.com/s/discord>) and the [issue queue](<https://github.com/ddev/ddev/issues>).

### How can I contribute to DDEV?

We love and welcome contributions of knowledge, support, docs, and code:

- Submit an issue or pull request to the [main repository](<https://github.com/ddev/ddev>).
- Add your external resource to [awesome-ddev](<https://github.com/ddev/awesome-ddev>).
- Help others in [Discord](<https://ddev.com/s/discord>).
- Contribute financially by [sponsoring DDEV](<https://ddev.com/sponsor>).
- Get involved with DDEV governance and the [Advisory Group](<https://github.com/ddev/ddev/discussions/categories/ddev-advisory-group>).

### How do financial contributions support DDEV?

Thanks for asking! Contributions made by [sponsoring DDEV](<https://ddev.com/sponsor>) go to the [DDEV Foundation](<https://ddev.com/foundation>) and are used for infrastructure and supporting development.

# Usage

This section covers day-to-day DDEV usage, reference material, and common support details.

## Common Tasks

- [Using the `ddev` Command](<https://ddev.github.io/ddev/en/stable/users/usage/cli/index.md>)
- [Interactive Dashboard](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#interactive-dashboard>)
- [Database Management](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/index.md>)
- [Managing CMS Settings](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/index.md>)
- [Managing Projects](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/index.md>)
- [Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/index.md>)
- [Using DDEV Offline](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>)
- [Upgrading DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-upgrade/index.md>)

## Reference

- [How DDEV Works](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/index.md>)
- [Commands](<https://ddev.github.io/ddev/en/stable/users/usage/commands/index.md>)
- [Built-in Developer Tools](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/index.md>)
- [Diagnostics](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>)
- [Uninstalling](<https://ddev.github.io/ddev/en/stable/users/usage/uninstall/index.md>)

## Getting Help

- [FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/index.md>)
- [Support](<https://ddev.github.io/ddev/en/stable/users/support/index.md>)
- [Code of Conduct](<https://ddev.github.io/ddev/en/stable/users/code-of-conduct/index.md>)

## Configuration Files

The [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) and `ddev start` commands attempt to create a CMS-specific settings file pre-populated with DDEV credentials. If you don’t want DDEV to do this, set the [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) config option to `true`.

For **Craft CMS** DDEV settings are added to the `.env` file.

For **Drupal** and **Backdrop**, DDEV settings are written to a DDEV-managed file, `settings.ddev.php`. The `ddev config` command will ensure these settings are included in your `settings.php` through the following steps:

- Write DDEV settings to `settings.ddev.php`.
- If no `settings.php` file exists, create one that includes `settings.ddev.php`.
- If a `settings.php` file already exists, ensure that it includes `settings.ddev.php`, modifying `settings.php` to write the include if necessary.

For **Magento 1**, DDEV settings go into `app/etc/local.xml`.

In **Magento 2**, DDEV settings go into `app/etc/env.php`.

For **Maho**, DDEV settings go into `app/etc/local.xml`.

For **TYPO3**, DDEV settings are written to `config/system/additional.php`. If `additional.php` exists and is not managed by DDEV, it will not be modified.

For **WordPress**, DDEV settings are written to a DDEV-managed file, `wp-config-ddev.php`. The `ddev config` command will attempt to write settings through the following steps:

- Write DDEV settings to `wp-config-ddev.php`.
- If no `wp-config.php` exists, create one that include `wp-config-ddev.php`.
- If a DDEV-managed `wp-config.php` exists, create one that includes `wp-config.php`.
- If a user-managed `wp-config.php` exists, instruct the user on how to modify it to include DDEV settings.

You’ll know DDEV is managing a settings file when you see a comment containing `#ddev-generated` like the one below. Remove the comment and DDEV will not attempt to overwrite it. If you’re letting DDEV create its settings file, we recommended leaving this comment so DDEV can continue to manage it, and make any needed changes in another settings file.

```
/**
 #ddev-generated: Automatically generated Drupal settings.php file.
 ddev manages this file and may delete or overwrite the file unless this comment is removed.
 */
```

If you’re providing the `settings.php` or `wp-config.php` and DDEV is creating `settings.ddev.php` (or `wp-config-local.php`, `AdditionalConfig.php`, or similar), the main settings file must explicitly include the appropriate DDEV-generated settings file. Any changes you need should be included somewhere that loads after DDEV’s settings file, for example in Drupal’s `settings.php` *after* `settings.ddev.php` is included. (See [Adding Configuration](<#adding-configuration>) below).

### Adding Configuration

**Drupal and Backdrop**: In `settings.php`, enable loading `settings.local.php` after `settings.ddev.php` is included—creating a new one if it doesn’t already exist—and make changes there. Wrap with `if (getenv('IS_DDEV_PROJECT') == 'true')` as needed.

**WordPress**: Load a `wp-config-local.php` after `wp-config-ddev.php`, and make changes there. Wrap with `if (getenv('IS_DDEV_PROJECT') == 'true')` as needed.

## Listing Project Information

> [!TIP]
>
> **TUI (Terminal UI) Alternative**
>
> You can also view and manage all your projects from the [interactive dashboard](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#interactive-dashboard>) by running `ddev` with no arguments.

Run [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) or `ddev list --active-only` current projects.

```
➜  ddev list
 NAME            STATUS        LOCATION                    URL                           TYPE
 d10             stopped       ~/workspace/d10                                           drupal10
 drup            running (ok)  ~/workspace/drup            https://drup.ddev.site        drupal
 my-cakephp-app  stopped       ~/workspace/my-cakephp-app                                cakephp
 Router          healthy       ~/.ddev                     http://127.0.0.1:10999        traefik
```

```
➜  ddev list --active-only
 NAME        STATUS        LOCATION                URL                           TYPE
 drup        running (ok)  ~/workspace/drup        https://drup.ddev.site        drupal
 Router      healthy       ~/.ddev                 http://127.0.0.1:10999        traefik
```

You can also see more detailed information about a project by running [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) from its working directory. You can also run `ddev describe [project-name]` from any location to see the detailed information for a running project.

```
$ ddev describe drup
┌──────────────────────────────────────────────────────────────────────────────────┐
│ Project: drup ~/workspace/drup https://drup.ddev.site                            │
│ Docker platform: orbstack                                                        │
│ Router: traefik                                                                  │
├──────────┬──────┬───────────────────────────────────────────┬────────────────────┤
│ SERVICE  │ STAT │ URL/PORT                                  │ INFO               │
├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
│ web      │ OK   │ https://drup.ddev.site                    │ drupal PHP8.4      │
│          │      │ InDocker: web:8025,443,80                 │ nginx-fpm          │
│          │      │ Host: 127.0.0.1:33016,33017               │ docroot:'web'      │
│          │      │                                           │ Perf mode: mutagen │
│          │      │                                           │ NodeJS:20          │
├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
│ db       │ OK   │ InDocker: db:3306                         │ mariadb:11.8       │
│          │      │ Host: 127.0.0.1:33018                     │ User/Pass: 'db/db' │
│          │      │                                           │ or 'root/root'     │
├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
│ Mailpit  │      │ Mailpit: https://drup.ddev.site:8026      │                    │
│          │      │ `ddev mailpit`                            │                    │
├──────────┼──────┼───────────────────────────────────────────┼────────────────────┤
│ All URLs │      │ https://drup.ddev.site,                   │                    │
│          │      │ https://127.0.0.1:33016,                  │                    │
│          │      │ http://drup.ddev.site,                    │                    │
│          │      │ http://127.0.0.1:33017                    │                    │
└──────────┴──────┴───────────────────────────────────────────┴────────────────────┘
```

## Removing Projects

There are two ways to remove a project from DDEV’s listing.

The first, the [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) command, is destructive. It removes the project from DDEV’s list, deletes its database, and removes the hostname entry from the hosts file:

`ddev delete <projectname>` or `ddev delete --omit-snapshot <projectname>`

If you don’t want the project to show up in [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) anymore, use [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>)—which is nondestructive—to unlist the project until the next time you run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) or [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>):

```
ddev stop --unlist <projectname>
```

## Importing Assets for An Existing Project

An important aspect of local web development is the ability to have a precise local recreation of the project you’re working on, including up-to-date database contents and static assets like uploaded images and files. DDEV provides two commands to help with importing assets to your local environment.

### Importing a Database

The [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) command imports the database for a project. Running this command will prompt you to specify the location of your database import. By default `ddev import-db` empties the default `db` database, then loads the provided dump file. Most people use it with command flags, like `ddev import-db --file=.tarballs/db.sql.gz`, but it can also prompt for the location of the dump if you only use `ddev import-db`:

```
ddev import-db
Provide the path to the database you wish to import.
Import path:
~/Downloads/db.sql
Importing database...
Successfully imported database for drupal8
```

#### Supported Database Import File Types

Database imports can be any of the following file types:

- Raw SQL Dump (`.sql`)
- Gzipped SQL Dump (`.sql.gz`)
- `bzip2` SQL Dump (`.sql.bz2`)
- Xz’d SQL Dump (`.sql.xz`)
- Zstandard SQL Dump (`.sql.zst`)
- Tarball Archive (`.tar`, `.tar.gz`, `.tgz`, `.tar.bz2`, `.tar.xz`, `.tar.zst`)
- ZIP Archive (`.zip`)
- stdin

If a Tarball Archive or ZIP Archive is provided for the import, you’ll be prompted to specify a path within the archive to use for the import asset. The specified path should provide a raw SQL dump (`.sql`). In the following example, the database we want to import is named `data.sql` and resides at the top level of the archive:

```
ddev import-db
Provide the path to the database you wish to import.
Import path:
~/Downloads/site-backup.tar.gz
You provided an archive. Do you want to extract from a specific path in your archive? You may leave this blank if you wish to use the full archive contents
Archive extraction path:
data.sql
Importing database...
A settings file already exists for your application, so ddev did not generate one.
Run 'ddev describe' to find the database credentials for this application.
Successfully imported database for drupal8
```

#### Non-Interactive Usage

If you want to use the [`import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) command without answering prompts, you can use the `--file` flag to provide the path to the import asset. If you’re importing an archive and wish to specify the path within the archive to extract, you can use the `--extract-path` flag in conjunction with the `--file` flag. Examples:

```
ddev import-db --file=/tmp/mydb.sql.gz
gzip -dc /tmp/mydb.sql.gz | ddev import-db
ddev import-db <mydb.sql
```

#### Database Import Notes

- Importing from a dump file via stdin will not show progress because there’s no way the import can know how far along through the import it has progressed.
- Use `ddev import-db --target-db <some_database>` to import to a non-default database (other than the default `db` database). This will create the database if it doesn’t already exist.
- Use `ddev import-db --no-drop` to import without first emptying the database.
- If a database already exists and the import does not specify dropping tables, the contents of the imported dumpfile will be *added* to the database. Most full database dumps do a table drop and create before loading, but if yours does not, you can drop all tables with `ddev stop --remove-data` before importing.
- If imports are stalling or failing, make sure you have plenty of unused space (see [\#3360](<https://github.com/ddev/ddev/issues/3360>)). DDEV has no problems importing large (2G+) databases, but importing requires lots of space. DDEV will show a warning on startup if unused space is getting low.

## Inter-Project Communication

### Access another project’s database

To connect the `web` container to the `db` container of a different project, use `ddev-<projectname>-db` as the hostname.

Example: two projects, `backend` and `frontend`.

In the `frontend` project:

```
ddev exec mysql -h ddev-backend-db
```

> [!NOTE]
>
> **Database host reset after restart**
>
> DDEV manages certain [CMS settings](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/index.md>). If you change the database host in `.env`, it may reset to `db` after `ddev restart`.
>
> Disable this behavior by setting [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) to `true` or running [`ddev config --disable-settings-management`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).

### Access another project via HTTP/S

Example: two projects, `backend` and `frontend`.

From v1.24.10+, DDEV supports direct HTTP/S calls between projects:

```
# From frontend web container to backend web container
ddev exec curl https://backend.ddev.site

# Or using internal Docker hostname
ddev exec curl https://ddev-backend-web
```

> [!NOTE]
>
> **Using HTTPS from a non-web container**
>
> HTTP works without extra setup. For HTTPS, the calling container must trust the `ddev-webserver` certificate authority (CA).
>
> ```
> $ ddev exec -s some-service curl https://backend.ddev.site
> curl: (60) SSL certificate problem: unable to get local issuer certificate
> More details: https://curl.se/docs/sslcerts.html
> ```
>
> See [Third-party services may need to trust `ddev-webserver`](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#third-party-services-may-need-to-trust-ddev-webserver>).

### Access another service in the same or different project

- **Same project**: containers reach each other by service name. No project name prefix is required.
- **Different project**: containers reach each other with `ddev-<projectname>-<service>`.

Example in a single project with `web` and `opensearch` services:

```
# From web container to opensearch
ddev exec curl http://opensearch:9200

# From opensearch container to web
ddev exec -s opensearch curl http://web
```

Example with two projects, `frontend` and `backend` (`backend` has `opensearch` service):

```
# From frontend web container to backend opensearch
ddev exec curl http://ddev-backend-opensearch:9200
```

### Access services on the host machine

To connect from a container to a service on the host, use `host.docker.internal` as the hostname.

```
# Test connection to host service on port 8000
ddev exec telnet host.docker.internal 8000

# Call API on host
ddev exec curl http://host.docker.internal:8000/some/api/endpoint
```

> [!NOTE]
>
> **Host service binding**
>
> Services on the host must listen on all interfaces (`0.0.0.0`), not only `127.0.0.1` (`localhost`).

# Special Network Configurations

> [!TIP]
>
> **The networking configurations described here are not typical**
>
> Don’t spend time with this page unless you know you have a global TLS trust or proxy configuration issue.

There are a few networking situations which occasionally cause trouble for some users, especially in corporate environments. These typically fall into two categories:

1. **TLS interception** (e.g., Zscaler, GlobalProtect) causes SSL verification errors in `docker pull` or inside containers.
2. **Proxy-only internet access**, which blocks Docker or container tools unless proxy settings are configured.

In these situations, multiple layers may require configuration:

- **Docker Engine**: Trust external registries
- **Docker CLI**: Use system or explicit proxy settings
- **Containers (e.g., DDEV web)**: Trust HTTPS inside the container
- **Package Managers (e.g., apt)**: If used inside containers, may also need proxy/CA configuration

## Corporate Packet-inspection VPNs (including Zscaler and Global Protect)

> [!NOTE]
>
> **Your IT Department or Vendor May Have Easier Ways to Solve These Problems**
>
> In many cases, your IT department or VPN vendor may be able to whitelist certain internet resources, and you may not have to do extensive configuration. Check with them (if possible) before you start making configuration changes.

Packet-inspecting VPNs like **Zscaler**, **GlobalProtect**, and similar products intercept HTTPS traffic using a corporate-controlled TLS Certificate Authority (CA). These systems act as a “man-in-the-middle” proxy, decrypting and re-encrypting HTTPS traffic. As a result, systems and applications that are not explicitly configured to trust the corporate CA will experience SSL/TLS verification errors.

This creates two separate problems in Docker-based workflows:

| Layer | Problem | Solution |
| --- | --- | --- |
| Docker Engine | `docker pull` fails with certificate errors when connecting to Docker registries like `hub.docker.com` | Configure Docker Engine to trust the corporate CA |
| Inside Containers | Tools like `curl` or `composer` inside containers fail to connect to the internet | Install the corporate CA in the container image |

### 🧩 Docker Engine SSL Trust (for `docker pull`)

The Docker Provider itself must trust the corporate CA to pull images from remote registries. The method of adding this trust varies by platform and Docker engine.

Often, though, the easiest way to solve this particular problem is for your IT department or VPN vendor to whitelist your registry (usually `registry-1.docker.io`) so you don’t have to deal with this problem in the first place. If you can’t do that, a variety of solutions are provided below.

#### macOS

- **Docker Desktop**, **Orbstack**, and **Rancher Desktop** automatically use the macOS system keychain, so you likely don’t need to configure SSL trust.
- **Colima**: Colima copies `~/.docker/certs.d` into the VM at startup. To trust a CA, place it in `~/.docker/certs.d/` **before** starting Colima.
- **Lima**: Copy the CA certificate into `/etc/docker/certs.d/` using `limactl shell default`.

#### Windows

Install the trusted certificate in the system:

1. Search “Settings” for “Manage Computer Certificates”, which runs `certlm`.
2. Navigate to “Certificates - Local Computer” -\> “Trusted Root Certification” -\> “Certificates”.
3. Right-click -\> “All tasks” -\> “Import” to import the `crt` file.
4. **Docker Desktop**: Uses the Windows system certificate store. If the CA is trusted by the system, Docker will trust it too.
5. **WSL2 with Docker Desktop**: Behaves like Docker Desktop (Windows trust store).
6. **WSL2 with `docker-ce`**: Requires manual installation of the CA cert as with native Linux.

#### Linux

For native Linux or WSL2 with `docker-ce`:

```
sudo mkdir -p /etc/docker/certs.d/
sudo cp mycorp-ca.crt /etc/docker/certs.d/
sudo systemctl restart docker
```

#### ✅ **Test Docker Engine Trust**

To test:

```
docker pull alpine
# ✅ Should succeed if CA is trusted
# ❌ If not trusted: x509: certificate signed by unknown authority
```

If it works without SSL errors, the CA is trusted properly.

See [Docker Engine certificate configuration](<https://docs.docker.com/engine/security/certificates/>) for more background.

---

### 📦 Container-Level SSL Trust (for `curl`, `composer`, `Node.js`, etc.)

Applications running inside containers do **not** inherit trust from the host system. If the container makes outbound HTTPS connections, you must install the corporate CA inside the container image.

The standard approach:

1. Export the corporate CA certificate (`.crt`) as described in the section below. Use the name of your `crt` file, not `mycorp-ca.crt`.
2. Place the `.crt` file in both your `.ddev/web-build` and `.ddev/db-build` directories.
3. Add a `.ddev/web-build/pre.Dockerfile.vpn` and `.ddev/db-build/pre.Dockerfile.vpn` like this:

   ```
   COPY mycorp-ca.crt /usr/local/share/ca-certificates/
   RUN update-ca-certificates
   ```

   > **Apply to all projects**
   >
   > Put these Dockerfiles in `$HOME/.ddev/web-build/` and `$HOME/.ddev/db-build/` to apply them to every project, see [Global Dockerfiles](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#global-dockerfiles>).
4. If you’re using Node.js/npm make it trust both the DDEV `mkcert` CA and your corporate CA by combining the two into a single file and then making the environment variable `NODE_EXTRA_CA_CERTS` point to that file. Add a post-start hook to concatenate the required files into the needed `/usr/local/share/ca-certificates/node_ca_certs.pem`. For example, in a `.ddev/config.vpn.yaml` add `post-start` hook:

   ```
   web_environment:
     - NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/node_ca_certs.pem
   hooks:
     post-start:
       - exec: "cat /mnt/ddev-global-cache/mkcert/rootCA.pem /usr/local/share/ca-certificates/mycorp-ca.crt > /usr/local/share/ca-certificates/node_ca_certs.pem"
   ```

   > **Apply to all projects**
   >
   > The same `web_environment` and `hooks` can go in `$HOME/.ddev/global_config.yaml` to apply to every project, see [Global Hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/#global-hooks>). On machines that are not behind the proxy the certificate is missing and the `cat` would report a failed hook, so guard it:
   >
   > ```
   > hooks:
   >   post-start:
   >     - exec: "if test -f /usr/local/share/ca-certificates/mycorp-ca.crt; then cat /mnt/ddev-global-cache/mkcert/rootCA.pem /usr/local/share/ca-certificates/mycorp-ca.crt > /usr/local/share/ca-certificates/node_ca_certs.pem; fi"
   > ```
5. Run:

   ```
   ddev restart
   ddev exec curl -I https://www.google.com
   # ✅ Expect: HTTP/2 200
   # ❌ If not trusted: curl: (60) SSL certificate problem
   ddev npm install --verbose
   # ✅ Expect: Successful install
   # ❌ If not trusted: attempt 2 failed with SELF_SIGNED_CERT_IN_CHAIN
   ddev yarn install
   # ✅ Expect: Successful install
   # ❌ If not trusted: code: 'SELF_SIGNED_CERT_IN_CHAIN'
   ```

This method works across all OS platforms and all Docker providers, because you’re explicitly modifying the container’s certificate store.

> [!NOTE]
>
> **Clear or recreate buildx contexts**
>
> During the testing process, we found that an old `docker buildx` context can make all of the `ddev start` builds fail in this situation. We had to remove buildx contexts (`docker buildx ls` and `docker buildx rm <context>` may help, or removing the `~/.docker/buildx` directory.)

---

### 🔍 Where to Get the Corporate CA Certificate

#### Option 1: Ask Your IT Department

Request the “TLS root certificate” or “SSL inspection CA” used by your company’s VPN or proxy.

#### Option 2: Extract from Your Own System

- **macOS**: Use Keychain Access to export the cert from the “System” keychain.
- **Windows**: Use `certmgr.msc` and export the cert from “Trusted Root Certification Authorities”.
- **Linux**: Locate and copy certs from `/etc/ssl/certs/` or use Firefox + `certutil`.

You can also visit a site like `https://www.google.com` in Chrome or Firefox, inspect the certificate chain, and export the root CA manually ([example method](<https://stackoverflow.com/a/71642712/215713>)).

### Converting Exported PEM or CER Files to CRT

When you export a CA certificate from your system (e.g., Keychain Access on macOS or certmgr on Windows), the file may be saved with a `.pem` or `.cer` extension. These are usually the same format as `.crt`: a base64-encoded X.509 certificate.

For Docker or Linux tools that expect a `.crt` file, you can simply rename the exported file:

```
mv your-cert.pem your-cert.crt
# or
mv your-cert.cer your-cert.crt
```

To confirm it is the correct format, the file should begin with:

```
-----BEGIN CERTIFICATE-----
```

If your file contains this header, renaming it to `.crt` is sufficient for use with Docker and container trust configurations.

### Corporate Packet-inspection VPN Resources

- [Network Test Environments: Packet-Inspection VPN Simulation](<https://ddev.github.io/ddev/en/stable/developers/network-test-environments/index.md>)
- [Adding Self-signed Registry Certs to Docker &amp; Docker for Mac](<https://blog.container-solutions.com/adding-self-signed-registry-certs-docker-mac>)
- [Docker Docs: How Do I Add TLS Certificates](<https://docs.docker.com/desktop/troubleshoot-and-support/faqs/macfaqs/#how-do-i-add-tls-certificates>)

### VPN Trust Summary by Provider

| Provider | Engine Trust Needed? | Auto-Inherits Host Trust? | Notes |
| --- | --- | --- | --- |
| Docker Desktop | No | ✅ | Uses macOS/Windows system keychain |
| Orbstack | No | ✅ | Fully integrated with macOS keychain |
| Colima | Yes | 🚫 | Requires pre-start copy of certs |
| Rancher Desktop | Yes (dockerd) | Partial | Depends on Lima config and backend |
| WSL2 + docker-ce | Yes | 🚫 | Must configure trust inside WSL |

### Cloudflare WARP (Zero Trust)

If you are using [Cloudflare WARP](<https://developers.cloudflare.com/cloudflare-one/team-and-resources/devices/warp/>) (Zero Trust), you might find that `*.ddev.site` domains (or other domains you might use that resolve to 127.0.0.1) do not resolve because WARP intercepts and routes all traffic through its network, bypassing your local loopback.

To fix this, configure **Split Tunneling** in your Cloudflare dashboard (or local settings):

1. Log in to your Cloudflare Zero Trust dashboard.
2. Go to **Settings** \> **WARP Client** \> **Device Settings**.
3. Locate your profile and click **Edit**.
4. Under **Split Tunnels**, ensure the mode is set to **Exclude**.
5. Add the following **Selector** entries:

**Domains:**

- `*.ddev.site`
- `ddev.site`
- Any other domain you use with DDEV which resolves to `127.0.0.1`

**IP Addresses:**

- `127.0.0.1/8` (Localhost)
- `172.16.0.0/12` (Standard Docker range)

> [!NOTE]
>
> The `172.16.0.0/12` range might overlap with your internal corporate networks. If you lose access to corporate resources:
>
> - Identify the specific Docker ranges you need using a CIDR calculator and only exclude those.
> - Or [reconfigure Docker’s default IP ranges](<https://www.lullabot.com/articles/fixing-docker-and-vpn-ip-address-conflicts>) to use a different range and exclude that one instead.

## Corporate or Internet Provider Proxy

Some network environments, including some corporate networks, require a “proxy” system be used to access the outside network. In these environments, most systems do not have direct access to the public internet, but instead must use a configured proxy host to access the public internet. A proxy is a system that receives HTTP and HTTPS traffic and then sends and receives traffic on behalf of the client that requests it.

In most environments, the proxy will be configured at a system level. For example, on macOS, it can be configured at `Settings -> Wi-Fi -> Connection -> Details -> Proxies`. On Ubuntu it’s at `Settings -> Network -> Network Proxy`.

In each of these situations the configuration required is essentially this:

- HTTP Proxy or “Web Proxy (HTTP)”
- HTTPS Proxy or “Secure web proxy (HTTPS)”
- “Ignore Hosts” or “Bypass proxy settings for these hosts”

Given a proxy with the hostname `yourproxy.intranet` with the IP address `192.168.1.254` and a port of `8888`, you would usually configure the HTTP and HTTPS Proxies as `yourproxy.intranet` with port `8888`. But it’s usually important to tell your system *not* to proxy some hostnames and IP addresses, including `localhost`, `*.ddev.site`, `127.0.0.1`, and `::1`. These exclusions ensure that local development domains (such as `*.ddev.site`) and local network addresses (`127.0.0.1`, `::1`) are not mistakenly routed through the proxy, which could disrupt DDEV’s functionality.

System configuration in many systems results in environment variables like these examples:

- `HTTP_PROXY=http://yourproxy.intranet:8888`
- `HTTPS_PROXY=http://yourproxy.intranet:8888`
- `NO_PROXY=localhost,127.0.0.1,::1,*.ddev.site`

If they are not set automatically, they can be set manually in your `.bash_profile` or similar configuration file.

### Configuring Docker Daemon for Proxy

See the [Docker documentation](<https://docs.docker.com/engine/daemon/proxy/#daemon-configuration>) to configure the Docker daemon for access to the Docker registry (for actions like `docker pull`).

For example, `/etc/docker/daemon.json` might be:

```
{
  "proxies": {
    "http-proxy": "http://squid.host-only:3128",
    "https-proxy": "http://squid.host-only:3128",
    "no-proxy": "localhost,127.0.0.0/8"
  }
}
```

After configuration,

```
sudo systemctl restart docker
```

When this is working, you should be able to successfully `docker pull alpine`.

### Configuring Docker Client for Proxy

See the [Docker documentation](<https://docs.docker.com/engine/cli/proxy/#configure-the-docker-client>) for how to configure the Docker client to pass proxy variables during container build (`ddev start`) and runtime (`ddev exec`).

For example, `~/.docker/config.json` might be:

```
{
  "proxies": {
    "default": {
      "httpProxy": "http://squid.host-only:3128",
      "httpsProxy": "http://squid.host-only:3128",
      "noProxy": "localhost,127.0.0.0/8"
    }
  }
}
```

After configuration, restart the DDEV project if it is already running.

### Proxy Resources

- [HTTP Proxy Test Environments](<https://ddev.github.io/ddev/en/stable/developers/http-proxy-test-environments/index.md>)
- [Configuring Rancher Desktop Proxy](<https://github.com/rancher-sandbox/rancher-desktop/issues/2259#issuecomment-1136833849>)
- [Colima proxy setup](<https://gist.github.com/res0nat0r/e182f23272a331f20b83195156eef83f>)
- [Linux Docker Daemon Proxy Configuration](<https://docs.docker.com/engine/daemon/proxy/#daemon-configuration>)
- [Linux Docker Client Proxy Configuration](<https://docs.docker.com/engine/cli/proxy/#configure-the-docker-client>)
- [Colima Proxy Configuration](<https://gist.github.com/res0nat0r/e182f23272a331f20b83195156eef83f>)

## WSL2 VirtioProxy Mode (Netskope and Similar VPNs)

Some corporate VPNs, notably **Netskope**, intercept network traffic in a way that is incompatible with the default WSL2 NAT networking mode. The WSL2 `VirtioProxy` networking mode can work around this, and is the primary reason users end up in VirtioProxy mode.

VirtioProxy mode is experimental and poorly documented by Microsoft. On some machines it works well; on others, the WSL2 distro has no internet access at all, which means tools like Composer and npm will not function. DDEV treats this mode as best-effort.

See the [WSL2 VirtioProxy system requirements](<https://ddev.github.io/ddev/en/stable/#windows-wsl2>) for setup instructions.

**Known limitations of VirtioProxy mode:**

- On some machines, the WSL2 distro has no internet access at all (Composer, npm, etc. will not work).
- The WSL2 distro and Docker containers cannot make outgoing connections to the Windows host. This means a Windows-side IDE cannot receive Xdebug connections. Use an IDE inside WSL2 via WSLg and set `ddev config global --xdebug-ide-location=wsl2`.
- Accessing DDEV sites from a Windows browser works normally.

If you are not required to use VirtioProxy, the [Traditional Windows](<https://ddev.github.io/ddev/en/stable/#traditional-windows>) approach (Docker Desktop with WSL2 backend) avoids these limitations entirely.

## Restrictive DNS servers, especially Fritz!Box (FritzBox) routers

The normal use of DDEV involves project URLs (and hostnames) like `*.ddev.site`. So a project with the name `mytypo3` will have the default hostname `mytypo3.ddev.site` and the default URL `https://mytypo3.ddev.site`. The way this works is that `*.ddev.site` is a Domain Name System (DNS) entry which always resolves to `127.0.0.1`, or `localhost`.

There are a few DNS servers, mostly local Fritz!Box routers, which do not allow a DNS lookup to result in `127.0.0.1`. In this situation, DDEV will ask you to use superuser (`sudo`) privileges to add the hostname to the system `hosts` file, often `/etc/hosts` or `C:\Windows\system32\drivers\etc\hosts`. **This is not the preferred behavior, as DDEV does not want to edit your system files.**

Instead, if DDEV is asking you to do this and add hostnames, it’s best to solve the underlying problem by adding configuration to the DNS server (often Fritz!Box router) or by using a less-restrictive DNS server like the Cloudflare `1.1.1.1` public DNS server. Full details are at [Fritz!Box Routers and DDEV](<https://ddev.com/blog/fritzbox-routers-and-ddev/>).

These options are explained in the [Troubleshooting - DNS Rebinding](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#dns-rebinding-prohibited-mostly-on-fritzbox-routers>) section of the documentation.

# Using DDEV Offline

> [!WARNING]
>
> **Prepare all projects and pull Docker images before going offline**
>
> All necessary Docker images must be downloaded and built prior to working offline.
>
> Run the following commands:
>
> ```
> # Download all images for all projects
> ddev utility download-images --all
>
> # Start all projects to ensure images are built
> ddev start --all
>
> # Stop all projects
> ddev poweroff
> ```

DDEV attempts to work smoothly offline, and you shouldn’t have to do anything to make it work.

However, it cannot pull needed Docker images when offline if a new Docker image is required, so you’ll want to make sure that you try a [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) before going offline to make sure everything has been pulled.

`ddev start` builds project images every time. If that build fails and Docker Hub can’t be reached, DDEV warns and starts with the images from the last successful build, so changes to a Dockerfile made while offline take effect on the next online `ddev start`. When Docker Hub can be reached, a failed build stops `ddev start` as usual.

If you have a project running when you’re online (using DNS for name resolution) and you then go offline, do a [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) to get the hostname added into `/etc/hosts` for name resolution.

You have some general options as well:

In `.ddev/config.yaml`, [`use_dns_when_possible: false`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#use_dns_when_possible>) will make DDEV never try to use DNS for resolution, instead adding hostnames to `/etc/hosts`. You can also use `ddev config --use-dns-when-possible=false` to set this configuration option.

You can also set up a local DNS server like [dnsmasq](<https://dnsmasq.org>) (Linux and macOS, `brew install dnsmasq`) or ([unbound](<https://github.com/NLnetLabs/unbound>) or many others on Windows) in your own host environment that serves the `project_tld` that you choose, and DNS resolution will work fine. You’ll likely want a wildcard A record pointing to `127.0.0.1` on most DDEV installations. If you use dnsmasq, you must configure it to allow DNS rebinding.

To understand what’s going on with name resolution and your browser and offline use, we recommend [Hostnames and Wildcards and DDEV Oh My! on ddev.com](<https://ddev.com/blog/ddev-name-resolution-wildcards/>).

> [!NOTE]
>
> **Administrative Privileges Required**
>
> If you `ddev start` when offline, DDEV will try to add `<projectname>.ddev.site` to your `/etc/hosts` file. You must have administrative privileges to edit the hosts file on any operating system.

> [!NOTE]
>
> **Oddities of using `buildx` `docker-container` driver**
>
> This is an unusual situation, mostly encountered by DDEV developers who have been pushing images, but you may not be able to work offline if your `docker buildx inspect` shows the `docker-container` driver, and you’ll need to switch to a builder that has the `docker` driver. `docker buildx ls` will show available drivers, or you can switch to one with `docker buildx create --name docker-driver --driver docker --use`. This is reported in [docker buildx issue](<https://github.com/moby/buildkit/issues/5214>).

# Troubleshooting

Things might go wrong! In addition to this page, consider checking [the DDEV issue queue](<https://github.com/ddev/ddev/issues>) and [other support options](<https://ddev.github.io/ddev/en/stable/users/support/index.md>), as well as [Docker troubleshooting suggestions](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#troubleshooting-docker>) and [Mutagen troubleshooting suggestions](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen-troubleshooting>).

## General Troubleshooting Strategies

- Please use the [current stable version of DDEV](<https://ddev.github.io/ddev/en/stable/users/install/ddev-upgrade/index.md>) and of your Docker provider before going too far or asking for support.
- Run [`ddev utility diagnose`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-diagnose>) to get a quick assessment of your DDEV installation and current project. This provides concise, actionable diagnostics for common issues.
- Start by running [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) to make sure all containers can start fresh.
- Try a trivial project to see if the problem is something about your project or if it’s something about DDEV and your environment. See the simple instructions at [ddev/trivial-project](<https://github.com/ddev/trivial-project>).
- Temporarily disable firewalls, VPNs, tunnels, network proxies, and virus checkers while you’re troubleshooting.
- Temporarily disable any proxies you’ve established in Docker’s settings.
- Check to see if you’re out of disk space. On macOS, make sure that your Docker provider has adequate disk space allocated. (DDEV will normally warn you about problems in this situation.)
- On macOS, if you have a particular heavyweight project or are encountering `kill` statements in `ddev logs`, increase your memory allocation in your Docker provider. (Most projects are fine with 5-6GB allocated.)
- On macOS your Docker provider limits the amount of disk space available to Docker. Make sure that you increase it if you’re seeing disk space problems.
- Please make sure that your project is in a subdirectory of your home directory and has normal ownership and privileges. For example, `ls -ld .` in your project directory should show you as owner of the directory and with write privileges.
- Use [`ddev utility dockercheck`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-dockercheck>) and [`ddev utility test`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-test>) to help sort out Docker problems.
- Make sure you do not have disk space problems on your computer. This can be especially tricky on WSL2, where you need to check both the main Windows disk space and WSL2 disk space as well.
- On macOS, check to make sure your Docker provider is not out of disk space. In *Settings* (or *Preferences*) → *Resources* → *Disk image size* there should be ample space left; try not to let usage exceed 80% because the reported number can be unreliable. If it says zero used, something is wrong.
- If you have customizations like PHP overrides, nginx or Apache overrides, MySQL/PostgreSQL overrides, custom services, or `config.yaml` changes, please back them out while troubleshooting, see [`ddev utility check-custom-config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-check-custom-config>). It’s important to have the simplest possible environment while troubleshooting.
- Restart Docker. Consider a Docker factory reset in serious cases, which will destroy any databases you’ve loaded. See [Docker Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#troubleshooting-docker>) for more.
- Try the simplest possible DDEV project (like [`ddev utility test`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-test>) does):

  ```
  ddev poweroff
  mkdir ~/tmp/testddev
  cd ~/tmp/testddev
  ddev config --auto
  printf "<?php\nphpinfo();\n" > index.php
  ddev start
  ```

  If that starts up fine, there may be an issue specifically with the project you’re trying to start.

> [!TIP]
>
> **Using DDEV with Other Development Environments**
>
> DDEV uses your system’s port 80 and 443 by default when projects are running. If you’re using another local development environment (like Lando or Docksal or a native setup), you can either stop the other environment or configure DDEV to use different ports. See [troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#unable-listen>) for more detailed problem-solving. It’s easiest to stop the other environment when you want to use DDEV, and stop DDEV when you want to use the other environment.

### Debug Environment Variables

Two environment variables meant for DDEV development may also be useful for broader troubleshooting: `DDEV_DEBUG` and `DDEV_VERBOSE`. When enabled, they’ll output more information when DDEV is executing a command. `DDEV_VERBOSE` can be particularly helpful debugging Dockerfile problems because it outputs complete information about the Dockerfile build stage within the `ddev start` command.

You can set either one in your current session by running `export DDEV_DEBUG=true` and `export DDEV_VERBOSE=true`.

Logs from a container that fails to start are printed with `DDEV_DEBUG=true` or `CI=true`.

## Front-End Development Tools

### Vite Issues

If you’re experiencing issues with Vite development servers (like “Bad Gateway” errors, CORS problems, or HMR not working), see the comprehensive [Vite Integration troubleshooting section](<https://ddev.github.io/ddev/en/stable/users/usage/vite/#troubleshooting>) which covers:

- Configuration of `web_extra_exposed_ports`
- CORS and origin settings
- Port conflicts and HMR issues
- Asset loading problems

## Web Server Ports Already Occupied

On `ddev start` you may see a message like this:

```
Port 443 is not available, using 30001 instead, see https://ddev.com/s/port-conflict
```

This means that DDEV has detected that it can’t use the expected port (`443`) in this example, usually because another application is using it. (It can also mean the port was occupied when the `ddev-router` container was created, and DDEV keeps using the substitute port until the router is recreated, for example by `ddev poweroff && ddev start`.) If this is OK, you don’t need to take any action. Most users want to use the default ports though (`80` and `443`) so you may want to figure out what the conflict is and solve it (usually by stopping the competing application).

`ddev utility port-diagnose`, run from your project directory, can likely explain what’s going on. It checks each port your project needs, identifies the blocking process by name and PID, and suggests how to stop it:

```
$ ddev utility port-diagnose
Port diagnostics for project: my-project
Port 80 (router HTTP): IN USE by apache2 (PID 1234, cmd=/usr/sbin/apache2 -k start) [Linux]
  sudo systemctl stop apache2 && sudo systemctl disable apache2
Port 443 (router HTTPS): Available
```

On WSL2, it checks both Linux/WSL2 and Windows. If a port conflict is held by a root-owned process (such as `docker-proxy` under rootful Docker CE), the tool will ask for permission before running any `sudo` command, showing the exact command it intends to run. You can pre-approve this with `--allow-sudo`:

```
ddev utility port-diagnose --allow-sudo
```

The `--allow-sudo` flag is useful in scripts or when you know elevated detection will be needed and want to avoid the interactive prompt. When running non-interactively (CI, pipes) without `--allow-sudo`, sudo escalation is skipped.

If port-diagnose doesn’t resolve it, the methods below explain how to stop the competing application or configure DDEV to use different ports.

If you do get messages like:

> ERROR: for ddev-router Cannot start service ddev-router: Ports are not available: listen tcp 127.0.0.1:XX: bind: An attempt was made to access a socket in a way forbidden by its access permissions.

or

> Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:8025 -\> 0.0.0.0:0: listen tcp 127.0.0.1:8025: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

it means some other process is using a needed port. Stop all Docker containers that might be using the port by running `ddev poweroff && docker rm -f $(docker ps -aq)`, then restart Docker.

### Method 1: Stop the competing application

Consider `lando poweroff` for Lando, or `fin system stop` for Docksal, or stop MAMP using GUI interface or [`stop.sh`](<https://stackoverflow.com/a/17750194/215713>).

Probably the most common conflicting application is Apache running locally. It can often be stopped gracefully (but temporarily) with:

```
sudo apachectl stop
```

or

```
sudo systemctl stop apache2 && sudo systemctl disable apache2
```

**Common tools that use port 80 and port 443:**

Most people will want to use ports 80 and 443, the default HTTP and HTTPS ports for their projects, and these work fine whenever some other process is not using them. All of the DDEV projects on a given computer can use ports 80 and 443 at the same time. However, if you are not getting the default ports, here are some of the other common processes that could be using ports 80/443 and methods to stop them.

- macOS content filtering: Under “Screen Time” → “Choose Screen Time content and privacy settings”, turn off “Content and Privacy” and then reboot. This has been a common issue with macOS Sonoma.
- macOS or Linux Homebrew: Look for active processes by running `brew services` and temporarily running `brew services stop` individually to see if it has any impact on the conflict.
- MAMP (macOS): Stop MAMP.
- Apache: Temporarily stop with `sudo apachectl stop`, permanent stop depends on your environment. On Debian/Ubuntu: `sudo systemctl disable apache2 && sudo systemctl stop apache2`
- nginx (macOS Homebrew): `sudo brew services stop nginx` or `sudo launchctl stop homebrew.mxcl.nginx`.
- nginx (Ubuntu): `sudo systemctl stop nginx` or `sudo service nginx stop`.
- VPNKit (macOS): You likely have a Docker container bound to port 80. Do you have containers up for Lando or another Docker-based development environment? If so, stop the other environment.
- Lando: If you’ve previously used Lando, try running `lando poweroff`.
- IIS on Windows (can affect WSL2). You’ll have to disable it in the Windows settings.

You can also probe a port with `curl` to get a hint about which application is responding: `curl -I localhost` or `curl -I -k https://localhost:443`.

### Method 2: Fix port conflicts by configuring your project to use different ports

To configure DDEV to use non-conflicting ports, remove router port configuration from the project and set it globally to different values. This will work for most people:

```
ddev config global --router-http-port=8080 --router-https-port=8443
ddev config --router-http-port="" --router-https-port=""
ddev restart
```

This changes all projects’ HTTP URLs to `http://yoursite.ddev.site:8080` and the HTTPS URLs to `https://yoursite.ddev.site:8443`.

We welcome your [suggestions](<https://github.com/ddev/ddev/issues/new>) based on other issues you’ve run into and your troubleshooting technique.

### Security Software Interfering with Port Detection

If you see messages like:

```
Unable to check port availability
Assuming ports are available, see https://ddev.com/s/port-conflict
```

DDEV will rely on Docker to report actual port conflicts. This can happen when security software intercepts localhost traffic.

### Debugging Port Issues on WSL2

On WSL2 the port may be occupied either on the traditional Windows side or within the WSL2 distro. `ddev utility port-diagnose` checks both sides automatically. The ports are shared between Windows and WSL2, so a conflict on either side blocks DDEV.

## Database Container Fails to Start

Use `ddev logs -s db` to see what’s wrong.

The most common cause of the database container not coming up is changing the database type or version in the project configuration, so the database server daemon is unable to start using an existing configuration for a different type or version.

To solve this:

- Change the configuration in `.ddev/config.yaml` back to the original configuration.
- Export the database with [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>).
- Delete the project with [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>), or remove just the database volume with [`ddev utility delete-volume database`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-delete-volume>), which stops the project first if it’s running.
- Update `.ddev/config.yaml` to use the new [database type or version](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/index.md>).
- Start the project and import the database from your export.

## “web service unhealthy” or “web service starting” or Exited

Use `ddev logs` to see what’s wrong.

The most common cause of the web container being unhealthy is a user-defined `.ddev/nginx-full/nginx-site.conf` or `.ddev/apache/apache-site.conf`. Please rename these to `<xxx_site.conf>` during testing. To figure out what’s wrong with it after you’ve identified that as the problem, use `ddev logs` and review the error.

Changes to `.ddev/nginx-site.conf` and `.ddev/apache/apache-site.conf` take effect only when you do a `ddev restart` or the equivalent.

## No Input File Specified (404) or Forbidden (403)

If you get a 404 with “No input file specified” (nginx) or a 403 with “Forbidden” (Apache) when you visit your project, it usually means that no `index.php` or `index.html` is being found in the docroot. This can result from:

- Misconfigured docroot: If the docroot isn’t where the web server thinks it is, then the web server won’t find `index.php`. Look at your `.ddev/config.yaml` to verify it has a docroot containing `index.php`. It should be a relative path.
- Missing `index.php`: There may not be an `index.php` or `index.html` in your project.

`ddev logs` shows the exact reason the web server gave for a 403. To browse a directory that has no index file at all, turn directory listing on yourself, with `Options +Indexes` in an `.htaccess` file (Apache) or `autoindex on;` in a `.ddev/nginx/*.conf` file (nginx).

## `ddev start` Fails and Logs Contain “failed (28: No space left on device)” - Docker File Space

If `ddev start` fails, it’s most often because the `web` or `db` container fails to start. In this case, the error message from `ddev start` says something like “Failed to start : db container failed: log=, err=container exited, please use ‘ddev logs -s db’ to find out why it failed”. You can`ddev logs -s db` to find out what happened.

If you see any variant of “no space left on device” in the logs when using Docker Desktop, it means you have to increase or clean up Docker’s file space. Increase the “Disk image size” setting under “Resources” in Docker’s Preferences:

![Docker disk space](<https://ddev.github.io/ddev/en/stable/images/docker-disk-image-size.png>)

If you see “no space left on device” on Linux, it most likely means your filesystem is full.

## `ddev start` Fails with “container failed to become ready”

A container fails to become ready when its health check is failing. This can happen to any of the containers, and you can usually find the issue with a `docker inspect` command.

> [!TIP]
>
> You may need to install [jq](<https://stedolan.github.io/jq/download/>) for these examples (`brew install jq`), or remove the `| jq` from the command and read the raw JSON output.

For the `web` container:

```
docker inspect --format "{{json .State.Health }}" ddev-<projectname>-web | jq
```

For `ddev-router`:

```
docker inspect --format "{{json .State.Health }}" ddev-router
```

For `ddev-ssh-agent`:

```
docker inspect --format "{{json .State.Health }}" ddev-ssh-agent
```

Don’t forget to check logs using `ddev logs` for the `web` container, and `ddev logs -s db` for the `db` container!

For `ddev-router` and `ddev-ssh-agent`: `docker logs ddev-router` and `docker logs ddev-ssh-agent`.

## `ddev start` Fails with “Failed to start \[project name\]: No such container: ddev-router”

Deleting the images and re-pulling them generally solves this problem.

Try running the following commands from the host machine:

```
ddev poweroff
docker rm -f $(docker ps -aq)
docker rmi -f $(docker images -q)
```

You should then be able to start your DDEV machine.

## Waiting for Another DDEV Process

DDEV commands take turns while they set up what all projects share: the `ddev-router`, the `ddev-ssh-agent`, and the `ddev_default` network. If another `ddev` command is in the middle of that, you’ll see something like:

```
Waiting for 'ddev start' in ~/workspace/d11 (pid 41233, running 3s), which is doing ddev-router setup. Press Ctrl-C to cancel.
```

This usually clears within seconds. The other command may be running in another terminal, an IDE integration, a script, or a hook.

If it doesn’t clear:

- Look at the process with `ps -p 41233` (on Windows, `tasklist /fi "PID eq 41233"`), and stop it if it’s stuck.
- Press Ctrl-C to cancel the waiting command; that is safe.
- After two minutes DDEV gives up waiting and continues anyway, warning that the two commands may conflict, and doesn’t wait on that process again for the rest of the command. If something then fails, run `ddev poweroff` and try again.

The lock is the file `~/.ddev/.global.lock`, which the operating system releases when the process holding it exits, so you never need to delete it.

## `ddev --version` shows an old version

If you have installed or upgraded DDEV to the latest version, but when you check the actual version with `ddev --version`, it shows an older version, please refer to [Why do I have an old DDEV?](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-have-an-old-ddev>)

## Trouble Building Dockerfiles

The additional `.ddev/web-build/Dockerfile` capability in DDEV is wonderful, but it can be hard to figure out what to put in there.

The best approach for any significant Dockerfile is to `ddev ssh` and `sudo -s` and then one at a time, do the things that you plan to do with a `RUN` command in the Dockerfile.

For example, if your Dockerfile were

```
RUN npm install --global forever
```

You could test it with `ddev ssh`, `sudo -s`, and then `npm install --global forever`.

The error messages you get will be more informative than messages that come when the Dockerfile is processed.

You can also see the output from the full Docker build using either:

```
ddev utility rebuild
```

or (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>) for `docker-compose` location):

```
$HOME/.ddev/bin/docker-compose -f .ddev/.ddev-docker-compose-full.yaml --progress=plain build --no-cache
```

### Docker build fails `apt-get update`, perhaps “SSL certificate problem: self-signed certificate”

The Docker build environment (where all projects have a little bit happening) is very sensitive to problems with `apt-get update` or with TLS certificate authentication. If you ware seeing problems with `apt-get update` failing, some of these strategies may help:

- **WSL2**: On WSL2 it’s a known issue that the WSL2 environment time can get out of sync with the real time. This is an [ongoing problem](<https://github.com/microsoft/WSL/issues/10006>) with WSL2, and can be fixed with various workarounds. One good workaround is to install `ntpdate` and `sudo ntpdate pool.ntp.org` to sync the time. The time in WSL2 can get out of sync due to laptop sleeping or other causes. A reboot also fixes it.
- **VPN**: If you are on a packet-inspection VPN, it often causes problems with validation of certificates on internet sites. In that situation you’ll need to get the CA updates required and install them with a custom Dockerfile, as described on [Stack Overflow](<https://stackoverflow.com/questions/71595327/corporate-network-ddev-composer-create-results-in-ssl-certificate-error/71595428#71595428>).
- **Other Docker Build**: The Dockerfile build environment is different from the host-side build and different from what you get with `ddev ssh`. If you’re having trouble with it it may be caused by name resolution or IP connectivity problems, most often caused by a firewall or VPN. Turn off your firewall temporarily and VPN. A good debugging technique would be to do a simple `.ddev/web-build/Dockerfile` that does `RUN curl -I https://www.google.com` and then use `ddev utility rebuild` to see the result. If it gets a 200 result, then your name resolution and internet connectivity are working in the Docker build environment.

## DDEV Starts but Browser Can’t Access URL

You may see one of these messages in your browser:

- `403` Forbidden
- *\[url\] server IP address could not be found*
- *We can’t connect to the server at \[url\]*

If you get the `403 Forbidden` it’s almost always because your [docroot is set wrong](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#why-do-i-get-a-403-or-404-on-my-project-after-ddev-launch>). You should have something like `docroot: web` or `docroot: ""` or `docroot: docroot` with the relative path to the directory where your `index.php` lives in the project.

**Name resolution**: Most people use `*.ddev.site` URLs, which work great most of the time but require internet access.

`*.ddev.site` is a wildcard DNS entry that always returns the IP address 127.0.0.1 (localhost). If you’re not connected to the internet, however, or if various other name resolution issues fail, this name resolution won’t work.

While DDEV can create a web server and a Docker network infrastructure for a project, it doesn’t have control of your computer’s name resolution, so its backup technique to make a hostname resolvable by the browser is to add an entry to the hosts file (`/etc/hosts` on Linux and macOS, `C:\Windows\system32\drivers\etc\hosts` on traditional Windows).

- If you’re not connected to the internet, your browser will not be able to look up `*.ddev.site` hostnames. DDEV works fine offline, but for your browser to look up names they’ll have to be resolved in a different way.
- DDEV assumes that hostnames can be resolved within 3 seconds. That assumption is not valid on all networks or computers, so you can increase the amount of time it waits for resolution. Increasing to 5 seconds, for example: `ddev config global --internet-detection-timeout-ms=5000`.
- If DDEV detects that it can’t look up one of the hostnames assigned to your project for that or other reasons, it will try to add that to the hosts file on your computer, which requires administrative privileges (sudo or Windows UAC).

  - This technique may not work on Windows WSL2, see below.

### Router Ports Not Reachable

If `ddev start` warns that nothing answers on the router’s host ports, the router is running but your Docker provider isn’t forwarding its ports to your computer. Restarting the Docker provider often fixes it.

With Lima or Colima on Linux, ports below 1024, such as 80 and 443, can’t be forwarded unless your system allows it. Either allow them with `echo 'net.ipv4.ip_unprivileged_port_start=0' | sudo tee -a /etc/sysctl.d/60-rootless.conf && sudo sysctl --system` and restart Lima or Colima, or move the router to higher ports with `ddev config global --router-http-port=8080 --router-https-port=8443`.

### DNS Rebinding Prohibited (Mostly on Fritzbox Routers)

You may see one of several messages:

- *Cannot resolve*
- *unknown host*
- *No address associated with hostname*

Some DNS servers prevent the use of DNS records that resolve to `localhost` (127.0.0.1) because in uncontrolled environments this may be used as a form of attack called [DNS Rebinding](<https://en.wikipedia.org/wiki/DNS_rebinding>). Since `*.ddev.site` resolves to 127.0.0.1, they may refuse to resolve, and your browser may be unable to look up a hostname, and give you messages like “ server IP address could not be found” or “We can’t connect to the server at ”.

You verify this is your problem by running `ping -c 1 dkkd.ddev.site`. If you get “No address associated with hostname” or something of that type, your computer is unable to look up `*.ddev.site`.

In this case, you can take any one of the following approaches:

1. Reconfigure your router to allow DNS Rebinding. Many Fritz!Box routers have added default DNS Rebinding disallowal, and they can be reconfigured to allow it. Easy instructions are at [Fritz!Box Routers and DDEV](<https://ddev.com/blog/fritzbox-routers-and-ddev/>). If you have the local dnsmasq DNS server it may also be configured to disallow DNS rebinding, but it’s a simple change to a configuration directive to allow it.
2. Most computers can use more relaxed DNS resolution if they are not on corporate intranets that have non-internet DNS. So for example, the computer can be set to use 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare) for DNS name resolution, see [this article](<https://support.perimeter81.com/docs/change-your-pc-dns-settings>).
3. If you have control of the router, you can usually change its DHCP settings to choose a public, relaxed DNS server as in [\#2](<https://github.com/ddev/ddev/issues/2> "GitHub Issue: ddev/ddev #2").
4. You can live with DDEV trying to edit the `/etc/hosts` file, which it only has to do when a new name is added to a project.

An extensive discussion of this class of problem is on [ddev.com](<https://ddev.com/blog/ddev-name-resolution-wildcards>).

## Browser Shows Certificate Error for DDEV Sites

If your browser shows a certificate warning such as `NET::ERR_CERT_AUTHORITY_INVALID`, `SEC_ERROR_UNKNOWN_ISSUER`, or “Your connection is not private” when visiting a DDEV HTTPS URL, the mkcert certificate authority (CA) is not trusted by your browser or OS.

Run [`ddev utility tls-diagnose`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-tls-diagnose>) to identify the specific problem:

```
ddev utility tls-diagnose
```

The command checks mkcert installation, OS trust store, certificate files, and live HTTPS connectivity, and prints actionable fix instructions for each issue it finds.

**Common causes and fixes:**

- **mkcert CA not installed in OS trust store** — Run `mkcert -install` and restart your browser.
- **Firefox on Windows** — Firefox on Windows does not use the Windows certificate store. You must import the mkcert CA manually: Firefox Settings → Privacy &amp; Security → View Certificates → Authorities → Import. Select `rootCA.pem` from the path shown by `mkcert -CAROOT`. Firefox Nightly, Developer Edition, and ESR each maintain a separate trust store and need the same treatment. On macOS and Linux, standard Firefox works via the OS trust store after `mkcert -install`; only special builds (Flatpak, snap, Nightly, Developer Edition) may need a manual import.
- **Linux: `certutil` not installed** — Firefox on Linux relies on `certutil` (from `libnss3-tools`) for `mkcert -install` to register the CA. Install it with `sudo apt install libnss3-tools` (or `brew install nss`), then run `mkcert -install` again.
- **Expired or CA-rotated certificates** — Run `ddev poweroff && ddev start` to regenerate certificates, or the nuclear option: `ddev poweroff && mkcert -uninstall && rm -rf "$(mkcert -CAROOT)" && mkcert -install && ddev start`.

**On WSL2:** The mkcert CA is installed on Windows using `mkcert -install` in PowerShell. WSL2 then points its `$CAROOT` at the Windows mkcert directory so both sides use the same CA. `ddev utility tls-diagnose` checks all the WSL2-specific requirements:

- `$CAROOT` must point to the Windows mkcert directory (e.g. `/mnt/c/Users/<user>/AppData/Local/mkcert`)
- `CAROOT` must be listed in `$WSLENV` so it propagates into WSL2 sessions
- The mkcert CA must be installed in the Windows certificate store (via `mkcert -install` in PowerShell)

If any of these are missing, follow the setup instructions in [WSL2 and Certificates](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/index.md>).

## Windows WSL2 Network Issues

- If you’re using a browser on Windows, accessing a project in WSL2, you can end up with confusing results when your project is listening on a port inside WSL2 while a Windows process is listening on that same port. The way to sort this out is to stop your project inside WSL2, verify that nothing is listening on the port there, and then study the port on the Windows side by visiting it with a browser or using other tools as described above.

## Limitations on Symbolic Links (symlinks)

Symbolic links are widely used but have specific limitations in many environments beyond DDEV. Here are some of the ways those may affect you:

- **Crossing mount boundaries**: Symlinks may not generally cross between network mounts. In other words, if you have a relative symlink in the root of your project directory on the host that points to `../somefile.txt`, that symlink will not be valid inside the container where `../` is a completely different filesystem (and is typically not mounted).
- **Symlinks to absolute paths**: If you have an absolute symlink to something like `/Users/xxx/somefile.txt` on the host, it will not be resolvable inside the container because `/Users` is not mounted there. Some tools, especially on Magento 2, may create symlinks to rooted paths, with targets like `/var/www/html/path/to/something`. These basically can’t make it to the host and may create errors.
- **Windows restrictions on symlinks**: Inside the Docker container on Windows, you may not be able to create a symlink that goes outside the container.
- **Mutagen restrictions on Windows symlinks**: On macOS and Linux (including WSL2) the default `.ddev/mutagen/mutagen.yml` chooses the `posix-raw` type of symlink handling. (See [Mutagen docs](<https://mutagen.io/documentation/synchronization/symbolic-links>)). This basically means that any symlink created will try to sync, regardless of whether it’s valid in the other environment. However, Mutagen does not support posix-raw on traditional Windows, so DDEV uses the `portable` symlink mode. So on Windows with Mutagen, symlinks have to be strictly limited to relative links that are inside the Mutagen section of the project.

### Delete and Re-Download Docker Images

In a few unusual cases, the actual downloaded Docker images can somehow get corrupted. Deleting the images will force them to be re-downloaded or rebuilt. This does no harm, as everything is rebuilt, but running `ddev start` will take longer while it downloads needed resources:

```
ddev poweroff
docker rm -f $(docker ps -aq) # Stop any other random containers that may be running
docker rmi -f $(docker images -q) # You might have to repeat this to get rid of all images
```

## “Your Docker install has only … available disk space”

Weird and bad things happen when Docker or your host system run out of disk space. Here are some ways to solve the problem if you get the warning “Your Docker install has only … available disk space”:

- **Everybody**: Often a `ddev delete images` and `docker builder prune` (or `docker buildx prune`) will free up plenty of space. Consider deleting all images with `docker rmi -f $(docker images -q)`; this does no damage, but the images will have to be re-downloaded.
- **macOS and traditional Windows**: `ddev mutagen reset` in each project will free up space.
- **Docker Desktop for Mac** allocates a specific amount of docker-related space, and you can increase it. Settings -\> Resources -\> Disk usage limit.
- **Colima, Lima, Rancher Desktop**: Before changing anything, save away your databases with `ddev snapshot -a`. Then follow instructions in each of those projects to increase allocated disk space. If you have your databases saved, you can delete your current instance and recreate with new disk constraints, see [Docker Installation](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>).
- **OrbStack and Linux including WSL2 with Docker CE**: You are probably out of disk space on the disk where Docker stores images and volumes.

# Uninstalling DDEV

A DDEV installation consists of:

- The self-contained `ddev` binary.
- Each project’s `.ddev` directory.
- The global `$HOME/.ddev` directory where various global items are stored. (This directory can be [moved](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>) to another location.)
- The global `$HOME/.ddev_mutagen_data_directory` directory where Mutagen sync data may be stored.
- The associated Docker images, containers and volumes DDEV created.
- Any entries in `/etc/hosts`.

Please use [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) or [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>) to make backups of your databases before deleting projects or uninstalling.

You can use [`ddev clean`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#clean>) to uninstall the vast majority of things DDEV has touched. For example, `ddev clean <project>` or `ddev clean --all`.

To uninstall one project, run [`ddev delete <project>`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>). This removes any hostnames in `/etc/hosts` and removes your database. If you don’t want it to make a database backup/snapshot on the way down, include the `--omit-snapshot` option: `ddev delete --omit-snapshot <project>`.

To remove all DDEV-owned `/etc/hosts` entries: [`ddev hostname --remove-inactive`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#hostname>).

To remove the global `.ddev` directory: `rm -r $HOME/.ddev`.

To remove the global `.ddev_mutagen_data_directory` directory: `ddev poweroff && rm -r $HOME/.ddev_mutagen_data_directory`.

If you installed Docker only for DDEV and want to uninstall it with all containers and images, uninstall it for your version of Docker.

Otherwise:

- Remove Docker images from before the current DDEV release with [`ddev delete images`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete-images>).
- Remove all DDEV Docker containers that might still exist: `docker rm $(docker ps -a | awk '/ddev/ { print $1 }')`.
- Remove all DDEV Docker images that might exist: `docker rmi $(docker images | awk '/ddev/ {print $3}')`.
- Remove all Docker images of any type (does no harm; they’ll be re-downloaded): `docker rmi -f $(docker images -q)`.
- Remove any Docker volumes: `docker volume rm $(docker volume ls | awk '/ddev|-mariadb/ { print $2 }')`.

To remove the `ddev` binary:

- Find the binary location with `which -a ddev`, you may have several binaries installed in different ways. The output will give you a general idea of how you installed it.
- On macOS or Linux with Homebrew, `brew uninstall ddev`.
- For Linux or other simple installs, remove the binary. Example: `sudo rm /usr/local/bin/ddev`. For Linux installed via apt, `sudo apt-get remove ddev`.
- On Windows, if you used the DDEV Windows installer, use the uninstall on the Start Menu or in the “Add or Remove Programs” section of Windows Settings.

# Vite Integration

[Vite](<https://vitejs.dev/>) is a popular front-end build tool that provides fast development server with Hot Module Replacement (HMR) and optimized production builds. DDEV supports Vite development workflows for various frameworks including Laravel, Vue.js, React, Svelte, and more.

## Quick Setup

To use Vite with DDEV, you need to:

1. Configure DDEV to expose Vite’s port in `.ddev/config.yaml`:

   ```
   web_extra_exposed_ports:
     - name: vite
       container_port: 5173
       http_port: 5172
       https_port: 5173
   ```
2. Configure Vite in your `vite.config.js`:

   ```
   import { defineConfig } from 'vite'

   export default defineConfig({
     // Your settings
     // ...

     // Adjust Vites dev server to work with DDEV
     // https://vitejs.dev/config/server-options.html
     server: {
       // Respond to all network requests
       host: "0.0.0.0",
       port: 5173,
       strictPort: true,
       // Defines the origin of the generated asset URLs during development,
       // this must be set to the Vite dev server URL and selected port.
       origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
       // Configure CORS securely for the Vite dev server to allow requests
       // from *.ddev.site domains, supports additional hostnames (via regex).
       // If you use another `project_tld`, adjust this value accordingly.
       cors: {
         origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
       },
     },
   })
   ```
3. Restart DDEV to apply configuration changes:

   ```
   ddev restart
   ```
4. Start Vite development server:

   ```
   ddev npm run dev
   # or
   ddev yarn dev
   ```

Your Vite development server will be available at `https://yourproject.ddev.site:5173`.

> [!NOTE]
>
> **HTTPS Configuration**
>
> This guide assumes your project runs on `https://`. If you are unable to access the HTTPS version of your project, refer to the [Configuring Browsers](<https://ddev.github.io/ddev/en/stable/users/install/configuring-browsers/index.md>).

> [!TIP]
>
> **Custom TLD**
>
> If you use a custom [`project_tld`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#project_tld>) other than `ddev.site`, adjust the CORS configuration accordingly in your `vite.config.js`, or use this snippet:
>
> ```
> export default defineConfig({
>   server: {
>     cors: {
>       origin: new RegExp(
>         `https?:\/\/(${process.env.DDEV_HOSTNAME.split(",")
>           .map((h) => h.replace("*", "[^.]+"))
>           .join("|")})(?::\\d+)?$`
>       )
>     },
>   },
> });
> ```

## Example Projects

Example implementations demonstrating Vite integration with DDEV:

- **[Working with Vite in DDEV](<https://ddev.com/blog/working-with-vite-in-ddev/>)** - Basic PHP project with step-by-step setup guide
- **[vite-php-setup](<https://github.com/andrefelipe/vite-php-setup>)** - General PHP + Vite integration (adapt `VITE_HOST` for DDEV)

For additional integration patterns and framework-specific examples:

- **[Vite Backend Integration Guide](<https://vitejs.dev/guide/backend-integration.html>)** - Official Vite documentation for backend frameworks
- **[Vite Awesome List](<https://github.com/vitejs/awesome-vite#integrations-with-backends>)** - Community-maintained list of integrations

## Craft CMS

The [Vite plugin by `nystudio107`](<https://nystudio107.com/docs/vite/>) provides official DDEV support with detailed [configuration instructions](<https://nystudio107.com/docs/vite/#using-ddev>) for `vite.config.js` and `config/vite.php`.

> [!NOTE]
>
> **Port Configuration**
>
> When using `web_extra_exposed_ports` in `.ddev/config.yaml`, the `.ddev/docker-compose.*.yaml` file for port exposure is not required.

Example implementations:

- **[Craft CMS with Vite integration](<https://github.com/mandrasch/ddev-craftcms-vite>)**
- **[Craft CMS Starter](<https://github.com/vigetlabs/craft-site-starter>)**
- **[How we use DDEV, Vite and Tailwind with Craft CMS](<https://www.viget.com/articles/how-we-use-ddev-vite-and-tailwind-with-craft-cms/>)**

## Drupal

Several tools and modules are available for integrating Vite with Drupal:

- **[Vite module](<https://www.drupal.org/project/vite>)** - Uses Vite’s manifest.json to map Drupal library files to compiled versions in `/dist` or to the Vite development server
- **[UnoCSS Starter theme](<https://www.drupal.org/project/unocss_starter>)** - Drupal theme with Vite integration and DDEV setup instructions
- **[Foxy](<https://www.drupal.org/project/foxy>)** - Alternative asset bundling solution for Drupal

Community resources:

- **[UnoCSS Starter Theme Documentation](<https://www.drupalarchitect.info/projects/unocss-starter-theme>)**
- **[Proof of concept for Vite bundling in Drupal](<https://github.com/darvanen/drupal-js>)**

The Drupal community is actively developing Vite integration solutions for bundling assets across multiple modules and themes.

## Laravel

Laravel adopted [Vite as the default asset bundler](<https://laravel-news.com/vite-is-the-default-frontend-asset-bundler-for-laravel-applications>) in v9.19, replacing Laravel Mix.

Configure DDEV to expose Vite’s port in `.ddev/config.yaml`:

```
web_extra_exposed_ports:
  - name: vite
    container_port: 5173
    http_port: 5172
    https_port: 5173
```

Configure Vite in your `vite.config.js`:

```
import { defineConfig } from 'vite';
import laravel from 'laravel-vite-plugin';

export default defineConfig({
  plugins: [
    laravel({
      input: [
        'resources/css/app.css',
        'resources/js/app.js',
      ],
      refresh: true,
    }),
  ],
  server: {
    host: "0.0.0.0",
    port: 5173,
    strictPort: true,
    origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
    cors: {
      origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
    },
  },
});
```

Start the Vite development server:

```
ddev npm run dev
```

Example implementation:

- **[ddev-laravel-vite](<https://github.com/mandrasch/ddev-laravel-vite>)** - Laravel with Vite integration

> [!NOTE]
>
> **Laravel-Specific Integration**
>
> Laravel’s Vite integration uses a `public/hot` file to manage development server state through its npm integration.

## Node.js

DDEV supports Node.js-only projects by proxying requests to the correct ports within the web container. This configuration enables running Node.js applications like Keystone CMS or SvelteKit entirely within DDEV.

This approach supports various architectures:

- **Monorepo setup**: Run a PHP backend with a Node.js frontend on separate subdomains within a single DDEV project
- **Headless CMS**: Ideal for decoupled architectures combining traditional backends with modern JavaScript frameworks
- **Multi-project setup**: Use separate DDEV projects for frontend and backend with [inter-project communication](<https://ddev.github.io/ddev/en/stable/users/usage/managing-projects/#inter-project-communication>)

Additional resources:

- **[How to Run Headless Drupal and Next.js on DDEV](<https://www.velir.com/ideas/2024/05/13/how-to-run-headless-drupal-and-nextjs-on-ddev>)** - Headless CMS implementation guide
- **[ddev-laravel-breeze-sveltekit](<https://github.com/mandrasch/ddev-laravel-breeze-sveltekit>)** - Monorepo example with Laravel and SvelteKit

## TYPO3

Several tools are available for integrating Vite with TYPO3:

- **[typo3-vite-demo](<https://github.com/fgeierst/typo3-vite-demo>)** - Vite demo project
- **[vite-asset-collector](<https://github.com/s2b/vite-asset-collector>)** - TYPO3 extension for Vite integration
- **[vite-plugin-typo3](<https://github.com/s2b/vite-plugin-typo3>)** - Vite plugin for TYPO3
- **[ddev-vite-sidecar](<https://github.com/s2b/ddev-vite-sidecar>)** - DDEV add-on for zero-config Vite integration

The vite-asset-collector extension provides detailed [DDEV installation instructions](<https://docs.typo3.org/p/praetorius/vite-asset-collector/main/en-us/Installation/Index.html#installation-1>). For questions or support, join the Vite channel on [TYPO3 Slack](<https://typo3.community/meet/slack>).

## WordPress

Several libraries are available for integrating Vite with WordPress:

- **[php-wordpress-vite-assets](<https://github.com/idleberg/php-wordpress-vite-assets>)** - PHP library for loading Vite assets in WordPress
- **[vite-for-wp](<https://github.com/kucrut/vite-for-wp>)** - WordPress integration for Vite
- **[wp-vite-manifest](<https://github.com/iamntz/wp-vite-manifest>)** - Vite manifest loader for WordPress

Example implementations:

- **[ddev-wp-vite-demo](<https://github.com/mandrasch/ddev-wp-vite-demo>)** - Demo theme using php-wordpress-vite-assets
- **[wp-vite-manifest usage guide](<https://github.com/iamntz/wp-vite-manifest/wiki/How-to-use-inside-your-WP-plugin-theme#usage>)** - Integration guide for themes and plugins
- **[Integrating Vite and DDEV into WordPress](<https://www.viget.com/articles/integrating-vite-and-ddev-into-wordpress/>)**

## GitHub Codespaces

DDEV supports Vite in GitHub Codespaces with alternative port configuration. Example implementations:

- **[Laravel with Vite in Codespaces](<https://github.com/mandrasch/ddev-laravel-vite>)**
- **[Craft CMS with Vite in Codespaces](<https://github.com/mandrasch/ddev-craftcms-vite>)**

> [!NOTE]
>
> **Alternative Port Configuration Required**
>
> The DDEV router is unavailable in Codespaces. Instead of using `web_extra_exposed_ports` in `.ddev/config.yaml`, create a `.ddev/docker-compose.vite-workaround.yaml` file:
>
> ```
> services:
>   web:
>     ports:
>       - 5173:5173
> ```

For additional Codespaces configuration details, see the [DDEV Codespaces documentation](<https://ddev.github.io/ddev/en/stable/users/install/ddev-installation/#github-codespaces>).

## Auto-starting Vite

You can configure DDEV to automatically start Vite when the project starts using [hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>):

Add to `.ddev/config.yaml`:

```
hooks:
  post-start:
    - exec: "npm run dev"
```

Or use a more robust daemon configuration (logs available via `ddev logs -s web`):

```
web_extra_daemons:
  - name: "vite"
    command: bash -c 'npm install && npm run dev -- --host'
    directory: /var/www/html
```

For a real-world daemon implementation example, see the [ddev.com repository](<https://github.com/ddev/ddev.com>) configuration.

## Production Builds

For production builds, ensure your `vite.config.js` includes proper manifest generation:

```
export default defineConfig({
  build: {
    manifest: true,
    rollupOptions: {
      input: {
        main: 'path/to/your/main.js',
      }
    }
  },
  // ... other configuration
})
```

Build for production:

```
ddev npm run build
```

## DDEV Add-ons

Several community add-ons simplify Vite integration:

- **[ddev-vite-sidecar](<https://github.com/s2b/ddev-vite-sidecar>)** - Zero-config Vite integration exposing the development server as a `https://vite.*` subdomain, eliminating the need to expose ports to the host system
- **[ddev-vitest](<https://github.com/tyler36/ddev-vitest>)** - Helper commands for projects using [Vitest](<https://vitest.dev/>), a Vite-native testing framework
- **[ddev-viteserve](<https://github.com/torenware/ddev-viteserve>)** - First DDEV Vite add-on (no longer maintained, but pioneered the integration)

Additional Vite-related add-ons are available in the [DDEV Add-on Registry](<https://addons.ddev.com>).

## Troubleshooting

### Bad Gateway Errors

**Problem**: Getting “502 Bad Gateway” when accessing Vite URL.

**Solutions**:

1. **Check port configuration**: Ensure `web_extra_exposed_ports` is correctly configured in `.ddev/config.yaml`.
2. **Verify Vite is running**: Check if Vite development server is actually running:

   ```
   ddev logs -s web
   ```
3. **Restart DDEV**: After changing configuration:

   ```
   ddev restart
   ```

### CORS Issues

**Problem**: Browser console shows CORS errors.

**Solutions**:

1. **Update CORS configuration** in `vite.config.js`:

   ```
   export default defineConfig({
     server: {
       cors: {
         origin: /https?:\/\/([A-Za-z0-9\-\.]+)?(\.ddev\.site)(?::\d+)?$/,
       },
     },
   });
   ```
2. **Check origin setting**:

   ```
   export default defineConfig({
     server: {
       origin: `${process.env.DDEV_PRIMARY_URL_WITHOUT_PORT}:5173`,
     },
   });
   ```

### Port Already in Use

**Problem**: “Port 5173 is already in use” error.

**Solutions**:

1. **Use different port**: Change the port in both DDEV and Vite configurations:

   ```
   # .ddev/config.yaml
   web_extra_exposed_ports:
     - name: vite
       container_port: 5174
       http_port: 5172
       https_port: 5174
   ```

   ```
   // vite.config.js
   export default defineConfig({
     server: {
       port: 5174,
     },
   });
   ```
2. **Kill existing process**:

   ```
   ddev exec "pkill -f vite"
   ```

### Assets Not Loading

**Problem**: CSS/JS assets not loading properly.

**Solutions**:

1. **Verify base path** in production builds matches your web server configuration.
2. **Check manifest.json** is being generated and loaded correctly.
3. **Ensure proper asset URLs** in your templates/framework integration.

## Best Practices

1. **Use specific Node.js versions**: Specify `nodejs_version` in your DDEV configuration for consistency across team members.
2. **Include Vite in your project dependencies**: Don’t rely on global Vite installations.
3. **Configure proper `.gitignore`**: Exclude build artifacts:

   ```
   /dist/
   /build/
   node_modules/
   ```
4. **Document your setup**: Include Vite configuration instructions in your project’s readme.
5. **Use environment variables**: Leverage `process.env.DDEV_PRIMARY_URL_WITHOUT_PORT` for dynamic configuration.

# Support

We love to hear from you and want you to be successful with DDEV!

- See the included [`ddev help`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#help>) command, which includes lots of examples.
- [FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/index.md>)
- [Discord](<https://ddev.com/s/discord>) interactive community support.
- [DDEV issue queue](<https://github.com/ddev/ddev/issues>) for bugs and feature requests.
- [Mastodon](<https://fosstodon.org/@ddev>)
- [Bluesky](<https://bsky.app/profile/ddev.bsky.social>)

# Code of Conduct

## Our Pledge

We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.

We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.

## Our Standards

Examples of behavior that contributes to a positive environment for our community include:

- Demonstrating empathy and kindness toward other people
- Being respectful of differing opinions, viewpoints, and experiences
- Giving and gracefully accepting constructive feedback
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
- Focusing on what is best not only for us as individuals, but for the overall community

Examples of unacceptable behavior include:

- The use of sexualized language or imagery, and sexual attention or advances of any kind
- Trolling, insulting or derogatory comments, and personal or political attacks
- Public or private harassment
- Publishing others’ private information, such as a physical or email address, without their explicit permission
- Other conduct which could reasonably be considered inappropriate in a professional setting

## Enforcement Responsibilities

Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.

Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.

## Scope

This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.

## Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at `support`(at)`ddev.com`. All complaints will be reviewed and investigated promptly and fairly.

All community leaders are obligated to respect the privacy and security of the reporter of any incident.

## Enforcement Guidelines

Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:

### 1\. Correction

**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.

**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.

### 2\. Warning

**Community Impact**: A violation through a single incident or series of actions.

**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.

### 3\. Temporary Ban

**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.

**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.

### 4\. Permanent Ban

**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.

**Consequence**: A permanent ban from any sort of public interaction within the community.

## Attribution

This Code of Conduct is adapted from the [Contributor Covenant](<https://www.contributor-covenant.org>), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code\_of\_conduct.html](<https://www.contributor-covenant.org/version/2/1/code_of_conduct.html>).

Community Impact Guidelines were inspired by [Mozilla’s code of conduct enforcement ladder](<https://github.com/mozilla/diversity>).

For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](<https://www.contributor-covenant.org/faq>). Translations are available at [https://www.contributor-covenant.org/translations](<https://www.contributor-covenant.org/translations>).

# Configuration

# Config Options

DDEV configuration is stored in YAML files that come in two flavors:

1. **Project** `.ddev/config.yaml` settings, with optional [environmental override](<#environmental-overrides>) variants.
2. **Global** `$HOME/.ddev/global_config.yaml` settings that can apply to all projects.

Most of these settings take effect when you run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).

## Managing Configuration

### Setting Options

You can hand-edit the YAML files DDEV creates for you after running [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>), and you can also define most settings with equivalent CLI arguments:

```
php_version: "8.4"
```

```
ddev config --php-version 8.4
```

Run `ddev help config` to see all the available config arguments.

### Environmental Overrides

You can override the per-project `config.yaml` with files named `config.*.yaml`, and files like this are often created by [DDEV add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>). For example, `config.python2.yaml` in [Python 2 add-on](<https://github.com/ddev/ddev-python2>) adds additional configuration related to Python 2.

Many teams use `config.local.yaml` for configuration that is specific to one environment, and not checked into the team’s default `config.yaml`. For example, you might enable `performance_mode: mutagen` only on your machine. Or you could use a different database type. The file `config.local.yaml` is gitignored by default.

The global `$HOME/.ddev/global_config.yaml` can be extended the same way with `global_config.*.yaml` files in `$HOME/.ddev`, which is useful for keeping machine-specific or team-distributed settings out of the file DDEV rewrites.

For examples, see the [Extending and Customizing Environments](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#extending-configyaml-with-custom-configyaml-files>) page.

---

## `additional_fqdns`

An array of [extra fully-qualified domain names](<https://ddev.github.io/ddev/en/stable/users/extend/additional-hostnames/index.md>) to be used for a project.

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

Example: `additional_fqdns: ["example.com", "sub1.example.com"]` would provide HTTP and HTTPS URLs for `example.com` and `sub1.example.com`.

See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) for more information on DDEV hostname resolution.

> [!WARNING]
>
> Take care with `additional_fqdns`; it adds items to your `/etc/hosts` file which can cause confusion.

## `additional_hostnames`

An array of [extra hostnames](<https://ddev.github.io/ddev/en/stable/users/extend/additional-hostnames/index.md>) to be used for a project.

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

Example: `additional_hostnames: ["somename", "someothername", "*.thirdname"]` would provide HTTP and HTTPS URLs for `somename.ddev.site`, `someothername.ddev.site`, and `one.thirdname.ddev.site` + `two.thirdname.ddev.site`.

The wildcard (`*.<whatever>`) setting only works if you’re [using DNS to resolve hostnames (default)](<#use_dns_when_possible>) and connected to the internet and using `ddev.site` as your [`project_tld`](<#project_tld>).

See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) for more information on DDEV hostname resolution.

## `bind_all_interfaces`

When the network interfaces of a project should be exposed to the local network, you can specify `bind_all_interfaces: true` to do that. This is an unusual application, sometimes used to [share projects on a local network](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#exposing-a-host-port-and-providing-a-direct-url>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. |

## `composer_root`

The relative path, from the project root, to the directory containing `composer.json`. (This is where all Composer-related commands are executed.)

| Type | Default | Usage |
| --- | --- | --- |
| project | ‌ | ‌ |

## `composer_version`

Composer version for the web container and the [`ddev composer`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project | `2` | Can be `2` or empty (`""`) for latest major version at container build time.<br><br>Can also be the LTS version `2.2` (there’s no other `2.x` LTS), an explicit version like `2.9.3`, or a keyword like `stable`, `preview` or `snapshot`. See [Composer documentation](<https://getcomposer.org/doc/03-cli.md#self-update-selfupdate>). |

> [!WARNING]
>
> **Composer version is cached at container build time**
>
> DDEV installs Composer at container build time and caches it. If you use a non-specific version like `2`, `2.2`, `""` (empty), or `stable`, DDEV installs the latest available version in that range at build time.
>
> The next update of Composer will be done automatically when DDEV is upgraded. If you want to update Composer in the web container before then, [restart](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) with `--no-cache` or [rebuild](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-rebuild>):
>
> ```
> ddev restart --no-cache
> # or
> ddev utility rebuild
> ```
>
> See [Composer Self-Update Changes Do Not Persist](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#composer-self-update-changes-do-not-persist>) for details.

> [!TIP]
>
> **Using `vendor/bin/composer`**
>
> See the example in [Composer from `vendor/bin/composer`](<https://ddev.github.io/ddev/en/stable/users/usage/developer-tools/#composer-from-vendorbincomposer>).

## `corepack_enable`

Whether to run `corepack enable` on Node.js configuration.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. |

When `true`, `corepack enable` will be executed, making latest `pnpm` and `yarn` package managers available.

Node.js 25 and later no longer include `corepack`. When it is missing, DDEV installs it from npm while building the web image, so that build needs access to the npm registry.

To set a specific version of `pnpm` for a project:

```
ddev config --corepack-enable && ddev restart
# pnpm@latest requires Node.js 22+
# use pnpm@latest-10 for Node.js 18 or 20
ddev exec corepack use pnpm@latest
ddev exec pnpm --version
```

To set a specific version of `yarn` for a project:

```
ddev config --corepack-enable && ddev restart
# yarn@stable is the latest stable release
# use yarn@4.9.1 to pin exactly
ddev exec corepack use yarn@stable
ddev yarn --version
```

`corepack use` pins the version by setting the `packageManager` field in `package.json`. To clear the global cache, run:

```
ddev exec corepack cache clear
```

## `database`

The type and version of the database engine the project should use.

| Type | Default | Usage |
| --- | --- | --- |
| project | `mariadb:11.8` | The following database types are currently supported:<br>\- MariaDB 5.5-10.8, 10.11, 11.4, 11.8, 12.3<br>\- MySQL 5.5-8.0, 8.4, 9.7<br>\- Postgres 9-18 |

See [Database Server Types](<https://ddev.github.io/ddev/en/stable/users/extend/database-types/index.md>) for examples (e.g. `ddev config --database=mariadb:11.8`) and caveats (e.g. how to migrate from one database version to another).

> [!TIP]
>
> **For very old database types, see [Using DDEV to spin up a legacy PHP application](<https://ddev.com/blog/legacy-projects-with-unsupported-php-and-mysql-using-ddev/>).**

## `dbimage`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it without Docker experience and a good reason. Typically, this means additions to the existing db image using a `.ddev/db-build/Dockerfile.*`.

The Docker image to use for the database server.

| Type | Default | Usage |
| --- | --- | --- |
| project | [`ddev/ddev-dbserver`](<https://hub.docker.com/u/ddev>) | Specify your own image based on the [ddev-dbserver](<https://github.com/ddev/ddev/tree/main/containers/ddev-dbserver>) image matching your project’s `database` type and version. |

DDEV images carry a `com.ddev.image-tag` label recording the image tag they were built as, and a derived image inherits it. When a pinned image was built from a different generation of DDEV images than the running DDEV expects, `ddev start` reports it as custom configuration, along with a note showing both tags. That’s the signal to rebuild your derived image against the current DDEV images. Images built before the label existed are not reported. See [DDEV Labels on Images](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#ddev-labels-on-images>) for how this differs from `com.ddev.webtag`.

## `dbimage_extra_packages`

Extra Debian packages for the project’s database container. (This is rarely used.)

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

Example: `dbimage_extra_packages: [netcat, telnet, sudo]` will add the `netcat`, `telnet`, and `sudo` packages when the database container is built.

## `ddev_version_constraint`

You can configure a [version constraint](<https://github.com/Masterminds/semver#checking-version-constraints>) for DDEV that will be validated against the running DDEV executable and prevent `ddev start` from running if it doesn’t validate. For example:

```
ddev_version_constraint: '>= v1.24.0-alpha1'
```

| Type | Default | Usage |
| --- | --- | --- |
| project |  | `>= 1.24.8` |

## `default_container_timeout`

Seconds DDEV will wait for all containers to become ready.

| Type | Default | Usage |
| --- | --- | --- |
| project | `120` | Can be adjusted to avoid timeouts on slower systems or for huge snapshot restores. |

## `developer_mode`

Not currently used.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

## `disable_settings_management`

Whether to disable CMS-specific settings file management.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. |

When `true`, DDEV will not create or update CMS-specific settings files.

## `disable_upload_dirs_warning`

Whether to disable the standard warning issued when a project is using `performance_mode: mutagen` but `upload_dirs` is not configured.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. |

When `true`, DDEV will not issue the normal warning on `ddev start`: “You have Mutagen enabled and your ‘php’ project type doesn’t have `upload_dirs` set”. See [Mutagen and User-Generated Uploads](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen-and-user-generated-uploads>) for context on why DDEV avoids doing the Mutagen sync on `upload_dirs`.

## `docker_buildx_version`

> [!WARNING]
>
> **Advanced Usage**
>
> `docker_buildx_version` should only be changed for troubleshooting purposes or if you can’t install `docker-buildx` on your system.

Controls which `docker-buildx` plugin DDEV uses.

| Type | Default | Usage |
| --- | --- | --- |
| global | `system` | `system` or a version string like `0.33.0` |

When set to `system` (the default), DDEV uses whatever `docker-buildx` is already installed on your system and never downloads anything.

## `docroot`

Relative path to the document root containing `index.php` or `index.html`.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | DDEV will attempt to detect this and set it for you, otherwise falling back to the current directory. |

## `fail_on_hook_fail`

Whether [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) should be interrupted by a failing [hook](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>), on a single project or for all projects if used globally.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `false` | Can be `true` or `false`. |

## `hooks`

DDEV-specific lifecycle [hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>) to be executed.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | \`\` | Global hooks in `global_config.yaml` run for every project, see [Global Hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/#global-hooks>). |

## `host_db_port`

Port for binding database server to localhost interface.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

Not commonly used. Can be a specific port number for a fixed database port. If unset, the port will be assigned automatically and change each time [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) is run.

Can be a specific port number for a fixed database port, which can be useful for configuration of host-side database clients. (May still be easier to use [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>), `ddev psql`, `ddev sequelace`, etc., which handle changing ports automatically, as does the sample command `ddev mysqlworkbench`.)

## `host_https_port`

Specific, persistent HTTPS port for direct binding to localhost interface.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

Not commonly used. Can be a specific port number for a fixed HTTPS URL. If unset, the port will be assigned automatically and change each time [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) is run.

Example: `59001` will have the project always use `https://127.0.0.1:59001` for the localhost URL—used less commonly than the named URL which is better to rely on.

## `host_mailpit_port`

Specific, persistent Mailpit port for direct binding to localhost interface.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

Not commonly used. Can be a specific port number for a fixed Mailpit URL. If unset, the port will be assigned automatically and change each time [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) is run.

## `host_webserver_port`

Specific, persistent HTTP port for direct binding to localhost interface.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

Not commonly used. Can be a specific port number for a fixed HTTP URL. If unset, the port will be assigned automatically and change each time [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) is run.

Example: `59000` will have the project always use `http://127.0.0.1:59000` for the localhost URL—used less commonly than the named URL which is better to rely on.

## `host_xhgui_port`

Specific, persistent XHGui port for direct binding to localhost interface.

| Type | Default | Usage |
| --- | --- | --- |
| project | automatic | ‌ |

Very rarely used. Can be a specific port number for a fixed XHGui URL.

## `instrumentation_opt_in`

Whether to allow [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `true` | Can be `true` or `false`. |

When `true`, anonymous usage information is collected via [Amplitude](<https://amplitude.com/>).

## `instrumentation_queue_size`

Maximum number of locally collected events for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `100` | Can be any integer. |

## `instrumentation_reporting_interval`

Reporting interval in hours for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `24` | Can be any integer. |

## `instrumentation_user`

Specific name identifier for [instrumentation reporting](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| global | \`\` | ‌ |

## `internet_detection_timeout_ms`

Internet detection timeout in milliseconds.

| Type | Default | Usage |
| --- | --- | --- |
| global | `3000` (3 seconds) | Can be any integer. |

DDEV must detect whether the internet is working to determine whether to add hostnames to `/etc/hosts`. In rare cases, you may need to increase this value if you have slow but working internet. See [FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/index.md>) and [GitHub issue](<https://github.com/ddev/ddev/issues/2409#issuecomment-662448025>).

## `letsencrypt_email`

Email associated with Let’s Encrypt feature. (Works in conjunction with [`use_letsencrypt`](<#use_letsencrypt>).)

| Type | Default | Usage |
| --- | --- | --- |
| global | \`\` | ‌ |

Set with `ddev config global --letsencrypt-email=me@example.com`. Used with the [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `mailpit_http_port`

Port for project’s Mailpit HTTP URL.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8025` | Can be changed to avoid a port conflict. |

## `mailpit_https_port`

Port for project’s Mailpit HTTPS URL.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8026` | Can be changed to avoid a port conflict. |

## `messages`

Configure messages like the Tip of the Day.

| Type | Default | Usage |
| --- | --- | --- |
| global | `ticker_interval:` | hours between ticker messages. |

Example: Disable the “Tip of the Day” ticker in `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>))

```
messages:
  ticker_interval: -1
```

Example: Show the “Tip of the Day” ticket every two hours:

```
messages:
  ticker_interval: 2
```

## `name`

The URL-friendly name DDEV should use to reference the project.

| Type | Default | Usage |
| --- | --- | --- |
| project | enclosing directory name | Must be unique; no two projects can have the same name. It’s best if this matches the directory name. If this option is omitted, the project will take the name of the enclosing directory. This value may also be set via `ddev config --project-name=<name>`. (The `ddev config` flag is `project-name`, not `name`, see [`ddev config` docs](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).)” |

## `no_bind_mounts`

Whether to not use Docker bind mounts.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

Some Docker environments (like remote Docker) do not allow bind mounts, so when `true` this turns those off, turns on Mutagen, and uses volume copies to do what bind mounts would otherwise do.

## `no_project_mount`

Whether to skip mounting project into web container.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. |

> [!WARNING]
>
> **Advanced users only!**
>
> When `true`, project will not be mounted by DDEV into the web container. Enables experimentation with alternate file mounting strategies.

## `no_tui`

Whether to disable the TUI (terminal user interface) when running the `ddev` command without any arguments.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

## `nodejs_root`

The relative path, from the project root, to the directory containing the Node.js version file. (Requires [`nodejs_version`](<#nodejs_version>) `auto` or `engine`.)

| Type | Default | Usage |
| --- | --- | --- |
| project | ‌ | `nodejs_root: web/themes/custom/mytheme` |

## `nodejs_version`

Node.js version for the web container, managed by [`n`](<https://www.npmjs.com/package/n>).

| Type | Default | Usage |
| --- | --- | --- |
| project | current LTS version | Any [Node.js version](<https://www.npmjs.com/package/n#specifying-nodejs-versions>); see the table below for what each value does. |

What DDEV does depends on the value:

| Value | Result |
| --- | --- |
| `24` | Default version preinstalled in DDEV. |
| `""` (empty) | Uses the version already included in the image, with no download step (fastest for CI). Follows DDEV default behavior over time. |
| `v24` | Installs the newest `24.x` release when the image is built. Use the `v` prefix only to get the latest of the current default major. |
| any other version (`22`, `20.2`, `18.19.2`, etc.) | Installs that version when the image is built. A bare major like `22` already installs the newest `22.x`. |
| `auto`, `engine` | Reads the version from a file in your project (see below). |

> [!WARNING]
>
> **The Node.js version changes only when the image is rebuilt**
>
> A version installed by `n` is fixed at build time. It changes only when the `ddev-webserver` image is rebuilt, for example when you upgrade DDEV. You can also trigger a rebuild manually:
>
> ```
> ddev restart --no-cache
> # or
> ddev utility rebuild
> ```
>
> Example: you set `22`, and `n` installs the newest `22.x` available at build time, for example `22.14.0`. If `22.14.1` is released before the next rebuild, your project stays on `22.14.0` until then.

> [!TIP]
>
> **How to define the Node.js version using a file**
>
> Set `nodejs_version: auto` to read the version from a file in your project root ([`DDEV_APPROOT`](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>)). `n` checks these in order: `.n-node-version`, `.node-version`, `.nvmrc`, then the `engines.node` field in `package.json`. Set `nodejs_version: engine` to use only `engines.node`. Either value fails validation if no such file exists. See [n’s documentation](<https://www.npmjs.com/package/n#specifying-nodejs-versions>) for details.
>
> If your version file is not in your project root, point [`nodejs_root`](<#nodejs_root>) at its directory. For example, if you have `frontend/.nvmrc`:
>
> ```
> nodejs_root: frontend
> nodejs_version: auto
> ```

> [!TIP]
>
> **Installing additional Node.js versions**
>
> To have multiple Node.js versions available, install additional ones via a [`post-start` hook](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>) using `n`:
>
> ```
> hooks:
>   post-start:
>     - exec: "n install 18 && n install 20"
> ```
>
> All installed versions are cached; the last one becomes active. Switch with `ddev exec n <version>`, clean up with `ddev exec n prune`.

## `omit_containers`

Containers that should not be loaded automatically for one or more projects.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `[]` | **For projects**, can include `db`, and `ddev-ssh-agent`.<br>**Globally**, can include `ddev-router`, and `ddev-ssh-agent`. |

Example: `omit_containers: [db, ddev-ssh-agent]` starts the project without a `db` container and SSH agent. Some containers can be omitted globally in `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) and the result is additive; all containers named in both places will be omitted.

> [!WARNING]
>
> Omitting the `db` container will cause database-dependent DDEV features to be unstable.

## `omit_project_name_by_default`

Determines whether `ddev config` updates the `name` field in the `.ddev/config.yaml` by default.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

When the `name` field is omitted in `.ddev/config.yaml`, DDEV gets the project name from the directory the project is in. If this option is set to `true`, `ddev config` will not update the `name` field unless you use `ddev config --project-name=<name>` to explicitly set the project name. People using `git worktree` often prefer to omit the project name so they can work on multiple projects at the same time in different worktrees.

## `omit_snapshot_on_delete`

Determines whether to omit the database snapshot when running `ddev delete` by default.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

Snapshots are taken by default when running `ddev delete` to allow recovery of data if the deletion was accidental. Setting this to `true` will turn off that safety feature. You can also override this behavior on a per-command basis with `ddev delete --omit-snapshot=false`.

## `override_config`

Whether to override config values instead of merging.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `false` | Can be `true` or `false`. |

When `true`, the `config.*.yaml` or `global_config.*.yaml` file with the option will have its settings *override* rather than *merge with* others. Allows statements like `use_dns_when_possible: false` or `additional_hostnames: []` to work.

See [Extending `config.yaml` with Custom `config.*.yaml` Files](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#extending-configyaml-with-custom-configyaml-files>).

## `performance_mode`

Defines the performance optimization mode to be used. Currently [Mutagen asynchronous caching](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) is supported. Mutagen is enabled by default on Mac and Traditional Windows.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | \`\` | Can be `global`, `none`, `mutagen`. |

This is typically a global setting. The project-specific value will override global config.

## `php_version`

The PHP version the project should use.

| Type | Default | Usage |
| --- | --- | --- |
| project | `8.4` | Can be `5.6` through `8.6`. New versions are added when released upstream. |

You can only specify the major version (`7.3`), not a minor version (`7.3.2`), from those explicitly available.

## `project_tld`

Default Top-Level-Domain (`TLD`) to be used for a project’s domains, or globally for all project domains. This defaults to `ddev.site` and it’s easiest to work with DDEV using the default setting.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `ddev.site` | Can be changed to any TLD you’d prefer. |

See [Hostnames and Wildcards and DDEV, Oh My!](<https://ddev.com/blog/ddev-name-resolution-wildcards/>) for more information on DDEV hostname resolution.

## `router_bind_all_interfaces`

Whether to bind `ddev-router`’s ports on all network interfaces.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

When `true`, the router will bind on all network interfaces instead of only `localhost`, exposing DDEV projects to your local network. This is sometimes used to share projects on a local network, see [Sharing Your Project](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>).

## `router_http_port`

Port for DDEV router’s HTTP traffic.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `80` | Usually changed only if there’s a conflicting process using that port. |

See the [Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>) page for more on addressing port conflicts.

## `router_https_port`

Port for DDEV router’s HTTPS traffic.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `443` | Usually changed only if there’s a conflicting process using that port. |

See the [Troubleshooting](<https://ddev.github.io/ddev/en/stable/users/usage/troubleshooting/#web-server-ports-already-occupied>) page for more on addressing port conflicts.

## `share_default_provider`

The default share provider to use with the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `ngrok` | Built-in providers: `ngrok`, `cloudflared`. Custom providers can be added to `.ddev/share-providers/`. Project config overrides global config. |

Set globally with `ddev config global --share-default-provider=cloudflared` or per-project with `ddev config --share-default-provider=cloudflared`. Can also be overridden with the `--provider` flag when running `ddev share`.

## `share_provider_args`

Extra flags for configuring provider when [sharing projects](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>) with the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) command.

| Type | Default | Usage |
| --- | --- | --- |
| project | \`\` | ‌ |

Example:

- [ngrok](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#setting-up-a-stable-ngrok-domain>): `--basic-auth username:pass1234 --domain foo.ngrok-free.app`.
- [cloudflared](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/#setting-up-a-stable-cloudflared-domain>): `--tunnel my-tunnel --hostname mysite.example.com`.

> [!NOTE]
>
> **Replaces `ngrok_args`**
>
> This option replaces the deprecated `ngrok_args`. The old name still works for backward compatibility.

## `simple_formatting`

Whether to disable most [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) table formatting and implicitly set `NO_COLOR=1`.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. If you don’t like the table lines in `ddev list` or `ddev describe`, you can completely turn them off with `ddev config global --simple-formatting=true`. |

When `true`, turns off most table formatting in [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) and suppresses colorized text everywhere.

## `skip_global_hooks`

Whether to skip the [global hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/#global-hooks>) in this project.

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Can be `true` or `false`. Project hooks still run. |

## `ssh_agent_upstream`

Make the `ddev-ssh-agent` container relay to an SSH agent you already run, such as the macOS agent, 1Password, or one forwarded with `ssh -A`, instead of running its own agent. See [Using an Existing SSH Agent](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>) for how this works with each Docker provider.

| Type | Default | Usage |
| --- | --- | --- |
| global | (empty) | Can be empty, `host`, or an absolute or `~/`-relative path of an agent socket. |

- Empty: `ddev-ssh-agent` runs its own agent, and [`ddev auth ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#auth-ssh>) adds key files to it.
- `host`: relay to the agent your Docker provider forwards (Docker Desktop on macOS or Linux, OrbStack, Colima with `--ssh-agent`, or Lima with `ssh.forwardAgent`), or on Linux and WSL2 to the socket in `$SSH_AUTH_SOCK` when a project starts.
- A socket path: relay to that socket. The Docker host must be able to reach it, so on macOS use `host` instead.

Traditional Windows doesn’t support this setting, because Windows SSH agents such as 1Password listen on a named pipe that Docker can’t reach. On WSL2, bridge that pipe to a socket path first, as [Using an Existing SSH Agent](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>) describes.

If DDEV can’t use the setting, for example `host` with a provider that doesn’t forward an agent, projects still start with DDEV’s own agent and a warning. With an upstream agent, `ddev auth ssh` lists the agent’s keys rather than adding keys.

## `table_style`

Style for [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>) and [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>).

| Type | Default | Usage |
| --- | --- | --- |
| global | `default` | Can be `default`, `bold`, and `bright`. |

`bright` is a pleasant, colorful output some people may prefer. If you don’t like the table lines at all, you can remove them with `ddev config global --simple-formatting=true`.

## `timezone`

Timezone for container and PHP configuration.

| Type | Default | Usage |
| --- | --- | --- |
| project | Automatic detection or `UTC` | Can be any [valid timezone](<https://en.wikipedia.org/wiki/List_of_tz_database_time_zones>), like `Europe/Dublin` or `MST7MDT`. |

If `timezone` is unset, DDEV will attempt to derive it from the host system timezone using the `$TZ` environment variable or the `/etc/localtime` symlink.

## `traefik_monitor_port`

Specify an alternate port for the Traefik (ddev-router) monitor port. This defaults to 10999 and rarely needs to be changed, but can be changed in cases of port conflicts.

| Type | Default | Usage |
| --- | --- | --- |
| global | `10999` | Can be any unused port below 65535. |

## `type`

The DDEV-specific project type.

| Type | Default | Usage |
| --- | --- | --- |
| project | `php` | Can be `asterios`, `backdrop`, `cakephp`, `codeigniter`, `craftcms`, `drupal`, `drupal6`, `drupal7`, `drupal8`, `drupal9`, `drupal10`, `drupal11`, `drupal12`, `generic`, `joomla`, `laravel`, `magento`, `magento2`, `maho`, `modx`, `php`, `shopware6`, `silverstripe`, `symfony`, `typo3`, `wordpress`, or `wp-bedrock`. |

The `php` type doesn’t attempt [CMS configuration](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>) or settings file management and can work with any project.

The many versions of the Drupal project types can be used, for example `drupal11` or `drupal6`. There is also a special `drupal` type that is interpreted as “latest stable Drupal version”, so until the release of Drupal 12, `drupal` currently means `drupal11`.

The special `generic` project type does nothing and implies nothing. It is normally used with `webserver_type: generic`.

## `upload_dirs`

Paths from the project’s docroot to the user-generated files directory targeted by `ddev import-files`. Can be outside the docroot but must be within the project directory e.g. `../private`. Some CMSes and frameworks have default `upload_dirs`, like Drupal’s `sites/default/files`; `upload_dirs` will override the defaults, so if you want Drupal to use both `sites/default/files` and `../private` you would list both, `upload_dirs: ["sites/default/files", "../private"]`. `upload_dirs` is used for targeting `ddev import-files` and also, when Mutagen is enabled, to bind-mount those directories so their contents does not need to be synced into Mutagen.

If you do not have directories of static assets of this type, or they are small and you don’t care about them, you can disable the warning `You have Mutagen enabled and your 'php' project type doesn't have upload_dirs set.` by setting [`disable_upload_dirs_warning`](<#disable_upload_dirs_warning>) with `ddev config --disable-upload-dirs-warning`.

| Type | Default | Usage |
| --- | --- | --- |
| project |  | A list of directories. |

## `use_dns_when_possible`

Whether to use DNS instead of editing `/etc/hosts`.

| Type | Default | Usage |
| --- | --- | --- |
| project | `true` | Can be `true` or `false`. |

When `false`, DDEV will always update the `/etc/hosts` file with the project hostname instead of using DNS for name resolution.

See [Using DDEV Offline](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>).

## `use_hardened_images`

Whether to use hardened images for internet deployment.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

When `true`, more secure hardened images are used for an internet deployment. These do not include sudo in the web container, and the container is run without elevated privileges. Generally used with the [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `use_letsencrypt`

Whether to enable Let’s Encrypt integration. (Works in conjunction with [`letsencrypt_email`](<#letsencrypt_email>).)

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

May also be set via `ddev config global --use-letsencrypt` or `ddev config global --use-letsencrypt=false`. When `true`, `letsencrypt_email` must also be set and the system must be available on the internet. Used with the [hosting](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>) feature.

## `web_environment`

Additional [custom environment variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/#web_environment>) for a project’s web container. (Or for all projects if used globally.)

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `[]` | ‌ |

## `web_extra_daemons`

Additional daemons that should [automatically be started in the web container](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#running-extra-daemons-in-the-web-container>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

## `web_extra_exposed_ports`

Additional named sets of ports to [expose via `ddev-router`](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#exposing-extra-ports-via-ddev-router>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

For common front-end development tools like Vite, see the [Vite Integration](<https://ddev.github.io/ddev/en/stable/users/usage/vite/index.md>) documentation for complete configuration examples.

## `webimage`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it without Docker experience and a good reason. Typically, this means additions to the existing web image using a `.ddev/web-build/Dockerfile.*`.

The Docker image to use for the web server.

| Type | Default | Usage |
| --- | --- | --- |
| project | [`ddev/ddev-webserver`](<https://hub.docker.com/r/ddev/ddev-webserver>) | Specify your own image based on [ddev/ddev-webserver](<https://github.com/ddev/ddev/tree/main/containers/ddev-webserver>). |

## `webimage_extra_packages`

Extra Debian packages for the project’s web container.

| Type | Default | Usage |
| --- | --- | --- |
| project | `[]` | ‌ |

Example: `webimage_extra_packages: ['php${DDEV_PHP_VERSION}-tidy', 'php${DDEV_PHP_VERSION}-yac']` will add the `phpX.Y-tidy` and `phpX.Y-yac` packages when the web container is built.

## `webserver_type`

Which available [web server type](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#changing-web-server-type>) should be used.

| Type | Default | Usage |
| --- | --- | --- |
| project | `nginx-fpm` | Can be `nginx-fpm`, `apache-fpm`, `generic`. |

To change from the default `nginx-fpm` to `apache-fpm`, for example, you would need to edit your project’s `.ddev/config.yaml` to include the following:

```
webserver_type: apache-fpm
```

This is the same as `ddev config --webserver-type=apache-fpm`.

Then run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) to have the change take effect.

The `generic` type is special: It tells DDEV not to run any web server daemons, and the user can configure their own with the [`web_extra_daemons`](<#web_extra_daemons>) option.

> [!TIP]
>
> For generic web server configuration examples, see the [quickstart guide](<https://ddev.github.io/ddev/en/stable/users/quickstart/#generic>).

## `working_dir`

Working directories used by [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) and [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>).

| Type | Default | Usage |
| --- | --- | --- |
| project | ‌ | ‌ |

Example: `working_dir: { web: "/var/www", db: "/etc" }` sets the working directories for the `web` and `db` containers.

## `wsl2_no_windows_hosts_mgt`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it. On Windows, it may prevent site access when using a custom [`project_tld`](<#project_tld>) or working [offline](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>).

(WSL2 only) Whether to disable the management and checking of the Windows hosts file. By default, when using WSL2, DDEV manages the system-wide hosts file on the Windows side (normally `C:\Windows\system32\drivers\etc\hosts`) by using `ddev.exe` installed on the *Windows* side. This normally works better for all applications, including browsers and IDEs. However, this behavior can be disabled by setting `wsl_no_windows_hosts_mgt: true`.

| Type | Default | Usage |
| --- | --- | --- |
| global | `false` | Can be `true` or `false`. |

May also be set via `ddev config global --wsl2-no-windows-hosts-mgt` or `ddev config global --wsl2-no-windows-hosts-mgt=false`.

## `xdebug_enabled`

Whether Xdebug should be enabled for [step debugging](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/step-debugging/index.md>) or [profiling](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xdebug-profiling/index.md>).

| Type | Default | Usage |
| --- | --- | --- |
| project | `false` | Please leave this `false` in most cases. Most people use [`ddev xdebug`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>) and `ddev xdebug off` (or `ddev xdebug toggle`) commands. |

## `xdebug_ide_location`

> [!WARNING]
>
> **Proceed with caution**
>
> It’s unusual to change this option, and we don’t recommend it. Ask for help in one of our [support channels](<https://ddev.github.io/ddev/en/stable/users/support/index.md>) before changing it unless you understand its use completely.

Adjust Xdebug listen location for WSL2 or in-container. This is used very rarely.

| Type | Default | Usage |
| --- | --- | --- |
| global | `""` | Can be empty (`""`), `"wsl2"`, `"container"`, or an explicit IP address. |

For PhpStorm running inside WSL2 (or JetBrains Gateway), use `"wsl2"`. For in-container like VS Code Language Server, set to `"container"`. It can also be set to an explicit IP address.

Examples:

- `xdebug_ide_location: 172.16.0.2` when you need to provide an explicit IP address where the IDE is listening. This is very unusual.
- `xdebug_ide_location: container` when the IDE is actually listening inside the `ddev-webserver` container. This is only done very occasionally with obscure Visual Studio Code setups like VS Code Language Server.
- `xdebug_ide_location: wsl2` when an IDE is running (or listening) in WSL2. This is the situation when running an IDE directly inside WSL2 instead of running it on Windows.

## `xhgui_http_port`

Port for project’s XHGui HTTP URL (for router). Only changed when there are port conflicts on the default port 8143.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8143` | Can be changed to avoid a port conflict. |

## `xhgui_https_port`

Port for project’s XHGui HTTPS URL (for router). Only changed when there are port conflicts on the default port 8142.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `8142` | Can be changed to avoid a port conflict. |

## `xhprof_mode`

Whether XHProf should use `prepend` or `xhgui` mode.

| Type | Default | Usage |
| --- | --- | --- |
| project<br>global | `xhgui` | Can be `global`, `prepend` or `xhgui`. |

# Environment Variables

There are three different things people mean by “environment variables” in a DDEV project, and they land in different places. This page covers all of them, in what order they override each other, and where to put a secret.

The same two scopes as [config options](<https://ddev.github.io/ddev/en/stable/users/configuration/config/index.md>) apply here:

1. **Project** files, in the project directory and mostly under `.ddev`.
2. **Global** files in the [global DDEV directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>), which apply to every project. This page writes that directory as `$HOME/.ddev`, its usual location, but it can be somewhere else.

> [!TIP]
>
> **Container variables take effect on restart**
>
> The `.ddev/.env*` files, their global equivalents, and `web_environment` are read while containers are being created, so run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) after changing them. An application `.env` file in the project root is not one of these: your framework reads it on every request, so changing it needs no restart.

## Which Variables Reach Where

| Where you set it | Type | What it reaches | Who reads it |
| --- | --- | --- | --- |
| An application `.env` file in the project root | project | Nothing in the container environment; it stays a file in your project | Your framework: Laravel, Craft CMS, Symfony, Silverstripe, and others |
| [`.ddev/.env*`](<#project-env-files>) and [`$HOME/.ddev/.env*`](<#global-env-files>) | project<br>global | The environment of any container in the project: `web`, `db`, and add-on or custom services | Anything running in the container, plus interpolation in `.ddev/docker-compose.*.yaml` |
| [`web_environment`](<#web_environment>) | project<br>global | The environment of the `web` container only | Anything running in `web` |

## Application `.env` Files, Outside `.ddev/`

Many frameworks read a `.env` file in the project root. That file belongs to your application, and DDEV treats it as ordinary project code: nothing in it becomes a container environment variable.

For several project types DDEV writes database credentials and the project URL into that file as part of [settings management](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/index.md>), creating it if it doesn’t exist. Set [`disable_settings_management`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#disable_settings_management>) to `true` if you want to manage the file yourself.

You can edit it from the command line with [`ddev dotenv set`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-set>), which is useful in a `README` or a CI script because it creates the file and updates single keys without disturbing the rest:

```
ddev dotenv set .env --app-key=value
```

Your framework reads this file on every request, so a change to it takes effect without a `ddev restart`.

The `.local` convention below applies only inside `.ddev/` and `$HOME/.ddev/`. A root `.env.local`, like the one Symfony and Shopware use, is your project’s file and is covered by your project’s own `.gitignore`.

## Project Env Files

The `.env*` files in the project’s `.ddev` directory set real environment variables in the project’s containers. The filename decides which service gets them:

```
.env[.<service>[.<label>...]][.local]
```

| File | Reaches | Notes |
| --- | --- | --- |
| `.ddev/.env` | Every container in the project |  |
| `.ddev/.env.local` | Every container in the project | Gitignored, DDEV v1.25.4+ |
| `.ddev/.env.web` | The `web` container | Any service name works: `db`, `redis`, and so on |
| `.ddev/.env.web.local` | The `web` container | Gitignored, DDEV v1.25.4+ |
| `.ddev/.env.web.myaddon` | The `web` container | A label keeps files from different sources apart, DDEV v1.25.4+ |
| `.ddev/.env.web.myaddon.local` | The `web` container | Gitignored, DDEV v1.25.4+ |
| `.ddev/.env.redis-build` | Nothing | No service is named `redis-build`, so this file is expanded but never injected |

A trailing `.local` only marks the file as gitignored, and a label after the service name only keeps files apart. Both are dropped before DDEV reads the service name, so `local` cannot be used as a service or label name. Files ending in `.example` are skipped, which is how an add-on ships a documented template without setting anything.

Every one of these files is also passed to `docker-compose config`, whatever it is named, so `${SOME_VARIABLE}` in a `.ddev/docker-compose.*.yaml` file is expanded from all of them together. That is the point of the `.ddev/.env.redis-build` row above: when a variable is only meant to be substituted into a compose file, give the file a name that is not a service name and it will never appear inside a container.

## Override Order

Later wins. Everything in the [global DDEV directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>) is applied before anything belonging to the project, and within each directory DDEV sorts the files by their name with a trailing `.local` removed, which puts a `.local` file directly after the file it overrides.

The table below is a project that has every kind of file at once, with `db` and `web` as its services and `myaddon` as a label. The global files, the `.local` files, and the labeled files all need DDEV v1.25.4+; `.ddev/.env` and `.ddev/.env.<service>` are older.

| \# | Content | Notes |
| --- | --- | --- |
| 1 | `web_environment` in `$HOME/.ddev/global_config.yaml` | Reaches the `web` container only |
| 2 | `web_environment` in `.ddev/config.yaml`, then `.ddev/config.*.yaml` | Reaches the `web` container only |
| 3 | `$HOME/.ddev/.env` | Every container of every project |
| 4 | `$HOME/.ddev/.env.local` | Overrides the file above it, gitignored |
| 5 | `$HOME/.ddev/.env.db` | Services in alphabetical order, so `db` before `web` |
| 6 | `$HOME/.ddev/.env.db.local` | Overrides the file above it, gitignored |
| 7 | `$HOME/.ddev/.env.web` | ‌ |
| 8 | `$HOME/.ddev/.env.web.local` | Overrides the file above it, gitignored |
| 9 | `$HOME/.ddev/.env.web.myaddon` | Labels in alphabetical order, all after the unlabeled `$HOME/.ddev/.env.web` |
| 10 | `$HOME/.ddev/.env.web.myaddon.local` | Overrides the file above it, gitignored |
| 11 | `.ddev/.env` | Every container of this project |
| 12 | `.ddev/.env.local` | Overrides the file above it, gitignored |
| 13 | `.ddev/.env.db` | Services in alphabetical order, so `db` before `web` |
| 14 | `.ddev/.env.db.local` | Overrides the file above it, gitignored |
| 15 | `.ddev/.env.web` | ‌ |
| 16 | `.ddev/.env.web.local` | Overrides the file above it, gitignored |
| 17 | `.ddev/.env.web.myaddon` | Labels in alphabetical order, all after the unlabeled `.ddev/.env.web` |
| 18 | `.ddev/.env.web.myaddon.local` | Overrides the file above it, gitignored, and applied last of all |

Only the files you actually have are applied, and the rest of the order is unchanged. A second label, `.ddev/.env.web.otheraddon`, would come after row 18, because `myaddon` sorts before `otheraddon` and a `.local` file never leaves the file it overrides.

A command run with `ddev exec`, `ddev ssh`, or a custom command also gets the [host variables forwarded on exec](<#host-variables-forwarded-on-exec>), which come after every row above and apply to that command only. A bare `web_environment` name is different: DDEV reads it from the host again on exec, but it keeps its place in row 1 or 2, so an env file that sets the same name still wins.

To see the result:

- [`ddev utility check-custom-config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-check-custom-config>) lists the env files DDEV found under `Environment`, in the order they are applied.
- [`ddev utility compose-config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-compose-config>) shows the rendered `.ddev/.ddev-docker-compose-full.yaml`, including the `environment` section of each service.
- `ddev exec env` and `ddev exec -s <service> env` show what a command run in a container gets, which includes the [host variables forwarded on exec](<#host-variables-forwarded-on-exec>).

## Global Env Files

With DDEV v1.25.4+, the same filenames work in the [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>), where they apply to every project on the machine. `$HOME/.ddev/.env` reaches every container of every project, and `$HOME/.ddev/.env.db` reaches the `db` container of every project.

This is the only way to set a variable globally for something other than the `web` container, which is all [`web_environment`](<#web_environment>) can do.

Global files are applied before anything belonging to the project, so a global value is only a default: a project that sets the same variable in `.ddev/.env` or `.ddev/.env.<service>` wins. See [Override Order](<#override-order>) for the full sequence.

Use [`ddev dotenv global set`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-global-set>) to write them. Name the file `.ddev/<file>` exactly as you would in a project, and DDEV resolves it in the global directory:

```
ddev dotenv global set .ddev/.env.web --api-url=https://example.com
```

## Secrets

With DDEV v1.25.4+, DDEV adds `/.env.local` and `/.env.*.local` to both `.ddev/.gitignore` and `$HOME/.ddev/.gitignore`, so any env file ending in `.local` stays out of Git without you having to take over those files.

That gives a shared service a natural split: commit `.ddev/.env.web` with the settings your team shares, and keep the token next to it in `.ddev/.env.web.local`, which is applied right after it.

```
# Committed, everyone gets it
ddev dotenv set .ddev/.env.web --api-url=https://example.com

# Gitignored, yours only
ddev dotenv set .ddev/.env.web.local --api-key=secret
```

To document which keys are expected without committing their values, add a `.ddev/.env.web.example` file listing the keys with empty values. DDEV never reads `.example` files, and `.ddev/.gitignore` ignores them, so commit it with `git add -f .ddev/.env.web.example`.

The global files work the same way, so `$HOME/.ddev/.env.web.local` is a reasonable home for a credential you use in every project (but note that it is overridden by project-level `.ddev/.env` or `.ddev/.env.web`, etc).

## `web_environment`

The [`web_environment`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_environment>) setting predates the env files above and only reaches the `web` container. It lives in `.ddev/config.yaml` or any `.ddev/config.*.yaml` for a project, and in `$HOME/.ddev/global_config.yaml` for every project:

```
web_environment:
    - MY_ENV_VAR=someval
    - MY_OTHER_ENV_VAR=someotherval
```

You can also pass a variable through from the host by listing just its name with no value. DDEV hands the bare name to docker-compose, which resolves it from the host environment when the container starts:

```
web_environment:
    - MY_HOST_VAR
```

DDEV also reads each bare name from the host again on every [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), or custom command run in `web`, so a value set after `ddev start`, for example by an AI agent, reaches that command without a restart:

- Only that command sees the new value. PHP-FPM and anything else started with the container keep the value from `ddev start` until you run `ddev restart`.
- If the name is not set on the host when you run the command, the command keeps the value from `ddev start`.
- A name that a `.ddev/.env*` file also sets for `web` keeps the value from that file, as it does at start, because env files come later in the [override order](<#override-order>).

To set these from the command line, use [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). Use `--web-environment` instead of `--web-environment-add` to replace the existing list rather than add to it:

```
# Set MY_ENV_VAR for the project
ddev config --web-environment-add="MY_ENV_VAR=someval"

# Set MY_ENV_VAR globally
ddev config global --web-environment-add="MY_ENV_VAR=someval"
```

## Host Variables Forwarded on Exec

Some variables describe the session that runs a command rather than the project, so DDEV copies them from the host into every [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), and custom command, in any service. They reach only that command, so none of them needs a restart. A variable is forwarded when it is set on the host, even to an empty value, because some tools only check that it exists:

- The variables AI coding agents use to identify themselves, such as `AI_AGENT`, `CLAUDECODE`, `CURSOR_AGENT`, or `GEMINI_CLI`, so tools like PHPStan in the container know an agent called them. The list follows [laravel/agent-detector](<https://github.com/laravel/agent-detector#supported-agents>), minus `COPILOT_GITHUB_TOKEN`, which is a credential.
- In an interactive session, `TERM` and the variables a terminal identifies itself with, such as `COLORTERM` and `TERM_PROGRAM`, so programs know how many colors and which hyperlinks they can use.
- For [`ddev composer`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#composer>), [`COMPOSER_NO_BLOCKING`](<https://getcomposer.org/doc/03-cli.md#composer-no-blocking>).

None of them reach the daemons that `ddev start` launches, like `nginx`, `php-fpm`, or [`web_extra_daemons`](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/#running-extra-daemons-in-the-web-container>), so a project runs the same whether a person or an AI agent started it.

To forward another variable to `web`, add its bare name to [`web_environment`](<#web_environment>).

## Applying Changes

A running container never picks up a new value on its own, though `ddev exec` reads each [bare `web_environment` name](<#web_environment>) from the host again. After adding or editing any `.ddev/.env*` file, its global equivalent, or a `web_environment` value, run:

```
ddev restart
```

An application `.env` file in the project root is the exception, since your framework reads it on every request rather than at container start.

## `ddev dotenv`

The [`ddev dotenv`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv>) commands create and update these files without an editor, quoting values correctly. Flags become variable names: `--api-url` writes `API_URL`.

| Command | Type | Where the file lands |
| --- | --- | --- |
| [`ddev dotenv set`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-set>), [`ddev dotenv get`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-get>) | project | The path is relative to the project root, so `.env` for an application file and `.ddev/.env.web` for a DDEV one |
| [`ddev dotenv global set`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-global-set>), [`ddev dotenv global get`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#dotenv-global-get>) | global | The same `.ddev/<file>` path, resolved in the [global DDEV directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>), DDEV v1.25.4+ |

A DDEV env file is named `.ddev/.env*` in both scopes, so the only difference between the two commands is the word `global`:

```
ddev dotenv set .ddev/.env.redis --redis-tag 7-bookworm
ddev dotenv get .ddev/.env.redis --redis-tag

ddev dotenv global set .ddev/.env.redis --redis-tag 7-bookworm
ddev dotenv global get .ddev/.env.redis --redis-tag
```

## See Also

- [Using Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/#customizing-add-on-configuration>) for configuring an add-on this way
- [Creating Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/index.md>) for shipping env files with an add-on
- [Custom Docker Compose Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/index.md>) for using these variables in your own service
- [Environment Variables Provided](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>) for the `DDEV_*` variables DDEV sets itself

# Hooks

Most DDEV commands provide hooks to run tasks before or after the main command executes. To automate setup tasks specific to your project, define them in the project’s `config.yaml` file.

To define command tasks in your configuration, specify the desired command hook as a subfield to `hooks`, then a list of tasks to run:

```
hooks:
  post-start:
    - exec: "simple command expression"
    - exec: "ls >/dev/null && touch /var/www/html/somefile.txt"
    - exec-host: "simple command expression"
  post-import-db:
    - exec: "drush uli"
```

## Global Hooks

Hooks that should run for every project on your machine go in the `hooks` section of `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)), with the same syntax as above:

```
hooks:
  post-start:
    - exec-host: "echo a global hook ran"
```

For each hook, global tasks run first, then the project’s tasks. If a project has a task identical to a global one, the global copy is dropped and the project’s task runs in its place, so a hook you already copied into your projects does not run twice.

- A global `exec` task whose `service` is [omitted](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#omit_containers>) or not running in a project is skipped with a notice, and does not count as a failure even with [`fail_on_hook_fail`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#fail_on_hook_fail>).
- Set [`skip_global_hooks: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#skip_global_hooks>) in a project’s configuration to skip all global hooks there, and use `ddev --skip-hooks` to skip all hooks, global and project.
- `exec-host` tasks run in the project directory, so use absolute paths or `$HOME` when running a script from your home directory.
- Global `pre-exec` and `post-exec` hooks run on every [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) and on the commands DDEV runs in containers itself, for example during `ddev start` and `ddev import-db`, so keep them fast. They do not run around `exec` tasks in other hooks.
- An invalid hook name or task in `global_config.yaml` stops every `ddev` command with an error naming the file, until it is fixed.
- [`ddev utility check-custom-config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-check-custom-config>) and the warning at `ddev start` list global hooks.

## Supported Command Hooks

- `pre-start`: Hooks into [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). Execute tasks before the project environment starts.

  > **Tip**
  >
  > Only `exec-host` tasks can run during `pre-start` because the containers are not yet running. See [Supported Tasks](<#supported-tasks>) below.
- `post-start`: Execute tasks after the project environment has started.
- `pre-import-db` and `post-import-db`: Execute tasks before or after database import.
- `pre-import-files` and `post-import-files`: Execute tasks before or after files are imported.
- `pre-composer` and `post-composer`: Execute tasks before or after the `composer` command.
- `pre-share` and `post-share`: Execute tasks before or after the `share` command.
- `pre-stop`, `pre-config`, `post-config`, `pre-describe`, `post-describe`, `pre-exec`, `post-exec`, `pre-pull`, `post-pull`, `pre-push`, `post-push`, `pre-snapshot`, `post-snapshot`, `pre-delete-snapshot`, `post-delete-snapshot`, `pre-restore-snapshot`, `post-restore-snapshot`: Execute as the name suggests.
- `post-stop`: Hooks into [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>). Execute tasks after the project environment stopped.

  > **Tip**
  >
  > Only `exec-host` tasks can run during `post-stop`. See [Supported Tasks](<#supported-tasks>) below.
- `pre-delete` and `post-delete`: Hooks into [`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>). Execute tasks before or after the project and its database are deleted, for example to remove generated files that `ddev delete` leaves in the codebase.

  > **Tip**
  >
  > Only `exec-host` tasks can run during `post-delete`, and during `pre-delete` when the project is not running. See [Supported Tasks](<#supported-tasks>) below.

## Supported Tasks

DDEV currently supports these tasks:

- `exec` to execute a command in any service/container.
- `exec-host` to execute a command on the host.
- `composer` to execute a Composer command in the web container.

### `exec`: Execute a shell command in a container (defaults to web container)

Value: string providing the command to run. Commands requiring user interaction are not supported.

**Optional keys:**

- `service`: Specify which container to run the command in (defaults to `web`)
- `user`: Specify which user to run the command as (username or UID, defaults to container’s default user)
- `exec_raw`: Array of command arguments for direct execution without shell interpretation (alternative to string command)

Example: *Use Drush to rebuild all caches and get a user login link after database import*.

```
hooks:
  post-import-db:
    - exec: drush cache:rebuild
    - exec: drush user:login
```

Example: *Use wp-cli to replace the production URL with development URL in a WordPress project’s database*.

```
hooks:
  post-import-db:
    - exec: wp search-replace https://www.myproductionsite.com http://mydevsite.ddev.site
```

Example: *Use Drush to sanitize a database by removing or obfuscating user data*.

```
hooks:
  post-import-db:
    - exec: drush sql:sanitize
```

Example: *Add an extra database before `import-db`, executing in `db` container*.

```
hooks:
  pre-import-db:
    - exec: mysql -uroot -proot -e "CREATE DATABASE IF NOT EXISTS some_new_database;"
      service: db
```

Example: *Execute a command as root user in the `db` container*.

```
hooks:
  post-start:
    - exec: ls -la /root
      service: db
      user: root
```

Example: *Add the common `ll` alias into the `web` container’s `.bashrc` file*.

```
hooks:
  post-start:
    - exec: sudo echo alias ll=\"ls -lhA\" >> ~/.bashrc
```

> [!TIP]
>
> This could be done more efficiently via `.ddev/web-build/Dockerfile` as explained in [Customizing Images](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/index.md>).

Advanced usages may require running commands directly with explicit arguments. This approach is useful when Bash interpretation is not required (no environment variables, no redirection, etc.).

```
hooks:
  post-start:
    - exec:
      exec_raw: [ls, -lR, /var/www/html]
```

### `exec-host`: Execute a shell command on the host system

Value: string providing the command to run. Commands requiring user interaction are not supported.

```
hooks:
  pre-start:
    - exec-host: "command to run"
```

### `composer`: Execute a Composer command in the web container

Value: string providing the Composer command to run.

**Optional keys:**

- `exec_raw`: Array of Composer command arguments (alternative to string command)

Example:

```
hooks:
  post-start:
    - composer: config discard-changes true
```

Example with `exec_raw`:

```
hooks:
  post-start:
    - composer:
      exec_raw: [install, --no-dev]
```

## WordPress Example

```
hooks:
  post-start:
    # Install WordPress after start
    - exec: "wp config create --dbname=db --dbuser=db --dbpass=db --dbhost=db"
    - exec: "wp core install --url=http://mysite.ddev.site --title=MySite --admin_user=admin --admin_email=admin@mail.test"
  post-import-db:
    # Update the URL of your project throughout your database after import
    - exec: "wp search-replace https://www.myproductionsite.com http://mydevsite.ddev.site"
```

## Drupal 7 Example

```
hooks:
  post-start:
    # Install Drupal after start if not installed already
    - exec: "(drush status bootstrap | grep -q Successful) || drush site-install -y --db-url=db:db@db/db"
    # Generate a one-time login link for the admin account
    - exec: "drush uli"
  post-import-db:
    # Set the project name
    - exec: "drush vset site_name MyDevSite"
    # Enable the environment indicator module
    - exec: "drush en -y environment_indicator"
    # Clear the cache
    - exec: "drush cc all"
```

## Drupal 10 Example

```
hooks:
  post-start:
    # Install Composer dependencies from the web container
    - composer: install
    # Generate a one-time login link for the admin account
    - exec: "drush user:login"
  post-import-db:
    # Sanitize the database
    - exec: "drush sql:sanitize"
    # Apply any database updates
    - exec: "drush updatedb"
    # Rebuild all caches
    - exec: "drush cache:rebuild"
```

## TYPO3 Example

```
hooks:
  post-start:
    - composer: install
```

# Extending

# Additional Project Hostnames

You can add hostnames to a project by editing its [config file](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#additional_hostnames>) or using the [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) command.

Use the `additional_hostnames` array in `.ddev/config.yaml`:

```
name: mysite

additional_hostnames:
  - "extraname"
  - "fr.mysite"
  - "es.mysite"
  - "it.mysite"
  - "*.lotsofnames"
```

This configuration would result in working hostnames of `mysite.ddev.site`, `extraname.ddev.site`, `fr.mysite.ddev.site`, `es.mysite.ddev.site`, and `it.mysite.ddev.site`, with full HTTP and HTTPS URLs for each.

You could accomplish the same thing by running the `ddev config` command:

```
ddev config --additional-hostnames extraname,fr.mysite,es.mysite,it.mysite,*.lotsofnames
```

In addition, the wildcard `*.lotsofnames` will result in anything `*.lotsofnames.ddev.site` being recognized by the project. This works only if you’re connected to the internet, using `ddev.site` for your top-level-domain, and using DNS for name lookups. (These are all the defaults.)

**Although we recommend extreme care with this feature**, you can also provide `additional_fqdns` entries, which don’t use the `.ddev.site` top-level domain. **This feature populates your hosts file with entries which may hide the real DNS entries on the internet, causing way too much head-scratching.**

**If you use a FQDN which is resolvable on the internet, you must use `use_dns_when_possible: false` or configure that with `ddev config --use-dns-when-possible=false`.**

```
name: somename

additional_fqdns:
- example.com
- somesite.example.com
- anothersite.example.com
```

This configuration would result in working FQDNs of `somename.ddev.site`, `example.com`, `somesite.example.com`, and `anothersite.example.com`.

> [!WARNING]
>
> **Don’t use the same `additional_fqdns` or `additional_hostnames` in two different projects.**
>
> If you see `ddev-router` status become unhealthy in [`ddev list`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#list>), it’s most often a result of trying to use conflicting FQDNs in more than one project. `example.com` can only be assigned to one project, or it will break `ddev-router`.

> [!WARNING]
>
> **May not work predictably everywhere.**
>
> This may not work predictably on all systems. There are operating systems and machines where `/etc/hosts` may not be the first or only resolution technique, especially if the `additional_fqdns` you use is also in DNS.

> [!WARNING]
>
> **Don’t override a real domain name!**
>
> If you use an `additional_fqdns` that exists on the internet (like `www.google.com`), your hosts file will override access to the original (internet) site, and you’ll be sad and confused that you can’t get to it.

# Additional Service Configurations &amp; Add-ons

DDEV projects can be extended using add-ons or custom Docker Compose services.

## DDEV Add-ons (Recommended)

Add-ons are pre-packaged extensions that provide services with automatic installation and configuration.

**See [Using Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>) for:**

- Installing add-ons with `ddev add-on get`
- Managing and customizing add-ons
- Official add-on catalog

**See [Creating Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/index.md>) for:**

- Building your own add-ons
- Using PHP or Bash actions
- Publishing and sharing add-ons

## Custom Docker Compose Services

For specialized needs or deep customization, you can create custom services using `docker-compose.*.yaml` files.

**See [Custom Docker Compose Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/index.md>) for:**

- Deciding when a custom service makes more sense than an add-on
- The `x-ddev` extension field and a gallery of worked examples
- Converting services to add-ons

**See [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>) for:**

- How DDEV merges `docker-compose.*.yaml` files
- Required conventions: labels, container naming, the `build:`/`-built` tag pattern, port exposure

## Resources

- **[DDEV Add-on Registry](<https://addons.ddev.com/>)** - Browse and discover add-ons
- **[DDEV Add-on Template](<https://github.com/ddev/ddev-addon-template>)** - Template for creating add-ons

# Creating DDEV Add-ons

DDEV add-ons provide a powerful way to extend development environments. You can create add-ons using traditional Bash actions or the new PHP-based actions for complex configuration processing.

## Quick Start

1. Use the [`ddev-addon-template`](<https://github.com/ddev/ddev-addon-template>) repository
2. Click “Use this template” to create your own repository
3. Customize the `install.yaml` file - see the [example](<https://github.com/ddev/ddev-addon-template/blob/main/install.yaml>)
4. Add the [`#ddev-generated`](<#the-ddev-generated-comment>) comment to all files installed by the add-on
5. Test with [Bats](<#bats-testing-framework>)
6. Create a release when ready
7. If you expect to support and maintain the add-on, add the `ddev-get` [topic](<https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics>) to the add-on’s GitHub repository. This helps developers find the add-on and encourages reporting issues and feedback.

See this [screencast](<https://www.youtube.com/watch?v=fPVGpKGr0f4>) for a walkthrough.

## Add-on Structure

Every add-on requires an `install.yaml` file with these sections:

```
name: my-addon
pre_install_actions: []
project_files: []
global_files: []
post_install_actions: []
removal_actions: []
```

### Core Sections

- **`name`**: The add-on name used in `ddev add-on` commands
- **`pre_install_actions`**: Scripts executed before files are copied
- **`project_files`**: Files copied to the project’s `.ddev` directory
- **`global_files`**: Files copied to the [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)
- **`post_install_actions`**: Scripts executed after files are copied
- **`removal_actions`**: Scripts executed when removing the add-on. Use these to clean up files that don’t carry `#ddev-generated` (e.g. files placed outside `.ddev/`, or files the user may have modified).

  ```
  removal_actions:
    - |
      #ddev-description: Remove generated settings file if unmodified
      if [ -f "${DDEV_APPROOT}/${DDEV_DOCROOT}/sites/default/settings.ddev.myservice.php" ]; then
        if grep -q '#ddev-generated' "${DDEV_APPROOT}/${DDEV_DOCROOT}/sites/default/settings.ddev.myservice.php"; then
          rm -f "${DDEV_APPROOT}/${DDEV_DOCROOT}/sites/default/settings.ddev.myservice.php"
        else
          echo "Skipping removal: settings.ddev.myservice.php has been modified."
        fi
      fi
  ```

### Advanced Sections

- **`ddev_version_constraint`**: Minimum DDEV version required
- **`dependencies`**: Other add-ons this add-on depends on
- **`yaml_read_files`**: YAML files to read for template processing

## Action Types: Bash vs PHP

### Traditional Bash Actions

Bash actions run directly on the host system and are suitable for:

- File permissions and system commands
- Environment setup and package installation
- Direct command execution
- Simple file operations

```
name: bash-example

post_install_actions:
  - |
    #ddev-description: Configure project settings
    echo "Setting up project: $DDEV_PROJECT"
    chmod +x .ddev/commands/web/mycommand
```

### PHP-based Actions ✨ **NEW**

PHP actions provide powerful capabilities for:

- Complex data processing and YAML manipulation
- Conditional logic based on project configuration
- Cross-platform compatibility
- File content generation and template processing

#### Why Use PHP Actions?

- **Better YAML processing** with the built-in php-yaml extension
- **Cross-platform compatibility** (no shell scripting differences)
- **Rich string manipulation** and data processing capabilities
- **Access to DDEV project configuration** through environment variables
- **Familiar syntax** for developers working with PHP projects

#### Basic PHP Action

```
name: php-example

post_install_actions:
  - |
    <?php
    #ddev-description: Process project configuration

    // Access DDEV environment variables
    $projectName = $_ENV['DDEV_PROJECT'];
    $projectType = $_ENV['DDEV_PROJECT_TYPE'];
    $docroot = $_ENV['DDEV_DOCROOT'];

    echo "Setting up $projectType project: $projectName\n";

    // Generate YAML configuration
    $config = [
        'services' => [
            'myservice' => [
                'image' => 'nginx:latest',
                'environment' => [
                    'PROJECT_TYPE' => $projectType
                ]
            ]
        ]
    ];

    file_put_contents('docker-compose.myservice.yaml',
        "#ddev-generated\n" . yaml_emit($config));
    ?>
```

#### Available Environment Variables

PHP actions have access to all standard DDEV environment variables:

```
<?php
// Project Information
$_ENV['DDEV_PROJECT']        // Project name
$_ENV['DDEV_PROJECT_TYPE']   // 'drupal', 'wordpress', 'laravel', etc.
$_ENV['DDEV_APPROOT']        // '/var/www/html' (project root)
$_ENV['DDEV_DOCROOT']        // 'web', 'public', or configured docroot
$_ENV['DDEV_TLD']            // 'ddev.site' or configured TLD

// Technology Stack  
$_ENV['DDEV_PHP_VERSION']    // '8.1', '8.2', '8.3', etc.
$_ENV['DDEV_WEBSERVER_TYPE'] // 'nginx-fpm', 'apache-fpm'
$_ENV['DDEV_DATABASE']       // 'mysql:8.0', 'postgres:16', etc.
$_ENV['DDEV_DATABASE_FAMILY'] // 'mysql', 'postgres'

// System Information
$_ENV['DDEV_VERSION']        // Current DDEV version
$_ENV['DDEV_MUTAGEN_ENABLED'] // 'true' or 'false'
?>
```

#### PHP Action Execution Environment

PHP actions run **inside a temporary container**, unlike Bash actions which run on the host.

- **Working directory**: `/var/www/html/.ddev` (your project’s .ddev directory)
- **Project access**: Full read/write access to project repository at `/var/www/html/`
- **Error handling**: Automatic strict error handling (equivalent to Bash `set -eu`)
- **Extensions**: php-yaml extension for robust YAML processing

#### Advanced PHP Example: Conditional Configuration

```
name: conditional-config

pre_install_actions:
  - |
    <?php
    #ddev-description: Generate environment-specific configuration

    $projectType = $_ENV['DDEV_PROJECT_TYPE'];
    $services = [];

    // Different services based on project type
    switch($projectType) {
        case 'drupal':
            $services['redis'] = [
                'image' => 'redis:7-alpine',
                'ports' => ['6379:6379']
            ];
            break;
        case 'wordpress':
            $services['memcached'] = [
                'image' => 'memcached:alpine', 
                'ports' => ['11211:11211']
            ];
            break;
        default:
            $services['cache'] = [
                'image' => 'nginx:alpine'
            ];
    }

    $composeContent = ['services' => $services];
    file_put_contents('docker-compose.conditional.yaml',
        "#ddev-generated\n" . yaml_emit($composeContent));

    echo "Generated configuration for $projectType project\n";
    ?>
```

#### Separate PHP Script Files (Best Practice)

For complex logic, create separate PHP script files using your add-on’s namespace:

**File structure:**

```
.ddev/
├── install.yaml
└── myservice/
    └── scripts/
        ├── setup.php
        └── configure.php
```

**Clean install.yaml:**

```
name: myservice

project_files:
  - myservice/scripts/setup.php
  - myservice/scripts/configure.php

post_install_actions:
  - |
    <?php
    #ddev-description: Configure project
    require 'myservice/scripts/setup.php';
  - |
    <?php
    #ddev-description: Apply optimizations
    require 'myservice/scripts/configure.php';
```

**`myservice/scripts/setup.php`:**

```
<?php
#ddev-generated

$projectType = $_ENV['DDEV_PROJECT_TYPE']; 
$docroot = $_ENV['DDEV_DOCROOT'];

// Exit early if not applicable
if ($projectType !== 'drupal') {
    echo "Not a Drupal project, skipping\n";
    exit(0);
}

// Perform Drupal-specific setup
$settingsFile = "/var/www/html/{$docroot}/sites/default/settings.ddev.php";
$settings = "<?php\n// DDEV-generated settings\n";
file_put_contents($settingsFile, $settings);

echo "Drupal settings configured\n";
```

#### Real-world example: ddev-redis structure

```
.ddev/
├── install.yaml
├── docker-compose.redis.yaml
└── redis/
    └── scripts/
        ├── setup-drupal-settings.php
        ├── setup-redis-optimized-config.php
        └── settings.ddev.redis.php
```

#### Mixed Bash and PHP Actions

You can combine both approaches in a single add-on:

```
name: mixed-actions

pre_install_actions:
  - |
    #ddev-description: Set file permissions
    chmod +x .ddev/commands/web/mycommand

  - |
    <?php
    #ddev-description: Process configuration
    $projectName = $_ENV['DDEV_PROJECT'];
    echo "Processing config for: $projectName\n";
    ?>
```

## Advanced Features

### Customizing `ddev describe` Output

Add-ons can customize what appears in `ddev describe` using `x-ddev.describe-*` extensions in your docker-compose file (requires DDEV v1.24.10+):

```
services:
  myservice:
    image: myimage:latest
    x-ddev:
      describe-url-port: "https://${DDEV_HOSTNAME}:8080"
      describe-info: "API key: ${MYSERVICE_API_KEY}"
```

See [Customizing ddev describe output](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/#customizing-ddev-describe-output>) for full details, and the [`x-ddev` Extension](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/#x-ddev-extension>) for all supported keys.

### Minor Docker Image Customization

For small tweaks to an existing image, use `dockerfile_inline` instead of maintaining a separate `Dockerfile`:

```
services:
  myservice:
    image: myimage:latest
    build:
      dockerfile_inline: |
        FROM myimage:latest
        RUN apt-get update && apt-get install -y mypackage
```

### Tools That Update Themselves

If your add-on installs a tool in the web image and the tool updates itself, the update is lost at the next `ddev restart`, and users fall back to the slow `ddev restart --no-cache`. Use one of these approaches instead. Either way, keep the tool’s configuration and credentials apart from the program, as described in [Persisting Changes Across Restarts](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-changes-across-restarts>).

#### Keep the Tool in `ddev-global-cache`

Install the tool at build time as the web container’s user, not as `root`. The script below can’t move files owned by `root`, so it would leave the tool in the home directory and its updates wouldn’t be kept. Switch users around the install, as in [Installing into the home directory](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#installing-into-the-home-directory>):

```
# .ddev/web-build/Dockerfile.mytool
#ddev-generated
USER $username
RUN curl -fsSL https://example.com/mytool/install.sh | bash
USER root
```

Then add a `web-entrypoint.d/mytool.sh` script to `project_files`. It’s the script from [Persisting Home Subdirectories in `ddev-global-cache`](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-home-subdirectories-in-ddev-global-cache>) with one change: `cp -an` adds files from a newer image but never replaces the stored ones, so the tool’s own updates are kept. This example is for a tool installed in `~/.mytool`:

```
# .ddev/web-entrypoint.d/mytool.sh
#ddev-generated
# Keep mytool in ddev-global-cache so its own updates survive restarts.
# cp -n adds files from a newer image but keeps the stored ones.
(
  for dir in .mytool; do
    target="/mnt/ddev-global-cache/mytool/${HOSTNAME}/${dir}"
    mkdir -p "${target}" "$(dirname ~/"${dir}")" &&
      if [ -d ~/"${dir}" ] && [ ! -L ~/"${dir}" ]; then
        cp -an ~/"${dir}"/. "${target}"/ && rm -rf ~/"${dir}"
      fi &&
      ln -sfn "${target}" ~/"${dir}" ||
      echo "mytool.sh: unable to keep ~/${dir}" >&2
  done
)
```

The first start copies the tool from the image, and after that the tool’s updater writes to the volume. Starting needs no network, and `ddev delete` removes the copy. Keep `${HOSTNAME}` directly under your add-on’s directory, because `ddev delete` doesn’t look deeper. Only keep directories that belong to your tool: if two add-ons link a shared directory like `~/.local/bin`, the last one wins. [ddev-nvm](<https://github.com/ddev/ddev-nvm>) also keeps `~/.nvm` in `ddev-global-cache/nvm_dir/${HOSTNAME}`, but it copies from the image only on the first start, so a newer image doesn’t add anything.

To go back to the version in the image, users can run:

```
ddev exec 'rm -rf /mnt/ddev-global-cache/mytool/${HOSTNAME}'
ddev restart
```

#### Pin the Version

Set the version in an `ARG` and release a new add-on version for each tool update. After `ddev add-on get`, a plain `ddev restart` [rebuilds only from that step on](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#rebuilding-only-what-changed>). Turn off the tool’s own updater, because its updates would be lost.

### Environment Variables

Users configure an add-on through the [env files](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) named after it, so `.ddev/.env.myaddon` reaches the `myaddon` service and, with DDEV v1.25.4+, the add-on’s own install actions as well.

To add variables to a service you don’t own, such as `web`, use a labeled file named after your add-on:

```
ddev dotenv set .ddev/.env.web.myaddon --api-url=https://example.com
```

That reaches the `web` container, and two add-ons doing this leave each other’s file alone, which is not the case when both write `.ddev/.env.web`.

Ask for a token or any other secret in a `.local` file, like `.ddev/.env.myaddon.local`, which DDEV keeps out of Git.

> [!WARNING]
>
> **Require v1.25.4 for labeled and `.local` files**
>
> Older DDEV versions don’t raise an error on `.ddev/.env.<service>.<label>` or `.local` files, they simply never read them, so the add-on installs cleanly and misbehaves later. If yours ships or reads one, say so in `install.yaml`:
>
> ```
> ddev_version_constraint: '>= v1.25.4'
> ```

### Version Constraints

Specify minimum DDEV version requirements:

```
ddev_version_constraint: '>= v1.25.2'
```

### Dependencies

Declare add-on dependencies that will be automatically installed:

```
dependencies:
  - ddev/ddev-redis        # GitHub repository
  - https://example.com/addon.tar.gz  # Direct tarball URL
```

Dependencies are automatically installed when the add-on is installed. If a dependency is missing, DDEV will:

1. **Automatically install it** using the same formats supported by `ddev add-on get`
2. **Detect circular dependencies** and prevent infinite loops
3. **Install recursively** - dependencies of dependencies are also installed

To skip automatic dependency installation, use the `--skip-deps` flag:

```
ddev add-on get --skip-deps my-addon
```

This does not install dependencies. Ensure required dependencies are present if your add-on relies on them.

### Runtime Dependencies (Advanced)

> [!WARNING]
>
> **Advanced Feature**
>
> Runtime dependencies are an advanced, rarely-used feature for sophisticated add-ons that need to dynamically discover dependencies during installation. Most add-ons should use static `dependencies` declared in `install.yaml` instead.

Runtime dependencies allow add-ons to **dynamically discover and install dependencies** during the installation process, rather than declaring them statically. This enables complex scenarios like:

- **Service detection** - Analyzing project configuration to determine needed services
- **Conditional dependencies** - Installing different add-ons based on project analysis
- **Dynamic configuration processing** - Dependencies determined by parsing external files

#### How Runtime Dependencies Work

1. **Detection Phase**: During pre-install or post-install actions, your add-on analyzes the project
2. **Creation Phase**: Your add-on creates a `.runtime-deps-<addon-name>` file listing discovered dependencies
3. **Processing Phase**: After installation completes, DDEV automatically processes runtime dependencies
4. **Installation Phase**: DDEV installs any missing dependencies and cleans up the runtime dependencies file

#### Creating Runtime Dependencies

Create a `.runtime-deps-<addon-name>` file in the project’s `.ddev` directory with one dependency per line:

##### Example: Dynamic service detection in post-install action

```
name: my-dynamic-addon

post_install_actions:
  - |
    <?php
    #ddev-description: Detect required services dynamically

    $services = [];

    // Analyze project configuration
    if (file_exists('/var/www/html/.platform.yaml')) {
        $config = yaml_parse_file('/var/www/html/.platform.yaml');

        // Check for Redis usage
        if (isset($config['services']['cache']['type']) && 
            strpos($config['services']['cache']['type'], 'redis') !== false) {
            $services[] = 'ddev/ddev-redis';
        }

        // Check for Elasticsearch usage
        if (isset($config['services']['search']['type']) && 
            strpos($config['services']['search']['type'], 'elasticsearch') !== false) {
            $services[] = 'ddev/ddev-elasticsearch';
        }
    }

    // Create runtime dependencies file if services were found
    if (!empty($services)) {
        $runtimeDepsFile = '.runtime-deps-my-dynamic-addon';
        file_put_contents($runtimeDepsFile, implode("\n", $services) . "\n");
        echo "Created runtime dependencies for " . count($services) . " service(s)\n";
    }
    ?>
```

#### Runtime Dependencies File Format

The `.runtime-deps-<addon-name>` file uses the same dependency formats as static dependencies:

```
# One dependency per line
ddev/ddev-redis
ddev/ddev-elasticsearch
https://example.com/addon.tar.gz

# Comments and empty lines are ignored
```

#### Processing Timing

Runtime dependencies are processed **after all installation phases complete**:

1. Pre-install actions execute
2. Project files are copied
3. Global files are copied
4. Post-install actions execute
5. **Runtime dependencies are processed** ← This happens last
6. Cleanup occurs

This timing ensures that:

- Add-ons can analyze the fully installed project state
- Post-install actions can create runtime dependencies based on project configuration
- Dependencies have access to all project files when they install

#### Real-world Example: Upsun Integration

The [ddev-upsun](<https://github.com/ddev/ddev-upsun>) add-on demonstrates runtime dependencies by:

1. **Analyzing** `.upsun/config.yaml` during post-install
2. **Detecting** services like Redis, Elasticsearch, Memcached
3. **Creating** runtime dependencies for corresponding DDEV add-ons
4. **Automatically installing** the required service add-ons

```
<?php
// Simplified example from ddev-upsun
$detectedServices = analyzeUpsunConfig('/var/www/html/.upsun/config.yaml');
$dependencies = [];

foreach ($detectedServices as $service) {
    switch ($service['type']) {
        case 'redis':
            $dependencies[] = 'ddev/ddev-redis';
            break;
        case 'opensearch':
            $dependencies[] = 'ddev/ddev-opensearch';
            break;
    }
}

if (!empty($dependencies)) {
    file_put_contents('.runtime-deps-upsun', implode("\n", $dependencies));
}
?>
```

#### When NOT to Use Runtime Dependencies

**Use static `dependencies` instead if:**

- Dependencies are always required
- Dependencies don’t change based on project analysis
- You want simpler, more predictable behavior

**Use runtime dependencies only if:**

- Dependencies must be determined by analyzing project files
- Different projects need different dependencies
- You’re integrating with external platform configurations

#### Debugging Runtime Dependencies

Add verbose logging to debug runtime dependency processing:

```
ddev add-on get --verbose your-addon
```

This will show:

- When runtime dependencies files are created
- What dependencies are discovered
- Installation progress for each dependency

#### Limitations

- Runtime dependencies cannot create circular dependency loops
- The `.runtime-deps-*` file is automatically deleted after processing
- Runtime dependencies are not processed when using `--skip-deps`
- Cannot be used to conditionally install the add-on itself

### Template Replacements (Advanced, Very Unusual)

Use environment variables in filenames and content:

```
project_files:
  - "settings.${DDEV_PROJECT}.php"
```

### YAML File Processing

(Using YAML file processing is very unusual.)

`yaml_read_files` reads external YAML files and makes their contents available as Go template variables in **Bash actions**. This is a Go template feature and cannot be used inside PHP actions.

```
yaml_read_files:
  platformapp: ".platform.app.yaml"
  services: ".platform/services.yaml"

post_install_actions:
  - |
    #ddev-description: Configure PHP version from platform config
    cat <<EOF >${DDEV_APPROOT}/.ddev/config.platformsh.yaml
    php_version: {{ trimPrefix "php:" .platformapp.type }}
    EOF
```

### Error Handling

Use proper exit codes and error messages:

```
<?php
#ddev-description: Validate requirements

if (empty($_ENV['DDEV_PROJECT'])) {
    echo "Error: DDEV environment not available\n";
    exit(1);
}

// Continue with setup...
echo "Requirements validated\n";
?>
```

## Special Directives

### The `#ddev-generated` Comment

Add `#ddev-generated` as a comment in any file your add-on creates or copies into a project. DDEV uses this marker to:

1. **Track managed files** - on a subsequent `ddev add-on get`, DDEV replaces the file automatically if it contains `#ddev-generated`, even if the user has modified it. Files with `#ddev-generated` that are listed in the `project_files` or `global_files` will be automatically removed on `ddev add-on remove` if the `#ddev-generated` is found in the file.
2. **Enable clean removal** - `ddev add-on remove` deletes all files that still contain `#ddev-generated`

Files that do **not** contain this comment are left in place during removal (assumed to be user-modified). The [`removal_actions`](<#core-sections>) section is the place to clean up any such files.

```
# docker-compose.myservice.yaml
#ddev-generated
services:
  myservice:
    image: myimage:latest
```

In PHP actions, include it as the first line of generated files:

```
file_put_contents('docker-compose.myservice.yaml', "#ddev-generated\n" . yaml_emit($config));
```

In JSON files, add it as a property:

```
{
    "#ddev-generated": true
}
```

### Description Display

Add descriptions to your actions:

```
#ddev-description: Installing Redis configuration
```

```
<?php
#ddev-description: Processing project settings
?>
```

### Warning Exit Codes

Treat specific exit codes as warnings instead of errors:

```
post_install_actions:
  - |
    #ddev-warning-exit-code: 2
    #ddev-description: Optional configuration
    some-command-that-might-fail
```

### Interactive Actions

Add `#ddev-interactive` to a Bash action that needs direct terminal input or live output. DDEV runs these actions interactively only when stdin is a terminal and JSON output is disabled. In non-interactive environments, such as CI, DDEV keeps the standard buffered action behavior.

```
post_install_actions:
  - |
    #ddev-description: Configure API credentials
    #ddev-interactive
    if [ "$(ddev dotenv get .ddev/.env.myaddon.local --api-token 2>/dev/null)" = "" ]; then
      read -p "Enter your API token: " TOKEN
      ddev dotenv set .ddev/.env.myaddon.local --api-token="${TOKEN}"
    fi
```

## Testing Your Add-on

### Bats Testing Framework

The add-on template includes a `tests/test.bats` file for testing:

```
#!/usr/bin/env bats

setup() {
  set -eu -o pipefail

  # Override this variable for your add-on:
  export GITHUB_REPO=owner/repo

  # ...
}

health_checks() {
  # Do something useful here that verifies the add-on

  # You can check for specific information in headers:
  run curl -sfI https://${PROJNAME}.ddev.site
  assert_output --partial "HTTP/2 200"
  assert_output --partial "test_header"

  # Or check if some command gives expected output:
  DDEV_DEBUG=true run ddev launch
  assert_success
  assert_output --partial "FULLURL https://${PROJNAME}.ddev.site"
}

@test "install from directory" {
  set -eu -o pipefail
  echo "# ddev add-on get ${DIR} with project ${PROJNAME} in $(pwd)" >&3
  run ddev add-on get "${DIR}"
  assert_success
  run ddev restart -y
  assert_success
  health_checks
}

# bats test_tags=release
@test "install from release" {
  set -eu -o pipefail
  echo "# ddev add-on get ${GITHUB_REPO} with project ${PROJNAME} in $(pwd)" >&3
  run ddev add-on get "${GITHUB_REPO}"
  assert_success
  run ddev restart -y
  assert_success
  health_checks
}
```

Run tests in the add-on root directory:

```
bats ./tests/test.bats --filter-tags '!release'
```

### Manual Testing

1. Create a test DDEV project
2. Install your add-on locally:

```
ddev add-on get /path/to/your/addon
```

1. Verify services start correctly
2. Test configuration options
3. Test removal process

## Publishing Your Add-on

### Repository Setup

1. **Test thoroughly** using the test framework
2. **Create proper releases** with semantic versioning
3. If you expect the add-on to be maintained and useful to others, **add the `ddev-get` [topic](<https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics>)** to your GitHub repository.
4. **Write clear documentation** in your readme
5. **Include examples** and configuration options

### Making it Official

To become an officially supported add-on:

1. Open an issue in the [DDEV repository](<https://github.com/ddev/ddev/issues/new>)
2. Request upgrade to official status
3. Commit to maintaining the add-on
4. Subscribe to repository activity and be responsive

### Keeping Your Add-on Up to Date

The [`ddev-addon-template`](<https://github.com/ddev/ddev-addon-template>) evolves over time - workflows, test scripts, tooling, and other components get updated. Run the [`ddev utility addon-update-checker`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-addon-update-checker>) command regularly from your add-on directory (or a workspace containing multiple add-ons) to check whether your add-on is up to date with the template and current best practises:

```
ddev utility addon-update-checker
```

### Best Practices

- **Follow semantic versioning** for releases
- **Maintain backward compatibility** when possible
- **Test with different DDEV versions**
- **Update dependencies regularly** - use `ddev utility addon-update-checker` to keep scripts and tooling in sync with the template
- **Respond to user issues promptly**
- **Keep documentation up to date**
- **Use namespaced directories** (e.g., `myservice/scripts/` not just `scripts/`)
- **Expect changes inside the container to be lost on restart**, see [Tools That Update Themselves](<#tools-that-update-themselves>)

## Examples and References

- **Add-on Template**: [ddev-addon-template](<https://github.com/ddev/ddev-addon-template>)
- **Official Add-ons**: Browse examples at [addons.ddev.com](<https://addons.ddev.com/>)
- **Redis Add-on**: [ddev-redis](<https://github.com/ddev/ddev-redis>) - Example of add-on with `removal_actions` and namespaced scripts directory

## Getting Help

- **Maintenance Guide**: [DDEV Add-on Maintenance Guide](<https://ddev.com/blog/ddev-add-on-maintenance-guide/>)
- **DDEV Discord**: Join [DDEV Discord](<https://ddev.com/s/discord>) for development support
- **GitHub Issues**: Use [DDEV Issues](<https://github.com/ddev/ddev/issues>) for problems and questions
- **Add-on Trainings**: [DDEV Add-ons: Creating, maintaining, testing](<https://www.youtube.com/watch?v=OtmVJtwsHMg>) (YouTube) and [Advanced Add-On Techniques](<https://ddev.com/blog/advanced-add-on-contributor-training/>)

Creating DDEV add-ons is a powerful way to contribute to the DDEV ecosystem. Whether you use traditional Bash actions or the new PHP-based actions, you can create sophisticated extensions that help developers worldwide.

# Custom Commands

Custom commands can easily be added to DDEV, to be executed on the host or in containers.

This involves adding a Bash script to the project in `.ddev/commands/host`, a specific container in `.ddev/commands/<containername>`, or globally in `$HOME/.ddev/commands` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)).

Example commands in `ddev/commands/*/*.example` can be copied, moved, or symlinked.

For example, [.ddev/commands/host/mysqlworkbench.example](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/global_dotddev_assets/commands/host/mysqlworkbench.example>) can be used to add a `ddev mysqlworkbench` command. Rename it from `mysqlworkbench.example` to `mysqlworkbench`. If you’re on macOS or Linux (or some configurations of Windows) you can `cd .ddev/commands/host && ln -s mysqlworkbench.example mysqlworkbench`.

The [`ddev mysql`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#mysql>) runs the `mysql` client inside the `db` container command using this technique. See the [`ddev mysql` command](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/global_dotddev_assets/commands/db/mysql>).

## Notes for All Command Types

- The command filename is not what determines the name of the command. That comes from the “Usage” doc line (`## Usage: commandname`).
- To confirm that your custom command is available, run `ddev -h` and look for it in the list.

## Host Commands

To provide host commands, place a Bash script in `.ddev/commands/host`. For example, a PhpStorm launcher to make the `ddev phpstorm` command might go in `.ddev/commands/host/phpstorm` with these contents. The `OSTypes` and `HostBinaryExists` annotations are optional, but are useful to prevent the command from showing up if it’s not useful to the user.

```
#!/usr/bin/env bash

## Description: Open PhpStorm with the current project
## Usage: phpstorm
## Example: "ddev phpstorm"
## OSTypes: darwin
## HostBinaryExists: "/Applications/PhpStorm.app"

# Example is macOS-specific, but easy to adapt to any OS
open -a PhpStorm.app ${DDEV_APPROOT}
```

## Container Commands

To provide a command which will execute in a container, add a Bash script to `.ddev/commands/<container_name>`, for example, `.ddev/commands/web/mycommand`. The Bash script will be executed inside the named container. For example, see the [several standard DDEV script-based web container commands](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/global_dotddev_assets/commands/web>).

You can run commands in custom containers as well as standard DDEV `web` and `db` containers. Use the service name, like `.ddev/commands/solr/<command>`. The only catch with a custom container is that your service must mount `/mnt/ddev-global-cache` like the `web` and `db` containers do; the `volumes` section of `docker-compose.<servicename>.yaml` needs:

```
    volumes:
      - ddev-global-cache:/mnt/ddev-global-cache
```

For example, to add a `solrtail` command that runs in a Solr service, add `.ddev/commands/solr/solrtail` with:

```
#!/usr/bin/env bash

## Description: Tail the main solr log
## Usage: solrtail
## Example: ddev solrtail

tail -f /opt/solr/server/logs/solr.log
```

## Global Commands

Global commands work exactly the same as project-level commands, but they need to go in your *global* `.ddev` directory. Your home directory has a `.ddev/commands` in it, where you can add host, web, or db commands.

Changes to the command files in the global `.ddev` directory need a `ddev start` for changes to be picked up by a project, as the global commands are copied to the project on start.

## Shell Command Examples

There are many examples of [global](<https://github.com/ddev/ddev/tree/main/pkg/ddevapp/global_dotddev_assets/commands>) and [project-level](<https://github.com/ddev/ddev/tree/main/pkg/ddevapp/dotddev_assets/commands>) custom/shell commands that ship with DDEV you can adapt for your own use. They can be found in your `$HOME/.ddev/commands/*` directories (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) and in your project’s `.ddev/commands/*` directories. There you’ll see how to provide usage, examples, and how to use arguments provided to the commands. For example, the [`xdebug` command](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/global_dotddev_assets/commands/web/xdebug>) shows simple argument processing and the [launch command](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/global_dotddev_assets/commands/host/launch>) demonstrates flag processing.

## Command Line Completion

If your custom command has a set of pre-determined valid arguments it can accept, you can use the [`AutocompleteTerms`](<#autocompleteterms-annotation>). For command flag completion, use the [`Flags`](<#flags-annotation>) annotation.

For dynamic completion, you can create a separate script with the same name in a directory named `autocomplete`. For example, if your command is in `$HOME/.ddev/commands/web/my-command`, your autocompletion script will be in `$HOME/.ddev/commands/web/autocomplete/my-command`.

When you press tab on the command line after your command, the associated autocomplete script will be executed. The current command line (starting with the name of your command) will be passed into the completion script as arguments. If there is a space at the end of the command line, an empty argument will be included.

For example:

- `ddev my-command <tab>` will pass `my-command` and an empty argument into the autocomplete script.
- `ddev my-command som<tab>` will pass `my-command`, and `som` into the autocomplete script.

The autocomplete script should echo the valid arguments as a string separated by line breaks. You don’t need to filter the arguments by the last argument string (e.g. if the last argument is `som`, you don’t need to filter out any arguments that don’t start with `som`). That will be handled for you before the result is given to your shell as completion suggestions.

## Environment Variables Provided

A number of environment variables are provided to these command scripts. These are generally supported, but please avoid using undocumented environment variables. Useful variables for host scripts are:

- `DDEV_APPROOT`: File system location of the project on the host
- `DDEV_DATABASE`: Database in use, in format `type:version` (example: `mariadb:11.8`)
- `DDEV_DATABASE_FAMILY`: Database “family” (example: `mysql`, `postgres`), useful for database connection URLs
- `DDEV_DOCROOT`: Relative path from approot to docroot
- `DDEV_GID`: Group ID the `web` container runs as
- `DDEV_GLOBAL_DIR`: Path to [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)
- `DDEV_GOARCH`: Architecture (`arm64`, `amd64`)
- `DDEV_GOOS`: Operating system (`windows`, `darwin`, `linux`)
- `DDEV_HOSTNAME`: Comma-separated list of FQDN hostnames
- `DDEV_HOST_DB_PORT`: Localhost port of the database server
- `DDEV_HOST_HTTP_PORT`: Localhost port for HTTP on web server
- `DDEV_HOST_HTTPS_PORT`: Localhost port for HTTPS on web server
- `DDEV_HOST_MAILPIT_PORT`: Localhost port for Mailpit
- `DDEV_HOST_WEBSERVER_PORT`: Localhost port of the web server
- `DDEV_MAILPIT_HTTP_PORT`: Router Mailpit port for HTTP
- `DDEV_MAILPIT_HTTPS_PORT`: Router Mailpit port for HTTPS
- `DDEV_MUTAGEN_ENABLED`: `true` if Mutagen is enabled
- `DDEV_PHP_VERSION`: Current PHP version
- `DDEV_PRIMARY_URL`: Primary project URL
- `DDEV_PRIMARY_URL_PORT`: Port of the primary project URL, defaults to 80 for HTTP and 443 for HTTPS
- `DDEV_PRIMARY_URL_WITHOUT_PORT`: Primary project URL without port
- `DDEV_PROJECT`: Project name, like `d8composer`
- `DDEV_PROJECT_STATUS`: Project status determined from the `web` and `db` services health, like `starting`, `running`, `stopped`, `paused`, or another status returned from Docker, including `healthy`, `unhealthy`, `exited`, `restarting`
- `DDEV_PROJECT_TYPE`: `backdrop`, `drupal`, `typo3`,`wordpress`, etc.
- `DDEV_ROUTER_HTTP_PORT`: Router port for HTTP
- `DDEV_ROUTER_HTTPS_PORT`: Router port for HTTPS
- `DDEV_SCHEME`: Scheme of primary project URL
- `DDEV_SITENAME`: Project name, like `d8composer`
- `DDEV_TLD`: Top-level project domain, like `ddev.site`
- `DDEV_UID`: User ID the `web` container runs as
- `DDEV_USER`: Username the `web` container runs as
- `DDEV_XHGUI_HTTP_PORT`: Router XHGui port for HTTP
- `DDEV_XHGUI_HTTPS_PORT`: Router XHGui port for HTTPS
- `DDEV_WEBSERVER_TYPE`: `nginx-fpm`, `apache-fpm`, `generic`

Useful variables for container scripts are:

- `DDEV_APPROOT`: Absolute path to the project files within the web container
- `DDEV_DATABASE`: Database in use, in format `type:version` (example: `mariadb:11.8`)
- `DDEV_DATABASE_FAMILY`: Database “family” (example: `mysql`, `postgres`), useful for database connection URLs
- `DDEV_DOCROOT`: Relative path from approot to docroot
- `DDEV_FILES_DIR`: *Deprecated*, first directory of user-uploaded files
- `DDEV_FILES_DIRS`: Comma-separated list of directories of user-uploaded files
- `DDEV_GID`: Group ID the `web` container runs as
- `DDEV_HOSTNAME`: Comma-separated list of FQDN hostnames
- `DDEV_MUTAGEN_ENABLED`: `true` if Mutagen is enabled
- `DDEV_PHP_VERSION`: Current PHP version
- `DDEV_PRIMARY_URL`: Primary URL for the project
- `DDEV_PRIMARY_URL_PORT`: Port of the primary project URL, defaults to 80 for HTTP and 443 for HTTPS
- `DDEV_PRIMARY_URL_WITHOUT_PORT`: Primary project URL without port
- `DDEV_PROJECT`: Project name, like `d8composer`
- `DDEV_PROJECT_TYPE`: `backdrop`, `drupal`, `typo3`,`wordpress`, etc.
- `DDEV_ROUTER_HTTP_PORT`: Router port for HTTP
- `DDEV_ROUTER_HTTPS_PORT`: Router port for HTTPS
- `DDEV_SCHEME`: Scheme of primary project URL
- `DDEV_SITENAME`: Project name, like `d8composer`
- `DDEV_TLD`: Top-level project domain, like `ddev.site`
- `DDEV_UID`: User ID the `web` container runs as
- `DDEV_USER`: Username the `web` container runs as
- `DDEV_VERSION`: Version of the currently running `ddev` binary
- `DDEV_WEBSERVER_TYPE`: `nginx-fpm`, `apache-fpm`, `generic`
- `IS_DDEV_PROJECT`: If `true`, PHP is running under DDEV

## Annotations Supported

Custom commands support various annotations in the header for providing additional information to the user.

### `Description` Annotation

`Description` should briefly describe the command in its help message.

Usage: `## Description: <command-description>`

Example: `## Description: my great custom command`

### `Usage` Annotation

`Usage` should explain how to use the command in its help message.

Usage: `## Usage: <command-usage>`

Example: `## Usage: commandname [flags] [args]`

### `Example` Annotation

`Example` should demonstrate how the command might be used. Use `\n` to force a line break.

Usage: `## Example: <command-example>`

Example: `## Example: commandname\ncommandname -h`

### `Aliases` Annotation

If your command should have one or more aliases, add the `Aliases` annotation. Multiple aliases are separated by a comma:

Usage: `## Aliases: <list-of-aliases>`

Example: `## Aliases: cacheclear,cache-clear,cache:clear`

### `Flags` Annotation

> [!NOTE]
>
> **`Error: unknown flag` or `Error: unknown shorthand flag`**
>
> Starting with DDEV v1.24.7, unknown flags are no longer parsed when using the `Flags` annotation. To avoid errors, either list *all* supported flags explicitly or remove the `Flags` annotation.

`Flags` should explain any available flags, including their shorthand when relevant, for the help message. It has to be encoded according the following definition:

If no flags are specified, the command will have its flags parsing disabled. Global flags like `--help` will not work unless the command supports them.

You can still do `ddev help <command>` to see the command’s provided usage help.

Usage: `## Flags: <json-definition>`

This is the minimal usage of a `Flags` definition:

Example: `## Flags: [{"Name":"flag","Usage":"sets the flag option"}]`

Output:

```
Flags:
  -h, --help          help for ddev
      --flag          sets the flag option
```

Multiple flags are separated by a comma:

Example: `## Flags: [{"Name":"flag1","Shorthand":"f","Usage":"flag1 usage"},{"Name":"flag2","Usage":"flag2 usage"}]`

Output:

```
Flags:
  -h, --help          help for ddev
  -f, --flag1         flag1 usage
      --flag2         flag2 usage
```

The following fields can be used for a flag definition:

- `Name`: the name as it appears on command line
- `Shorthand`: one-letter abbreviated flag
- `Usage`: help message
- `Type`: possible values are `bool`, `string`, `int`, `uint` (defaults to `bool`)
- `DefValue`: default value for usage message
- `NoOptDefVal`: default value, if the flag is on the command line without any options
- `Annotations`: used by cobra.Command Bash autocomplete code (see [https://github.com/spf13/cobra/blob/main/site/content/completions/bash.md](<https://github.com/spf13/cobra/blob/main/site/content/completions/bash.md>))

### `AutocompleteTerms` Annotation

If your command accepts specific arguments, and you know ahead of time what those arguments are, you can use this annotation to provide those arguments for autocompletion.

Usage: `## AutocompleteTerms: [<list-of-valid-arguments>]`

Example: `## AutocompleteTerms: ["enable","disable","toggle","status"]`

### `CanRunGlobally` Annotation

This annotation is only available for global host commands.

Use `CanRunGlobally: true` if your global host command can be safely run even if the current working directory isn’t inside a DDEV project.

This will make your command available to run regardless of what your current working directory is when you run it.

This annotation will have no effect if you are also using one of the following annotations:

- `ProjectTypes`
- `DBTypes`

Example: `## CanRunGlobally: true`

### `ProjectTypes` Annotation

If your command should only be visible for a specific project type, `ProjectTypes` will allow you to define the supported types. This is especially useful for global custom commands. See [Quickstart for many CMSes](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>) for more information about the supported project types. Multiple types are separated by a comma.

Usage: `## ProjectTypes: <list-of-project-types>`

Example: `## ProjectTypes: drupal7,drupal,backdrop`

### `OSTypes` Annotation (Host Commands Only)

If your host command should only run on one or more operating systems, add the `OSTypes` annotation. Multiple types are separated by a comma. Valid types are:

- `darwin` for macOS
- `windows` for Windows
- `linux` for Linux

Usage: `## OSTypes: <list-of-os-types>`

Example: `## OSTypes: darwin,linux`

### `HostBinaryExists` Annotation (Host Commands Only)

If your host command should only run if a particular file exists, add the `HostBinaryExists` annotation.

Usage: `## HostBinaryExists: <path/to/file>`

Example: `## HostBinaryExists: /Applications/Sequel Ace.app`

### `DBTypes` Annotation

If your command should only be available for a particular database type, add the `DBTypes` annotation. Multiple types are separated by a comma. Valid types the available database types.

Usage: `## DBTypes: <type>`

Example: `## DBTypes: postgres`

### `HostWorkingDir` Annotation (Container Commands Only)

If your container command should run from the directory you are running the command in the host, add the `HostWorkingDir` annotation.

Example: `## HostWorkingDir: true`

### `ExecRaw` Annotation (Container Commands Only)

Use `ExecRaw: true` to pass command arguments directly to the container as-is.

For example, when `ExecRaw` is true, `ddev yarn --help` returns the help for `yarn`, not DDEV’s help for the `ddev yarn` command.

We recommend using this annotation for all container commands. The default behavior is retained to avoid breaking existing commands.

Example: `## ExecRaw: true`

### `MutagenSync` Annotation

Use `MutagenSync: true` to ensure [Mutagen](<https://ddev.github.io/ddev/en/stable/users/install/performance/#mutagen>) sync runs before and after the command (where Mutagen is enabled and the project is running).

We recommend using this annotation if your `host` or `web` command can modify, add, or remove files in the project directory.

## Known Windows Issues

### Line Endings

If you’re editing a custom command to be run in a container, it must have LF line endings and not traditional Windows CRLF line endings. Remember that a custom command in a container is a script that must execute in a Linux environment.

### Bash

Commands can’t be executed if DDEV can’t find `bash`. If you’re running inside Git Bash in most any terminal, this shouldn’t be an issue, and DDEV should be able to find `git-bash` if it’s in `C:\Program Files\Git\bin` as well. But if neither of those is true, add the directory of `bash.exe` to your `PATH` environment variable.

# Defining Additional Services with Docker Compose

This page covers how DDEV merges custom `docker-compose.*.yaml` files and the conventions your service definitions should follow (labels, container naming, the `build:`/`-built` tag pattern, port exposure, and more). For guidance on *when* to write a custom service instead of using an add-on, the `x-ddev` extension field, and a gallery of worked examples, see [Custom Docker Compose Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/index.md>).

## Prerequisite

Much of DDEV’s customization ability and extensibility comes from leveraging features and functionality provided by [Docker](<https://docs.docker.com/>) and [Docker Compose](<https://docs.docker.com/compose/overview/>). Some working knowledge of these tools is required in order to customize or extend the environment DDEV provides.

There are [many examples of custom docker-compose files](<https://github.com/ddev/ddev-contrib#additional-services-added-via-docker-composeserviceyaml>). The best examples are in the many available maintained DDEV add-ons.

## Background

Under the hood, DDEV uses a private copy of docker-compose to define and run the multiple containers that make up the local environment for a project. `docker-compose` (also called `docker compose`) supports defining multiple compose files to facilitate sharing Compose configurations between files and projects, and DDEV is designed to leverage this ability.

To add custom configuration or additional services to your project, create `docker-compose` files in the `.ddev` directory. DDEV will process any files with the `docker-compose.*.yaml` naming convention and merge them into a full docker-compose file.

> [!WARNING]
>
> **Don’t modify `.ddev/.ddev-docker-compose-base.yaml` or `.ddev/.ddev-docker-compose-full.yaml`!**
>
> The main docker-compose file is `.ddev/.ddev-docker-compose-base.yaml`, reserved exclusively for DDEV’s use. It’s overwritten every time a project is started, so any edits will be lost. If you need to add configuration, use an additional `.ddev/docker-compose.<whatever>.yaml` file instead.

## `docker-compose.*.yaml` Examples

For most HTTP-based services, use `expose` with `HTTP_EXPOSE` and `HTTPS_EXPOSE` environment variables. This approach allows multiple projects to run simultaneously without port conflicts:

```
services:
  dummy-service:
    container_name: "ddev-${DDEV_SITENAME}-dummy-service"
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    expose:
      - "9999"
    environment:
      - VIRTUAL_HOST=$DDEV_HOSTNAME
      - HTTP_EXPOSE=9998:9999
      - HTTPS_EXPOSE=9999:9999
```

> [!WARNING]
>
> **Avoid using `ports` - it prevents multiple projects from running**
>
> Direct port binding with `ports` should be avoided for most services because it prevents multiple projects with the same service from running simultaneously. Only use `ports` for non-HTTP services that cannot work through the DDEV router.

**Only use `ports` for non-HTTP services** that must bind directly to localhost, such as database connections or other protocols that cannot be routed through HTTP/HTTPS:

```
services:
  special-service:
    ports:
    - "9999:9999"  # Use only when HTTP routing is not possible
```

### Customizing Existing Services

You can also modify existing DDEV services like the `web` container without adding new services. This is useful for adding environment variables, volumes, or build customizations:

```
services:
  web:
    environment:
      - CUSTOM_ENV_VAR=value
    volumes:
      - ./custom-config:/etc/custom-config:ro
```

For more complex customizations, you can add a custom build stage to an existing service:

```
services:
  web:
    build:
      context: .
      dockerfile_inline: |
        FROM ddev-webserver
        RUN apt-get update && apt-get install -y custom-package
        COPY custom-script.sh /usr/local/bin/
```

## Confirming docker-compose Configurations

To better understand how DDEV parses your custom docker-compose files, run `ddev utility compose-config` or review the `.ddev/.ddev-docker-compose-full.yaml` file. This prints the final, DDEV-generated docker-compose configuration when starting your project.

## Conventions for Defining Additional Services

When defining additional services for your project, we recommend following these conventions to ensure DDEV handles your service the same way DDEV handles default services.

- The container name should be `ddev-${DDEV_SITENAME}-<servicename>`. This ensures the auto-generated [Traefik routing configuration](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/#project-traefik-configuration>) matches your custom service, and that commands like `ddev exec -s <servicename>` find it. Since DDEV v1.25.5, DDEV sets this name automatically and replaces any other `container_name`, except on services with more than one replica. Keep `container_name` in your files if they must also work with older DDEV versions.
- Since DDEV v1.25.5, DDEV sets the service’s hostname to `${DDEV_SITENAME}-<servicename>` when you don’t set `hostname` yourself, so the prompt in `ddev ssh -s <servicename>` shows a readable name instead of a container ID.
- Provide containers with required labels:

  ```
  services:
    dummy-service:
      image: ${YOUR_DOCKER_IMAGE:-example/example:latest}
      # These two labels are added automatically since DDEV v1.25.2+
      labels:
        com.ddev.site-name: ${DDEV_SITENAME}
        com.ddev.approot: ${DDEV_APPROOT}
  ```
- When using a custom `build` configuration with `dockerfile_inline` or `Dockerfile`, define the `image` with the `-${DDEV_SITENAME}-<servicename>-built` suffix:

  ```
  services:
    dummy-service:
      image: ${YOUR_DOCKER_IMAGE:-example/example:latest}-${DDEV_SITENAME}-dummy-service-built
      build:
        dockerfile_inline: |
          ARG YOUR_DOCKER_IMAGE="scratch"
          FROM $${YOUR_DOCKER_IMAGE}
          # ...
        args:
          YOUR_DOCKER_IMAGE: ${YOUR_DOCKER_IMAGE:-example/example:latest}
  ```

  DDEV pulls the base image, `example/example:latest`, before the build, so the project can start in [offline mode](<https://ddev.github.io/ddev/en/stable/users/usage/offline/index.md>). The base needs a tag, such as `debian:stable` rather than `debian`. The service name keeps two services built from the same base image from overwriting each other’s image. To pull other images, such as a `FROM` written in the Dockerfile, use [`x-ddev.pull-images`](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/#service-with-a-custom-build>).
- Exposing ports for service: you can expose the port for a service to be accessible as `projectname.ddev.site:portNum` while your project is running. This is achieved by the following configurations for the container(s) being added:

  - Define only the internal port in the `expose` section for docker-compose; use `ports:` only if the port will be bound directly to `localhost`, as may be required for non-HTTP services.
  - To expose a web interface to be accessible over HTTP, define the following environment variables in the `environment` section for docker-compose:

    - `VIRTUAL_HOST=$DDEV_HOSTNAME` You can set a subdomain with `VIRTUAL_HOST=mysubdomain.$DDEV_HOSTNAME`. You can also specify an arbitrary hostname like `VIRTUAL_HOST=extra.ddev.site`.
    - `HTTP_EXPOSE=portNum` The `hostPort:containerPort` convention may be used here to expose a container’s port to a different external port. To expose multiple ports for a single container, define the ports as comma-separated values.
    - `HTTPS_EXPOSE=<exposedPortNumber>:portNum` This will expose an HTTPS interface on `<exposedPortNumber>` to the host (and to the `web` container) as `https://<project>.ddev.site:exposedPortNumber`. To expose multiple ports for a single container, use comma-separated definitions, as in `HTTPS_EXPOSE=9998:80,9999:81`, which would expose HTTP port 80 from the container as `https://<project>.ddev.site:9998` and HTTP port 81 from the container as `https://<project>.ddev.site:9999`.

## Interacting with Additional Services

[`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), and [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) interact with containers on an individual basis.

By default, these commands interact with the `web` container for a project. All of these commands, however, provide a `--service` or `-s` flag allowing you to specify the service name of the container to interact with. For example, if you added a service to provide Apache Solr, and the service was named `solr`, you would be able to run `ddev logs --service solr` to retrieve the Solr container’s logs.

## Third Party Services May Need To Trust `ddev-webserver`

Sometimes a third-party service (defined in a `.ddev/docker-compose.*.yaml` file) needs to consume content from the `ddev-webserver` container. For example, a PDF generator such as [Gotenberg](<https://github.com/gotenberg/gotenberg>) might need to read in-container images or text to generate a PDF, or a testing service might need to read data to perform tests.

By default, a third-party service does not trust DDEV’s `mkcert` certificate authority (CA). In such cases, you have three main options:

- Use plain HTTP between the containers.
- Configure the third-party service to ignore HTTPS/TLS errors.
- Make the third-party service trust DDEV’s CA.

### Option 1: Use HTTP Between Containers

Using HTTP is the simplest solution. For instance, the [`ddev-selenium-standalone-chrome`](<https://github.com/ddev/ddev-selenium-standalone-chrome>) service consumes web content by accessing the `ddev-webserver` over plain HTTP, see [its configuration here](<https://github.com/ddev/ddev-selenium-standalone-chrome/blob/main/config.selenium-standalone-chrome.yaml#L17>). In this case, the `selenium-chrome` container interacts with the `web` container via `http://web` instead of HTTPS.

### Option 2: Ignore TLS Errors

This solution configures the third-party service to ignore certificate errors.  
For example, if it uses cURL, you can disable verification with:

```
curl --insecure https://web
# or
curl --insecure https://<project>.ddev.site
```

### Option 3: Make the Container Trust DDEV’s Certificate Authority

A more advanced solution is to configure the third-party container to trust the same self-signed certificate used by the `ddev-webserver` container:

```
# .ddev/docker-compose.example.yaml
services:
  example:
    container_name: ddev-${DDEV_SITENAME}-example
    # Run `mkcert -install` on container start
    # (choose either this or the `post_start` approach, not both):
    command: "bash -c 'mkcert -install && original-start-command-from-image'"
    # Or run `mkcert -install` on container post_start
    # (choose either this or the `command` approach, not both):
    post_start:
      - command: mkcert -install
    # Add an image and a build stage so we can add `mkcert`, etc.
    # The Dockerfile for the build stage goes in the `.ddev/example/` directory
    image: ${YOUR_DOCKER_IMAGE:-example/example:latest}-${DDEV_SITENAME}-example-built
    build:
      context: example
      args:
        YOUR_DOCKER_IMAGE: ${YOUR_DOCKER_IMAGE:-example/example:latest}
    environment:
      - HTTP_EXPOSE=3001:3000
      - HTTPS_EXPOSE=3000:3000
      - VIRTUAL_HOST=$DDEV_HOSTNAME
    # Adding external_links allows connections to `https://example.ddev.site`,
    # which then can go through `ddev-router`
    # Tip: external_links are not needed anymore in DDEV v1.24.10+
    external_links:
      - ddev-router:${DDEV_SITENAME}.${DDEV_TLD}
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.approot: ${DDEV_APPROOT}
      com.ddev.site-name: ${DDEV_SITENAME}
    restart: 'no'
    volumes:
      - .:/mnt/ddev_config
      # `ddev-global-cache` gets mounted so we have the CAROOT
      # This is required so that the CA is available for `mkcert` to install
      # and for custom commands to work
      - ddev-global-cache:/mnt/ddev-global-cache
```

And the corresponding `Dockerfile`:

```
# .ddev/example/Dockerfile
ARG YOUR_DOCKER_IMAGE="scratch"
FROM $YOUR_DOCKER_IMAGE
# Define CAROOT for mkcert
ENV CAROOT=/mnt/ddev-global-cache/mkcert
# Switch to root if needed (skip if already root)
USER root
# Optionally install sudo if missing
RUN (apt-get update || true) && apt-get install -y --no-install-recommends sudo \
    && rm -rf /var/lib/apt/lists/*
# Allow the `example` user passwordless sudo for `mkcert -install`
RUN mkdir -p /etc/sudoers.d && \
    echo "example ALL=(ALL) NOPASSWD: ALL" > /etc/sudoers.d/example && \
    chmod 0440 /etc/sudoers.d/example
# Install mkcert for the correct architecture
ARG TARGETARCH
RUN mkdir -p /usr/local/bin && \
    curl --fail -JL -s -o /usr/local/bin/mkcert "https://dl.filippo.io/mkcert/latest?for=linux/${TARGETARCH}" && \
    chmod +x /usr/local/bin/mkcert
# Switch back to non-root user
USER example
```

## Matching Container User to Host User

When mounting host directories for file editing, it’s often necessary to align container user permissions with those of the host user. This prevents ownership or permission mismatches when files are created or modified inside the container.

### Option 1: Run as the Host User

The simplest way is to run the container using the same UID and GID as the host user. DDEV automatically provides these values through its [environment variables](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>) `DDEV_UID` and `DDEV_GID`.

```
# .ddev/docker-compose.example.yaml
services:
  example:
    container_name: ddev-${DDEV_SITENAME}-example
    image: ${YOUR_DOCKER_IMAGE:-example/example:latest}
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.approot: ${DDEV_APPROOT}
      com.ddev.site-name: ${DDEV_SITENAME}
    restart: 'no'
    # Run the container as the same user/group as the host
    user: "${DDEV_UID}:${DDEV_GID}"
    volumes:
      - .:/mnt/ddev_config
      - ddev-global-cache:/mnt/ddev-global-cache
      # Mount the project root to /var/www/html inside the container
      - ../:/var/www/html
```

### Option 2: Create Matching User Inside Container

If you need a more sophisticated user setup, similar to what `ddev-webserver` uses, you can create a user inside the container during the build process that matches the host user’s UID and GID.

```
# .ddev/docker-compose.example.yaml
services:
  example:
    container_name: ddev-${DDEV_SITENAME}-example
    image: ${YOUR_DOCKER_IMAGE:-example/example:latest}-${DDEV_SITENAME}-example-built
    build:
      context: example
      args:
        YOUR_DOCKER_IMAGE: ${YOUR_DOCKER_IMAGE:-example/example:latest}
        username: ${DDEV_USER}
        uid: ${DDEV_UID}
        gid: ${DDEV_GID}
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.approot: ${DDEV_APPROOT}
      com.ddev.site-name: ${DDEV_SITENAME}
    restart: 'no'
    # Run the container as the same user/group as the host
    user: "${DDEV_UID}:${DDEV_GID}"
    volumes:
      - .:/mnt/ddev_config
      - ddev-global-cache:/mnt/ddev-global-cache
      # Mount the project root to /var/www/html inside the container
      - ../:/var/www/html
```

And the corresponding `Dockerfile`:

```
# .ddev/example/Dockerfile
ARG YOUR_DOCKER_IMAGE="scratch"
FROM $YOUR_DOCKER_IMAGE
# Switch to root if needed (skip if already root)
USER root
# Accept build arguments for user creation
ARG username
ARG uid
ARG gid
# Ensure tty group exists
RUN getent group tty || groupadd tty
# Create group and user, trying multiple methods for compatibility
RUN (groupadd --gid "$gid" "$username" || groupadd "$username" || true) && \
    (useradd -G tty -l -m -s "/bin/bash" --gid "$username" --comment '' --uid "$uid" "$username" || \
    useradd -G tty -l -m -s "/bin/bash" --gid "$username" --comment '' "$username" || \
    useradd -G tty -l -m -s "/bin/bash" --gid "$gid" --comment '' "$username" || \
    useradd -G tty -l -m -s "/bin/bash" --comment '' "$username")
# Switch to the created user
USER "$username"
```

## Optional Services

Services in named Docker Compose profiles will not automatically be started on `ddev start`. This is useful when you want to define a service that is not always needed, but can be started by an additional command when it is time to use it. In this way, it doesn’t use system resources unless needed. In this example, the `busybox` container will only be started if the `busybox` profile is requested, for example with `ddev start --profiles=busybox`. More than one service can be labeled for a single Docker Compose profile.

> [!TIP]
>
> **Run `ddev start --profiles='*'` to start all defined profiles.**

```
services:
  busybox:
    image: busybox:stable
    command: tail -f /dev/null
    profiles:
      - busybox
    container_name: ddev-${DDEV_SITENAME}-busybox
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
```

`ddev restart --profiles=busybox` restarts the project with the profile started. Once it’s running, `ddev restart --service=busybox` restarts only that service.

An optional service’s image is pulled or built only when its profile starts, so profiles you don’t use don’t slow down `ddev start`. On a running project, a profile whose services only use `image:` starts without touching the other services. A profile with a `build:` service starts with a full `ddev start`, which builds its image using the build cache, so Dockerfile and `.ddev/docker-compose.*.yaml` changes are picked up.

`ddev start --no-cache` and `ddev restart --no-cache` rebuild without the cache the images of the services they start and of any profile whose image was built before, so a profile started later doesn’t run a stale image.

`--profiles` replaces any `COMPOSE_PROFILES` setting. Without `--profiles`, `COMPOSE_PROFILES` in the environment or in `.ddev/.env` selects the profiles started along with the project. A service whose `depends_on` names a service in another profile needs both profiles, for example `ddev start --profiles=first,second`.

# Custom Docker Compose Services

When you need services that aren’t available as DDEV add-ons, or require deep customization beyond what add-ons provide, you can create custom Docker Compose services using `docker-compose.*.yaml` files. For how DDEV merges these files and the conventions your service should follow (labels, container naming, the `build:`/`-built` tag pattern, port exposure), see [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>).

> [!TIP]
>
> **From Custom Services to Add-ons**
>
> Many successful custom services eventually become DDEV add-ons so they can be shared with teams, between projects, or with the broader community. If you find your custom service useful and stable, convert it to an add-on using the [DDEV Add-on Template](<https://github.com/ddev/ddev-addon-template>) and see [Creating Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/index.md>).

## When to Use Custom Services

**Use custom Docker Compose services when:**

- You need a custom or highly specialized service
- You require deep customization of service configuration
- You’re prototyping or experimenting with service configurations
- The service doesn’t justify creating a full add-on yet
- You need tight integration with your specific project setup

**Use add-ons when:**

- An add-on is already available that provides a standard, tested service (Redis, Elasticsearch, Solr)
- You want automatic configuration and setup

See [Using Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>) for pre-built add-ons.

Whichever you choose, the same conventions apply once you have a compose file — see [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#conventions-for-defining-additional-services>).

## Creating Custom Services

A custom service typically runs a container based on a Docker image and provides a specific “service”. It’s defined in a `.ddev/docker-compose.*.yaml`. DDEV automatically processes any files matching this pattern and merges them into the full Compose configuration.

### Basic Service Example

Create `.ddev/docker-compose.myservice.yaml`:

```
services:
  myservice:
    container_name: "ddev-${DDEV_SITENAME}-myservice"
    image: nginx:alpine
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    expose:
      - "8080"
    environment:
      - VIRTUAL_HOST=${DDEV_HOSTNAME}
      - HTTP_EXPOSE=8080:8080
      - HTTPS_EXPOSE=8081:8080
    volumes:
      - ".:/mnt/ddev_config"
```

### Service Configuration Best Practices

Required labels, container naming, restart policy, and HTTP vs. direct port binding are covered in [Conventions for Defining Additional Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#conventions-for-defining-additional-services>) — follow those for every custom service.

#### Volume Mounts

Provide a bind-mount of your `.ddev` directory for configuration access:

```
volumes:
  - ".:/mnt/ddev_config"
```

Mount project files if needed:

```
volumes:
  - "../:/var/www/html:cached"
```

## `x-ddev` Extension

The `x-ddev` extension field lets you customize DDEV behavior per service in your `.ddev/docker-compose.*.yaml` files.

| Key | Description |
| --- | --- |
| [`container-user`](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#changing-the-container-user>) | User that `ddev ssh`, `ddev exec`, and custom commands run as for this service |
| [`describe-info`](<#customizing-ddev-describe-output>) | Text shown in the `INFO` column of `ddev describe` |
| [`describe-url-port`](<#customizing-ddev-describe-output>) | Text shown in the `URL/PORT` column of `ddev describe` |
| [`omit-ddev-labels`](<#omitting-comddev-labels-from-a-service>) | Skip injecting `com.ddev.*` labels onto this service |
| [`pull-images`](<#service-with-a-custom-build>) | Images DDEV pulls before building this service |
| [`ssh-shell`](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#changing-ddev-ssh-shell>) | Shell used by `ddev ssh -s <service>` for this service |

### Customizing `ddev describe` Output

You can use the `x-ddev` extension field in your `.ddev/docker-compose.*.yaml` configuration to customize the output of [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>).

This feature is useful for showing credentials, URLs, or usage notes for custom services.

```
services:
  rabbitmq:
    container_name: "ddev-${DDEV_SITENAME}-rabbitmq"
    image: rabbitmq:3-management-alpine
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    expose:
      - "15672"
    environment:
      - VIRTUAL_HOST=${DDEV_HOSTNAME}
      - HTTP_EXPOSE=15672:15672
      - HTTPS_EXPOSE=15673:15672
      - RABBITMQ_DEFAULT_USER=rabbitmq
      - RABBITMQ_DEFAULT_PASS=rabbitmq
    x-ddev:
      # Can be multi-line block
      describe-info: |
        User: rabbitmq
        Pass: rabbitmq
      # Or single line string
      describe-url-port: "extra help here"
```

- `x-ddev.describe-url-port`: Appears in the `URL/PORT` column when running [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>).
- `x-ddev.describe-info`: Appears in the `INFO` column, making it easy for team members to view relevant service details without checking config files.

> [!TIP]
>
> See related `x-ddev.ssh-shell` and `x-ddev.container-user` configuration for [Changing `ddev ssh` Shell](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#changing-ddev-ssh-shell>) and [Changing the Container User](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#changing-the-container-user>).

### Omitting `com.ddev.*` Labels from a Service

Setting `x-ddev.omit-ddev-labels: true` stops DDEV from injecting `com.ddev.*` labels onto a service.

DDEV normally stamps these labels (like `com.ddev.site-name`) on every service and has `ddev start` wait for the matching containers. That makes `ddev start` fail when a one-shot container exits before the wait completes. Omitting the labels drops the service from that wait, while leaving it in the compose file so `ddev stop`, `ddev poweroff`, and `ddev delete` still tear it down.

```
services:
  # One-shot container: prepares the shared volume, then exits
  init:
    container_name: "ddev-${DDEV_SITENAME}-init"
    image: busybox:stable
    command:
      - sh
      - -c
      - |
        mkdir -p /mnt/assets/cache &&
        chown -R ${DDEV_UID}:${DDEV_GID} /mnt/assets
    volumes:
      - "assets:/mnt/assets"
    x-ddev:
      omit-ddev-labels: true

  # web mounts the same volume
  web:
    volumes:
      - "assets:/mnt/assets"
    depends_on:
      init:
        condition: service_completed_successfully

volumes:
  assets:
```

## Advanced Service Examples

### Service with a Custom Build

If the stock image needs an extra tool or package, add a `build:` section instead of a plain `image:`. Follow the `-${DDEV_SITENAME}-<servicename>-built` tag convention from [Conventions for Defining Additional Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#conventions-for-defining-additional-services>).

Create `.ddev/docker-compose.myservice.yaml`:

```
services:
  myservice:
    container_name: "ddev-${DDEV_SITENAME}-myservice"
    image: ${BASE_IMAGE:-nginx:stable}-${DDEV_SITENAME}-myservice-built
    build:
      dockerfile_inline: |
        ARG BASE_IMAGE="scratch"
        FROM $${BASE_IMAGE}
        RUN apt-get update && apt-get install -y curl
      args:
        BASE_IMAGE: ${BASE_IMAGE:-nginx:stable}
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
```

To pull other images before the build, such as a `FROM` written in the Dockerfile, list them in `x-ddev.pull-images`:

```
services:
  myservice:
    x-ddev:
      pull-images:
        - busybox:stable
```

### SQL Server Database Service

This example shows a custom SQL Server database service, useful when you need a database not natively supported by DDEV.

> [!TIP]
>
> **A maintained add-on already exists**
>
> This example grew into the [`ddev-sqlsrv`](<https://github.com/ddev/ddev-sqlsrv>) add-on. Its `sqlsrv` service skips host `ports:` entirely and is reached only from the `web` container over the Docker network, so it avoids the port conflict noted below — use that pattern instead of the one here unless you specifically need to connect from the host.

Create `.ddev/docker-compose.sqlsrv.yaml`:

```
services:
  sqlsrv:
    container_name: "ddev-${DDEV_SITENAME}-sqlsrv"
    image: mcr.microsoft.com/mssql/server:2022-latest
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    ports:
      - "1433:1433"  # Direct port binding for SQL Server protocol
    environment:
      - SA_PASSWORD=Password123!
      - ACCEPT_EULA=Y
      - MSSQL_PID=Express
    volumes:
      - "sqlsrv-data:/var/opt/mssql"
      - ".:/mnt/ddev_config"
    # Platform specification for ARM64 compatibility
    platform: linux/amd64

volumes:
  sqlsrv-data:
    external: true
    name: "${DDEV_SITENAME}-sqlsrv-data"
```

> [!NOTE]
>
> **Non-HTTP Services Require Direct Port Binding**
>
> SQL Server uses a proprietary protocol that cannot be routed through the DDEV router, so it requires direct `ports` binding. This means only one project can use SQL Server at a time unless you change the port.

### Service with Custom Configuration

> [!TIP]
>
> **A maintained add-on already exists**
>
> This example grew into the [ddev-elasticsearch](<https://github.com/ddev/ddev-elasticsearch>) add-on, which also adds a `healthcheck:` and supports switching Elasticsearch major versions.

Create `.ddev/docker-compose.elasticsearch.yaml`:

```
services:
  elasticsearch:
    container_name: "ddev-${DDEV_SITENAME}-elasticsearch"
    image: elasticsearch:8.11.0
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    expose:
      - "9200"
    environment:
      - VIRTUAL_HOST=${DDEV_HOSTNAME}
      - HTTP_EXPOSE=9200:9200
      - discovery.type=single-node
      - xpack.security.enabled=false
      - "ES_JAVA_OPTS=-Xms512m -Xmx512m"
    volumes:
      - "elasticsearch-data:/usr/share/elasticsearch/data"
      - "./elasticsearch/config/elasticsearch.yml:/usr/share/elasticsearch/config/elasticsearch.yml:ro"

volumes:
  elasticsearch-data:
    external: true
    name: "${DDEV_SITENAME}-elasticsearch-data"
```

### Multi-Service Setup

It’s usually easier and clearer to have a separate `docker-compose.*.yaml` file for each service, but it’s possible to define more than one in a single file.

> [!TIP]
>
> **Maintained add-ons already exist**
>
> These two grew into the [ddev-redis](<https://github.com/ddev/ddev-redis>) and [ddev-memcached](<https://github.com/ddev/ddev-memcached>) add-ons. Neither binds a host port at all, since both are reached only from the `web` container — that’s why `expose:`, not `ports:`, is used below.

Create `.ddev/docker-compose.cache.yaml`:

```
services:
  redis:
    container_name: "ddev-${DDEV_SITENAME}-redis"
    image: redis:7-alpine
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    expose:
      - "6379"

  memcached:
    container_name: "ddev-${DDEV_SITENAME}-memcached"
    image: memcached:alpine
    # These two labels are added automatically since DDEV v1.25.2+
    labels:
      com.ddev.site-name: ${DDEV_SITENAME}
      com.ddev.approot: ${DDEV_APPROOT}
    restart: "no"
    expose:
      - "11211"
```

## Environment Variables and Configuration

DDEV variables such as `${DDEV_SITENAME}` and `${DDEV_APPROOT}` are available for interpolation in your service definitions; see [Environment Variables Provided](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>) for the full list.

### Custom Environment Variables

Define project-specific variables in `.ddev/.env`:

```
MYSERVICE_VERSION=latest
MYSERVICE_MEMORY=512m
```

Then use in your service:

```
services:
  myservice:
    image: myservice:${MYSERVICE_VERSION:-latest}
    environment:
      - MEMORY_LIMIT=${MYSERVICE_MEMORY:-256m}
```

### Service-Specific Environment Files

Use `.ddev/.env.servicename` for service-specific variables:

```
ddev dotenv set .ddev/.env.myservice --memory-limit 1024m --debug-mode true
```

Variables from every `.ddev/.env*` file are available for interpolation here, but only a file named after an existing service sets variables inside that container. See [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) for the file naming rules, the global `$HOME/.ddev/.env*` equivalents, and where to keep a secret.

## Debugging a Custom Service

`ddev logs --service myservice` and `ddev exec --service myservice bash` cover most cases; see [Interacting with Additional Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#interacting-with-additional-services>). To see how DDEV merged your compose files, run `ddev utility compose-config`.

Custom services let you integrate exactly what your project needs, with the potential to evolve into a shareable add-on — see the tip at the top of this page.

# Custom TLS Certificates

It’s possible to use “real” TLS certificates issued by a CA rather than the local-development-oriented `mkcert` command.

1. Obtain a certificate and key from Let’s Encrypt or another source.
2. Install the certificate and key in your project’s `.ddev/custom_certs` directory.
3. The files should be named `<projectname>.crt` and `<projectname>.key`, for example `exampleproj.crt` and `exampleproj.key`.
4. Run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and verify using a browser that you’re using the right certificate.

# Extending and Customizing Environments

DDEV provides several ways to customize and extend project environments.

## Choosing the Right Approach

Different customization needs require different approaches. Use this decision tree to find the best solution:

### 🎯 **Need a service like Redis, Elasticsearch, or Solr?**

→ **Use [DDEV Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>)**

- Pre-built, tested, and maintained
- Automatic installation and configuration
- Easy updates and management
- Cross-platform compatibility

### 🔧 **Need a highly customized or specialized service?**

→ **Use [Custom Docker Compose Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/index.md>)**

- Full control over service configuration
- Custom images and complex setups
- Project-specific requirements
- Can evolve into add-ons later

### ⚙️ **Need to modify existing container behavior?**

→ **Use configuration approaches below:**

- Environment variables
- Custom configuration files (PHP, nginx, Apache)
- Hooks for automation
- Image customization

### 👨‍💻 **Want to create reusable extensions?**

→ **Create [DDEV Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/index.md>)**

- Share with teams and community
- PHP or bash-based actions
- Version management and updates
- Automatic installation flows

## Environment Variables for Containers and Services

See [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) for the `.ddev/.env*` files, their global equivalents, `web_environment`, and the order they override each other in.

## Changing PHP Version

The project’s `.ddev/config.yaml` file defines the PHP version to use. The [`php_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#php_version>) can be any PHP version supported by DDEV.

### Older Versions of PHP

[Support for older versions of PHP (\< 5.6) is available on ddev-contrib](<https://github.com/ddev/ddev-contrib/blob/master/docker-compose-services/old_php>) via [custom docker-compose files](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>).

If your project requires multiple versions of PHP, and one of them is EOL, you can install it using [this technique](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#adding-eol-versions-of-php>).

## Changing Web Server Type

DDEV supports nginx with php-fpm by default (`nginx-fpm`), Apache with php-fpm (`apache-fpm`), and `generic` for [custom web servers](<https://ddev.github.io/ddev/en/stable/users/quickstart/#generic>). You can change this with the [`webserver_type`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webserver_type>) config option, or using the [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) command with the `--webserver-type` flag.

> [!TIP]
>
> **Using FrankenPHP web server**
>
> The `webserver_type: generic` setting allows you to use FrankenPHP as your web server. See the [ddev-frankenphp](<https://github.com/ddev/ddev-frankenphp>) add-on for details.

## Adding Services to a Project

DDEV provides everything you need to build a modern PHP application on your local machine. More complex web applications, however, often require integration with services beyond the usual requirements of a web and database server—maybe Apache Solr, Redis, Varnish, or many others. While DDEV likely won’t ever provide all of these additional services out of the box, it’s designed to provide simple ways to customize the environment and meet your project’s needs without reinventing the wheel.

A collection of vetted service configurations is available in the [Additional Services Documentation](<https://ddev.github.io/ddev/en/stable/users/extend/additional-services/index.md>). For pre-built solutions, see [Using Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>).

If you need to create a service configuration for your project, see [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>).

## Using Node.js with DDEV

There are many ways to deploy Node.js in any project, so DDEV tries to let you set up any possibility you can come up with.

- You can choose any Node.js version you want (including minor and older versions) in `.ddev/config.yaml` with [`nodejs_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#nodejs_version>).
- [`ddev npm`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#npm>) and [`ddev yarn`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#yarn>) provide shortcuts to the `npm` and `yarn` commands inside the container, and their caches are persistent.
- You can run Node.js daemons using [`web_extra_daemons`](<#running-extra-daemons-in-the-web-container>).
- You can expose Node.js ports via `ddev-router` by using [`web_extra_exposed_ports`](<#exposing-extra-ports-via-ddev-router>).
- You can manually run Node.js scripts using [`ddev exec <script>`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) or `ddev exec node <script>`.

> [!TIP]
>
> **Please share your techniques!**
>
> There are several ways to share your favorite Node.js tips and techniques. The best ways are by packaging with [DDEV add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/using-add-ons/index.md>).

### Using Node.js as DDEV’s primary web server

In DDEV v1.24.3+, you can use the `generic` web server type and provide your own web server inside the `web` container. As a result, you can use `webserver_type: generic` and use [`web_extra_daemons`](<#running-extra-daemons-using-web_extra_daemons>) and [`web_extra_exposed_ports`](<#exposing-extra-ports-via-ddev-router>) to provide your own web server. The [Node.js](<https://ddev.github.io/ddev/en/stable/users/quickstart/#nodejs>) quickstart shows how to do this with an Express Node.js server and also with a SvelteKit server.

## Running Extra Daemons in the Web Container

There are several ways to run processes inside the `web` container.

1. Manually execute them as needed, with [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), for example.
2. Run them with a `post-start` [hook](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>).
3. Run them automatically using `web_extra_daemons`.

> [!TIP]
>
> **Daemons requiring network access should bind to `0.0.0.0`, not to `localhost` or `127.0.0.1`**
>
> Many examples on the internet show starting daemons starting up and binding to `127.0.0.1` or `localhost`. Those examples are assuming that network consumers are on the same network interface, but with a DDEV-based solution the network server is essentially on a different computer from the host computer (workstation). If the host computer needs to have connectivity, then bind to `0.0.0.0` (meaning “all network interfaces”) rather than `127.0.0.1` or `localhost` (which means only allow access from the local network). A [ReactPHP example](<https://github.com/orgs/ddev/discussions/5973>) would be:
>
> ```
> $socket = new React\Socket\SocketServer('0.0.0.0:3000');
> ```
>
> instead of:
>
> ```
> $socket = new React\Socket\SocketServer('127.0.0.1:3000');
> ```
>
> To expose your daemon to the workstation and browser, see [Exposing Extra Ports via `ddev-router`](<#exposing-extra-ports-via-ddev-router>).

### Running Extra Daemons with a `post-start` Hook

Daemons can be run with a `post-start` `exec` hook or automatically started using `supervisord`.

A simple `post-start` exec hook in `.ddev/config.yaml` might look like:

```
hooks:
  post-start:
    - exec: "nohup php --docroot=/var/www/html/something -S 0.0.0.0:6666 &"
```

### Running Extra Daemons Using `web_extra_daemons`

If you need extra daemons to start up automatically inside the web container, you can add them using [`web_extra_daemons`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_extra_daemons>) in `.ddev/config.yaml`.

You might be running Node.js daemons that serve a particular purpose, like `browsersync`, or more general daemons like a `cron` daemon.

For example, you could use this configuration to run two instances of the Node.js HTTP server for different directories:

```
web_extra_daemons:
  - name: "http-1"
    command: "/var/www/html/node_modules/.bin/http-server -p 3000"
    directory: /var/www/html
  - name: "http-2"
    command: "/var/www/html/node_modules/.bin/http-server /var/www/html/sub -p 3000"
    directory: /var/www/html
```

> [!TIP]
>
> **How to view the results of a daemon start attempt?**
>
> See [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) or `docker logs ddev-<project>-web`.

- `directory` should be the absolute path inside the container to the directory where the daemon should run.
- `command` is best as a simple binary with its arguments, but Bash features like `cd` or `&&` work. If the program to be run is not in the `ddev-webserver` `$PATH` then it should have the absolute in-container path to the program to be run, like `/var/www/html/node_modules/.bin/http-server`.
- `web_extra_daemons` is a shortcut for adding a configuration to `supervisord`, which organizes daemons inside the web container. If the default settings are inadequate for your use, you can write a [complete config file for your daemon](<#explicit-supervisord-configuration-for-additional-daemons>).
- Your daemon is expected to run in the foreground, not to daemonize itself, `supervisord` will take care of that.
- To debug and/or get your daemon running to begin with, experiment with running it manually inside `ddev ssh`. Then when it works perfectly implement auto-start with `web_extra_daemons`.
- You can manually restart all daemons with `ddev exec supervisorctl restart 'webextradaemons:*'` or `ddev exec supervisorctl restart webextradaemons:<yourdaemon>`. (`supervisorctl stop` and `supervisorctl start` are available as you would expect.)

## Exposing Extra Ports via `ddev-router`

If your `web` container has additional HTTP servers running inside it on different ports, those can be exposed using [`web_extra_exposed_ports`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_extra_exposed_ports>) in `.ddev/config.yaml`. For example, this configuration would expose a `node-vite` HTTP server running on port 3000 inside the `web` container, via `ddev-router`, to ports 9998 (HTTP) and 9999 (HTTPS), so it could be accessed via `https://<project>.ddev.site:9999`:

```
web_extra_exposed_ports:
  - name: node-vite
    container_port: 3000
    http_port: 9998
    https_port: 9999
```

The configuration below would expose a Node.js server running in the `web` container on port 3000 as `https://<project>.ddev.site:3000` and a “something” server running in the web container on port 4000 as `https://<project>.ddev.site:4000`:

```
web_extra_exposed_ports:
  - name: nodejs
    container_port: 3000
    http_port: 2999
    https_port: 3000
  - name: something
    container_port: 4000
    https_port: 4000
    http_port: 3999
```

> [!WARNING]
>
> **Fill in all three fields even if you don’t intend to use the `https_port`!**
>
> If you don’t add `https_port`, then it defaults to `0` and `ddev-router` will fail to start.

## Exposing Extra Non-HTTP Ports

While the `web_extra_exposed_ports` gracefully handles running multiple DDEV projects at the same time, it can’t forward ports for non-HTTP TCP or UDP daemons. Instead, ports can be added in a `docker-compose.*.yaml` file. This file does not need to specify an additional services. For example, this configuration exposes port 5900 for a VNC server.

In `.ddev/docker-compose.vnc.yaml`:

```
services:
  web:
    ports:
      - "5900:5900"
```

If multiple projects declare the same port, only the first project will be able to start successfully. Consider making services like this disabled by default, especially if they aren’t needed in day to day use.

## Custom nginx Configuration

When you run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) using `nginx-fpm`, DDEV creates a configuration customized to your project type in `.ddev/nginx_full/nginx-site.conf`. You can edit and override the configuration by removing the `#ddev-generated` line and doing whatever you need with it. After each change, run `ddev restart`. (For updates without restart, see [Troubleshooting nginx Configuration](<#troubleshooting-nginx-configuration>).)

You can also have more than one config file in the `.ddev/nginx_full` directory, and each will be loaded when DDEV starts. This can be used for [serving multiple docroots](<#multiple-docroots-in-nginx-advanced>) and other techniques.

### Troubleshooting nginx Configuration

- Any errors in your configuration may cause the `web` container to fail and try to restart. If you see that behavior, use [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) to diagnose.
- The configuration is copied into the container during restart. Therefore it is not possible to edit the host file for the changes to take effect. You may want to edit the file directly inside the container at `/etc/nginx/sites-enabled/`. (For example, run [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) to get into the container.)
- You can run `ddev exec nginx -t` to test whether your configuration inside the container is valid. (Or run [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) and run `nginx -t`.)
- You can reload the nginx configuration by running either [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) or editing the configuration inside the container at `/etc/nginx/sites-enabled/` and running `ddev exec nginx -s reload` on the host system (inside the container run `nginx -s reload`).
- The health check script needs the line `include /etc/nginx/monitoring.conf;` in `nginx-site.conf`. It serves `/phpstatus` only to requests from `127.0.0.1` inside the container.

### Multiple Docroots in nginx (Advanced)

It’s easiest to have different web servers in different DDEV projects, and DDEV projects can [easily communicate with each other](<https://ddev.github.io/ddev/en/stable/users/usage/faq/index.md>), but some sites require more than one docroot for a single project codebase. Sometimes this is because there’s an API in the same codebase but using different code, or different code for different languages, etc.

The generated `.ddev/nginx_full/seconddocroot.conf.example` demonstrates how to do this. You can create as many of these as you want: change the `servername` and the `root` and customize as needed.

### nginx Snippets

To add an nginx snippet to the default config, add an nginx config file as `.ddev/nginx/<something>.conf`.

For example, to make all HTTP URLs redirect to their HTTPS equivalents you might add `.ddev/nginx/redirect.conf` with this stanza:

```
    if ($http_x_forwarded_proto = "http") {
      return 301 https://$host$request_uri;
    }
```

After adding a snippet, run `ddev restart` to make it take effect.

## Custom Apache Configuration

If you’re using [`webserver_type: apache-fpm`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webserver_type>) in your `.ddev/config.yaml`, you can override the default site configuration by editing or replacing the DDEV-provided `.ddev/apache/apache-site.conf` configuration.

When you run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) using `apache-fpm`, DDEV creates a configuration customized to your project type in `.ddev/apache/apache-site.conf`. You can edit and override the configuration by removing the `#ddev-generated` line and doing whatever you need with it. After each change, run `ddev restart`.

- Edit the `.ddev/apache/apache-site.conf`.
- Remove the `#ddev-generated` to signal to DDEV that you’re taking control of the file.
- Add your configuration changes.
- Save your configuration file and run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>). If you encounter issues with your configuration or the project fails to start, use [`ddev logs`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#logs>) to inspect the logs for possible Apache configuration errors.
- Use `ddev exec apachectl -t` to do a general Apache syntax check.
- The health check script needs the alias `Alias "/phpstatus" "/var/www/phpstatus.php"` and its `<Location "/phpstatus">` block in `apache-site.conf`. Keep `Require ip 127.0.0.1` in that block: only the health check inside the container needs `/phpstatus`. Other virtual hosts, such as a second docroot, do not need them.
- Any errors in your configuration may cause the `web` container to fail. If you see that behavior, use `ddev logs` to diagnose.

> [!WARNING]
>
> **Important!**
>
> Changes to `.ddev/apache/apache-site.conf` take place on a [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>). You can also `ddev exec apachectl -k graceful` to reload the Apache configuration.

## Custom PHP Configuration (`php.ini`)

You can provide additional PHP configuration for a project by creating a directory called `.ddev/php/` and adding any number of `*.ini` PHP configuration files.

You should generally limit your override to any specific option(s) you need to customize. Every file in `.ddev/php/` will be copied into `/etc/php/[version]/(cli|fpm)/conf.d`, so it’s possible to replace files that already exist in the container. Common usage is to put custom overrides in a file called `my-php.ini`. Make sure you include the section header that goes with each item (like `[PHP]`).

One interesting implication of this behavior is that it’s possible to disable extensions by replacing the configuration file that loads them. For instance, if you were to create an empty file at `.ddev/php/20-xdebug.ini`, it would replace the configuration that loads Xdebug, which would cause Xdebug to not be loaded!

To load the new configuration, run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).

An example file in `.ddev/php/my-php.ini` might look like this:

```
[PHP]
max_execution_time = 240;
```

## Custom MySQL/MariaDB configuration (`my.cnf`)

You can provide additional MySQL/MariaDB configuration for a project by creating a directory called `.ddev/mysql/` and adding any number of `*.cnf` MySQL configuration files. These files will be automatically included when MySQL is started. Make sure that the section header is included in the file.

A common use case is setting the server’s default character set and collation. DDEV automatically replaces modern collations like `utf8mb4_0900_ai_ci` (MySQL 8.0+) and `utf8mb4_uca1400_ai_ci` (MariaDB 11.x) with the server’s `collation-server` value during `ddev import-db`. Setting this explicitly ensures the substitution lands on the collation you expect:

An example file in `.ddev/mysql/utf8mb4.cnf`:

```
[mysqld]
collation-server = utf8mb4_unicode_ci
character-set-server = utf8mb4
```

DDEV already sets `max_allowed_packet` to 256M by default, which covers most cases. If your project works with unusually large BLOBs you can raise it further, though this is rarely needed:

An example file in `.ddev/mysql/max-packet.cnf`:

```
[mysqld]
max_allowed_packet = 512M
```

To load the new configuration, run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).

## Custom PostgreSQL Configuration

If you’re using PostgreSQL, a default `posgresql.conf` is provided in `.ddev/postgres/postgresql.conf`. If you need to alter it, remove the `#ddev-generated` line and [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).

## Extending `config.yaml` with Custom `config.*.yaml` Files

You may add additional `config.*.yaml` files to organize additional commands as you see fit for your project and team.

For example, many teams commit their `config.yaml` and share it throughout the team, but some team members may require overrides to the checked-in version specifically for their environment and not checked in. For example, a team member may want to use a [`router_http_port`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_http_port>) other than the team default due to a conflict in their development environment. In this case they could add `.ddev/config.ports.yaml`:

```
# My machine can’t use port 80 so override with port 8080, but don’t check this in!
router_http_port: 8080
```

Extra `config.*.yaml` files are loaded in lexicographic order, so `config.a.yaml` will be overridden by `config.b.yaml`.

Team members may choose to use `config.local.yaml` for local non-committed config changes, for example. `config.local.yaml` and `config.*.local.yaml` are gitignored by default.

`config.*.yaml` update configuration according to these rules:

1. Simple fields like [`router_http_port`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#router_http_port>) or [`webserver_type`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webserver_type>) are overwritten.
2. Lists of strings like [`additional_hostnames`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#additional_hostnames>) or [`additional_fqdns`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#additional_fqdns>) are merged.
3. The list of environment variables in [`web_environment`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_environment>) are “smart merged”: if you add the same environment variable with a different value, the value in the override file will replace the value from `config.yaml`.
4. Hook specifications in the [`hooks`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#hooks>) variable are merged.

If you need to *override* existing values, set [`override_config: true`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#override_config>) in the `config.*.yaml` where the override behavior should take place. Since `config.*.yaml` files are normally *merged* into the configuration, some things can’t be overridden normally. For example, if you have [`use_dns_when_possible: false`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#use_dns_when_possible>) you can’t override it with a merge and you can’t erase existing hooks or all environment variables. However, with `override_config: true` in a particular `config.*.yaml` file,

```
override_config: true
use_dns_when_possible: false
```

can override the existing values, and

```
override_config: true
hooks:
  post-start: []
```

or

```
override_config: true
additional_hostnames: []
```

can have their intended affect.

[`override_config`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#override_config>) affects only behavior of the `config.*.yaml` file it exists in.

The global `global_config.yaml` can be extended the same way with `global_config.*.yaml` files in the [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>), with the same rules and the same `override_config` behavior.

To experiment with the behavior of a set of `config.*.yaml` files, use the [`ddev utility configyaml`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-configyaml>) file; it’s especially valuable with the `yq` command, for example `ddev utility configyaml | yq`.

## Explicit `supervisord` Configuration for Additional Daemons

Although most extra daemons (like Node.js daemons, etc.) can be configured easily using [web\_extra\_daemons](<#running-extra-daemons-in-the-web-container>), there may be situations where you want complete control of the `supervisord` configuration.

In these case you can create a `.ddev/web-build/<daemonname>.conf` with configuration like:

```
[program:daemonname]
command=/var/www/html/path/to/daemon
directory=/var/www/html/
autorestart=true
startretries=3
stdout_logfile=/proc/1/fd/1
stdout_logfile_maxbytes=0
redirect_stderr=true
```

And create a `.ddev/web-build/Dockerfile.<daemonname>` to install the config file:

```
ADD daemonname.conf /etc/supervisor/conf.d
```

Full details for advanced configuration possibilities are in [Supervisor docs](<http://supervisord.org/configuration.html#program-x-section-settings>).

# Customizing Docker Images

It’s common to have a requirement for the `web` or `db` images which isn’t bundled with them by default. There are two ways to extend these Docker images:

1. `webimage_extra_packages` and `dbimage_extra_packages` in `.ddev/config.yaml`.
2. An add-on Dockerfile in your project’s `.ddev/web-build` or `.ddev/db-build`.

## Adding Extra Debian Packages with `webimage_extra_packages` and `dbimage_extra_packages`

You can add extra Debian packages with lines like this in `.ddev/config.yaml`:

```
# .ddev/config.yaml
webimage_extra_packages: ['php${DDEV_PHP_VERSION}-tidy', 'php${DDEV_PHP_VERSION}-yac']
dbimage_extra_packages: [netcat, telnet, sudo]
```

Then the additional packages will be built into the containers during [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).

## Adding PHP Extensions

### PHP Extensions supported by `deb.sury.org`

If a PHP extension is supported by the upstream package management from `deb.sury.org`, you’ll be able to add it with minimal effort. Test to see if it’s available using `ddev exec '(sudo apt-get update || true) && sudo apt-get install php${DDEV_PHP_VERSION}-<extension>'`, for example, `ddev exec '(sudo apt-get update || true) && sudo apt-get install php${DDEV_PHP_VERSION}-imap'`. If that works, then the extension is supported, and you can add `webimage_extra_packages: ["php${DDEV_PHP_VERSION}-<extension>"]` to your `.ddev/config.yaml` file.

### PIE PHP Extensions not supported by `deb.sury.org`

> [!TIP]
>
> **Few people need PIE or PECL extensions**
>
> Most people don’t need to install PHP extensions that aren’t supported by `deb.sury.org`, so you only need to go down this path if you have very particular needs.

If a PHP extension is not supported by `deb.sury.org`, you can install it with [PIE](<https://github.com/php/pie>) (PHP Installer for Extensions) in a `.ddev/web-build/Dockerfile.*` file. Find the extension’s package name on [packagist.org/extensions](<https://packagist.org/extensions>). (This technique can also be used to get newer versions of PHP extensions than are available in the `deb.sury.org` distribution.)

PIE requires PHP 8.1 or later. For older PHP versions, or an extension that isn’t on Packagist, use [PECL](<#pecl-php-extensions-not-supported-by-debsuryorg>) instead.

For example, this `.ddev/web-build/Dockerfile.brotli` installs [brotli](<https://packagist.org/packages/kjdev/brotli>). To install another extension, change `package`, and list any Debian packages it needs to build in `build_packages`:

```
# .ddev/web-build/Dockerfile.brotli
RUN --mount=type=secret,id=github_token <<EOF
    set -eu -o pipefail
    # Package name, optionally with a version constraint, like kjdev/brotli:^0.21
    package=kjdev/brotli
    # Debian packages needed to build it, like "libmemcached-dev zlib1g-dev"
    build_packages=""
    (apt-get update || true)
    DEBIAN_FRONTEND=noninteractive apt-get install -y \
        -o Dpkg::Options::="--force-confold" \
        --no-install-recommends --no-install-suggests \
        build-essential pkg-config "php${DDEV_PHP_VERSION}-dev" ${build_packages}
    curl -fsSL -o /usr/local/bin/pie \
        https://github.com/php/pie/releases/latest/download/pie.phar
    chmod +x /usr/local/bin/pie
    if [ -s /run/secrets/github_token ]; then
        token=$(cat /run/secrets/github_token)
        export COMPOSER_AUTH="{\"github-oauth\":{\"github.com\":\"${token}\"}}"
    fi
    pie install --with-php-config="/usr/bin/php-config${DDEV_PHP_VERSION}" \
        "${package}"
EOF
```

- `--with-php-config` builds the extension for your project’s PHP version rather than the image’s default one. PIE enables the extension itself.
- For `build_packages`, check the extension’s installation instructions and add the `-dev` packages of the libraries it needs. If the build still fails, the `configure` error names what’s missing, like `memcached support requires ZLIB` for `zlib1g-dev`, and [packages.debian.org](<https://packages.debian.org/>) finds the package that provides a missing file.
- DDEV passes your GitHub token, from `DDEV_GITHUB_TOKEN`, `GH_TOKEN`, or `GITHUB_TOKEN`, as the `github_token` [build secret](<https://docs.docker.com/build/building/secrets/>). PIE reads it from `COMPOSER_AUTH` to avoid GitHub API rate limits. The secret is empty when no token is set. Keep the token in an environment variable of the `RUN` step, as above: writing it to a file would store it in the image.
- `--force-confold` keeps DDEV’s PHP configuration files if installing `php${DDEV_PHP_VERSION}-dev` upgrades the PHP packages.

A `.ddev/web-build/Dockerfile.xdebug` that replaces the `deb.sury.org` Xdebug with one built by PIE might look like this:

```
# .ddev/web-build/Dockerfile.xdebug
RUN --mount=type=secret,id=github_token <<EOF
    set -eu -o pipefail
    (apt-get update || true)
    apt-get remove -y "php${DDEV_PHP_VERSION}-xdebug" || true
    DEBIAN_FRONTEND=noninteractive apt-get install -y \
        -o Dpkg::Options::="--force-confold" \
        --no-install-recommends --no-install-suggests \
        build-essential pkg-config "php${DDEV_PHP_VERSION}-dev"
    curl -fsSL -o /usr/local/bin/pie \
        https://github.com/php/pie/releases/latest/download/pie.phar
    chmod +x /usr/local/bin/pie
    if [ -s /run/secrets/github_token ]; then
        token=$(cat /run/secrets/github_token)
        export COMPOSER_AUTH="{\"github-oauth\":{\"github.com\":\"${token}\"}}"
    fi
    # ddev xdebug enables it with DDEV's own xdebug.ini, so there is no phpenmod
    pie install --with-php-config="/usr/bin/php-config${DDEV_PHP_VERSION}" \
        --skip-enable-extension xdebug/xdebug
EOF
```

### PECL PHP Extensions not supported by `deb.sury.org`

Use PECL for PHP versions older than 8.1, which aren’t supported by PIE, or for an extension release that isn’t published on Packagist. Find the extension’s package name on [pecl.php.net](<https://pecl.php.net/>).

For example, this `.ddev/web-build/Dockerfile.brotli` installs [brotli](<https://pecl.php.net/package/brotli>). To install another extension, change `extension`, and list any Debian packages it needs to build in `build_packages`:

```
# .ddev/web-build/Dockerfile.brotli
RUN <<EOF
    set -eu -o pipefail
    # Package name, optionally with a version, like brotli-0.21.0
    extension=brotli
    # Debian packages needed to build it, like "libmemcached-dev zlib1g-dev"
    build_packages=""
    (apt-get update || true)
    DEBIAN_FRONTEND=noninteractive apt-get install -y \
        -o Dpkg::Options::="--force-confold" \
        --no-install-recommends --no-install-suggests \
        build-essential php-pear "php${DDEV_PHP_VERSION}-dev" ${build_packages}
    # yes '' accepts the default answer to every question pecl asks
    # pecl prints the line that enables the extension, like extension=brotli.so
    ini=$(pecl -d php_suffix="${DDEV_PHP_VERSION}" install "${extension}" \
        < <(yes '') | tee /dev/stderr \
        | grep -o '[a-z_]*extension=[^"]*\.so' | tail -1)
    name=$(basename "${ini#*=}" .so)
    echo "${ini}" > "/etc/php/${DDEV_PHP_VERSION}/mods-available/${name}.ini"
    phpenmod -v "${DDEV_PHP_VERSION}" "${name}"
EOF
```

`-d php_suffix` builds the extension for your project’s PHP version rather than the image’s default one. Find what goes in `build_packages` [the same way as for PIE](<#pie-php-extensions-not-supported-by-debsuryorg>). To answer questions from `pecl` with something other than the defaults, pass them with `--configureoptions`, like `pecl install --configureoptions 'enable-redis-igbinary="yes"' redis`.

To replace an extension that DDEV enables itself, Xdebug with [`ddev xdebug`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>) or XHProf with [`ddev xhprof`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xhprof>), remove the `deb.sury.org` package first. For example, this `.ddev/web-build/Dockerfile.xdebug` pins Xdebug 3.1.6, the last release supporting PHP 7.2 to 7.4:

```
# .ddev/web-build/Dockerfile.xdebug
RUN <<EOF
    set -eu -o pipefail
    # xdebug or xhprof, optionally with a version
    extension=xdebug-3.1.6
    (apt-get update || true)
    apt-get remove -y "php${DDEV_PHP_VERSION}-${extension%%-*}" || true
    DEBIAN_FRONTEND=noninteractive apt-get install -y \
        -o Dpkg::Options::="--force-confold" \
        --no-install-recommends --no-install-suggests \
        build-essential php-pear "php${DDEV_PHP_VERSION}-dev"
    pecl -d php_suffix="${DDEV_PHP_VERSION}" install "${extension}" < <(yes '')
    # ddev xdebug and ddev xhprof enable it with DDEV's own ini file,
    # so there is no phpenmod
EOF
```

## Adding Locales

The web image ships by default with a small number of locales, which work for most usages, including `en_CA`, `en_US`, `en_GB`, `es_ES`, `es_MX`, `pt_BR`, `pt_PT`, `de_DE`, `de_AT`, `fr_CA`, `fr_FR`, `ja_JP`, and `ru_RU`.

If you need other locales, you can install all of them by adding `locales-all` to your `webimage_extra_packages`. For example, in `.ddev/config.yaml`:

```
# .ddev/config.yaml
webimage_extra_packages: [locales-all]
```

## Adding Extra Dockerfiles for `webimage` and `dbimage`

For more complex requirements, add your own Dockerfile content to `.ddev/web-build` (for `webimage`) or `.ddev/db-build` (for `dbimage`). DDEV merges those files with its own build steps into one generated Dockerfile per image, at `.ddev/.webimageBuild/Dockerfile` and `.ddev/.dbimageBuild/Dockerfile`, which you never edit directly.

DDEV writes example files for you to copy and rename:

- `.ddev/web-build/Dockerfile.example` and `.ddev/db-build/Dockerfile.example` in the project, when you run [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>)
- `$HOME/.ddev/web-build/pre.Dockerfile.example` and `$HOME/.ddev/db-build/pre.Dockerfile.example` for [global Dockerfiles](<#global-dockerfiles>)

> [!WARNING]
>
> **The Dockerfile builds an image, it doesn’t run in your project**
>
> While the Dockerfile is executing, your code is not mounted and the container is not running, the image is being built. So for example, an `npm install` in `/var/www/html` will not do anything to your project because the code is not there at image building time.

### Insertion Order

The filename decides where its content lands in the generated Dockerfile, and [global files](<#global-dockerfiles>) in `$HOME/.ddev/*-build` are always inserted before the project’s files in `.ddev/*-build`:

| \# | Content | Notes |
| --- | --- | --- |
| 1 | `prepend.Dockerfile`, `prepend.Dockerfile.*`<br>([global](<#global-dockerfiles>), then project) | Above DDEV’s `FROM` line, for [multi-stage builds](<#multi-stage-builds>). Only `$BASE_IMAGE` is declared this early, see [Build Time Environment Variables](<#build-time-environment-variables>) |
| 2 | DDEV’s `FROM $BASE_IMAGE`, build arguments, and user creation | The in-image user mirrors your host user, using `$username`, `$uid`, and `$gid` |
| 3 | `pre.Dockerfile`, `pre.Dockerfile.*`<br>([global](<#global-dockerfiles>), then project) | For directives that have to come early, like proxy settings, SSL termination, [CA certificates](<#global-dockerfiles>), or [EOL PHP versions](<#adding-eol-versions-of-php>) |
| 4 | DDEV’s own build steps | PHP version, `webimage_extra_packages` or `dbimage_extra_packages`, Composer update, database clients |
| 5 | `Dockerfile`, `Dockerfile.*`<br>([global](<#global-dockerfiles>), then project) | The usual choice for most customizations |
| 6 | DDEV’s finishing steps | Permission fixes on the web image, which have to run after everything else |

Within each group, files are inserted in alphabetical order, so `Dockerfile` comes first, then `Dockerfile.*` alphabetically.

To see the result, read the generated Dockerfile, or force a rebuild with [`ddev restart --no-cache`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>) or [`ddev utility rebuild`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-rebuild>), which shows the whole build output for debugging.

### Rebuilding Only What Changed

Docker caches each step of the image build. When a step changes, Docker rebuilds it and every step after it, and reuses the rest. `ddev restart --no-cache` and `ddev utility rebuild` skip the cache and rebuild everything, including `webimage_extra_packages`, which can take minutes.

A step that installs the latest version of a tool doesn’t change when a new version comes out, so the cache keeps the old one. Pin the version instead. When you change it, `ddev restart` rebuilds only from that step on:

```
# .ddev/web-build/Dockerfile.gatsby
ARG GATSBY_CLI_VERSION=5.14.0
RUN npm install -g gatsby-cli@${GATSBY_CLI_VERSION}
```

### Copying Files into the Image

The `.ddev/*-build` directory is the Docker “context”, so if a file named `file.txt` exists in `.ddev/web-build`, you can use `COPY file.txt /` in the Dockerfile.

### Python Packages from `requirements.txt`

If you add `python3-pip` to the web image, `pip install` fails with this error:

```
error: externally-managed-environment

× This environment is externally managed
```

Debian manages the image’s Python packages. Instead, build a virtual environment in the image from the project’s `requirements.txt`. The build reads files only from `.ddev/web-build`, so add the project root as another build context in `.ddev/docker-compose.python.yaml`:

```
# .ddev/docker-compose.python.yaml
services:
  web:
    build:
      additional_contexts:
        project: ${DDEV_APPROOT}
```

Add `python3-venv` to [`webimage_extra_packages`](<#adding-extra-debian-packages-with-webimage_extra_packages-and-dbimage_extra_packages>), for example in `.ddev/config.python.yaml`:

```
# .ddev/config.python.yaml
webimage_extra_packages: [python3-venv]
```

Then create `.ddev/web-build/Dockerfile.python`. The `COPY` source is relative to the project root, so for a file in `docs/`, use `docs/requirements.txt`. `--chmod=644` lets the user read the file even if only its owner can, as with files that Mutagen syncs from the container:

```
# .ddev/web-build/Dockerfile.python
COPY --from=project --chmod=644 requirements.txt /tmp/requirements.txt
RUN install -d -o "$username" /opt/venv \
    && runuser -u "$username" -- python3 -m venv /opt/venv \
    && runuser -u "$username" -- /opt/venv/bin/pip install --no-cache-dir -r /tmp/requirements.txt \
    && echo 'export PATH="/opt/venv/bin:$PATH"' > /etc/bashrc/python-venv.bashrc
```

The virtual environment goes first in `PATH`, so `python` runs it rather than the image’s `/usr/bin/python`, which doesn’t have the packages.

`ddev restart` rebuilds the virtual environment when `requirements.txt` changes. To get newer releases within a version range like `wagtail>=7.2,<7.3`, run `ddev restart --no-cache`. A package added with `ddev exec pip install` lasts until the next restart, so add the ones you want to keep to `requirements.txt`.

### Examples

This `.ddev/web-build/Dockerfile.phpcs` installs `phpcs` and `phpcbf` globally, with the Drupal coding standards from [`drupal/coder`](<https://packagist.org/packages/drupal/coder>):

```
# .ddev/web-build/Dockerfile.phpcs
ARG COMPOSER_HOME=/usr/local/composer
ARG DRUPAL_CODER_VERSION=9.0.1
RUN composer global config --no-interaction \
        allow-plugins.dealerdirect/phpcodesniffer-composer-installer true && \
    composer global require --no-interaction \
        "drupal/coder:${DRUPAL_CODER_VERSION}" && \
    ln -s "${COMPOSER_HOME}/vendor/bin/phpcs" \
        "${COMPOSER_HOME}/vendor/bin/phpcbf" /usr/local/bin/
```

### Multi-Stage Builds

[Multi-stage builds](<https://docs.docker.com/build/building/multi-stage/>) let you copy files from another image, so the web image gets a tool without what it took to build or package it. They need a `prepend.` file, because the extra `FROM` statement has to be on top of the generated Dockerfile. For example, to copy [Bun](<https://bun.sh/>) from its official image, add a `.ddev/web-build/prepend.Dockerfile.bun`:

```
# .ddev/web-build/prepend.Dockerfile.bun
ARG BUN_VERSION=1.4.3
FROM oven/bun:${BUN_VERSION} AS bun
```

And then a `.ddev/web-build/Dockerfile.bun`:

```
# .ddev/web-build/Dockerfile.bun
COPY --from=bun /usr/local/bin/bun /usr/local/bin/bun
RUN ln -s bun /usr/local/bin/bunx
```

### Project-Specific Utilities

DDEV installs these utilities when building the web image for the configured project type:

| Project type | Utilities |
| --- | --- |
| `wordpress`, `wp-bedrock` | WP-CLI (`wp`, `wp-cli`) |
| `magento` | `magerun` and Bash completion |
| `magento2` | `magerun2` and Bash completion |
| `drupal6`, `drupal7` | Drush 8 |
| `backdrop` | Drush 8 and the Backdrop Drush extension |
| `symfony` | Symfony CLI |
| `shopware6` | Shopware CLI |

Building without a cached image downloads the required utilities. Subsequent starts reuse the built image. After changing the project type, run `ddev restart` to rebuild with the corresponding utilities. Modern Drupal projects should install Drush through their project’s Composer dependencies.

To use a utility with another project type, install it in a custom Dockerfile. For example, add `.ddev/web-build/Dockerfile.wp-cli` to make WP-CLI available in a `php` project:

```
# .ddev/web-build/Dockerfile.wp-cli
RUN curl --fail -sSL -o /usr/local/bin/wp-cli \
    https://raw.githubusercontent.com/wp-cli/builds/gh-pages/phar/wp-cli.phar && \
    chmod +x /usr/local/bin/wp-cli && \
    ln -sf /usr/local/bin/wp-cli /usr/local/bin/wp
```

Run `ddev restart`, then use `ddev exec wp --info`. The `ddev wp` command is available for the WordPress and Bedrock project types.

### Global Dockerfiles

The same files work in `$HOME/.ddev/web-build/` and `$HOME/.ddev/db-build/`, where they apply to every project on the machine, which is handy for things like corporate certificates or private package registries. Global files are inserted *before* the project’s own files, and the global directory is a Docker “context” too, where a project file of the same name wins.

> [!TIP]
>
> **Your global directory may live elsewhere**
>
> See [Global Files](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>), it isn’t always `$HOME/.ddev`.

For example, to install a custom CA certificate in every project’s web image:

```
cat > $HOME/.ddev/web-build/pre.Dockerfile.vpn << 'EOF'
COPY my-ca.crt /usr/local/share/ca-certificates/
RUN update-ca-certificates
EOF
cp /path/to/my-ca.crt $HOME/.ddev/web-build/my-ca.crt
ddev restart
```

A `pre.` file is used here so the certificate is in place before DDEV’s own build steps run.

### Build Time Environment Variables

The following environment variables are available for the web Dockerfile to use at build time:

- `$BASE_IMAGE`: the base image, like `ddev/ddev-webserver:v1.24.0` ([global scope](<https://docs.docker.com/build/building/variables/#scoping>))
- `$username`: the username inferred from your host-side username
- `$uid`: the user ID inferred from your host-side user ID
- `$gid`: the group ID inferred from your host-side group ID
- `$DDEV_PHP_VERSION`: the PHP version declared in your project configuration
- `$TARGETARCH`: The build target architecture, like `arm64` or `amd64`
- `$TARGETOS`: The build target operating system (always `linux`)
- `$TARGETPLATFORM`: `linux/amd64` or `linux/arm64` depending on the machine it’s been executed on

> [!WARNING]
>
> **Only `$BASE_IMAGE` is automatically available in `prepend.Dockerfile*` variants**
>
> If you need to use any of the other variables you will need to manually add them to your `prepend.Dockerfile*` files using [ARG](<https://docs.docker.com/reference/dockerfile/#arg>) instructions.

The [PIE](<#pie-php-extensions-not-supported-by-debsuryorg>) and [PECL](<#pecl-php-extensions-not-supported-by-debsuryorg>) examples use `$DDEV_PHP_VERSION` to build an extension for the configured PHP version.

For example, this `.ddev/web-build/Dockerfile.hugo` uses `$TARGETARCH` to download [Hugo](<https://gohugo.io/>) for the architecture being built:

```
# .ddev/web-build/Dockerfile.hugo
ARG HUGO_VERSION=0.168.0
RUN url="https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}" && \
    curl -fsSL "${url}/hugo_${HUGO_VERSION}_linux-${TARGETARCH}.tar.gz" \
    | tar -xz -C /usr/local/bin hugo
```

## DDEV Labels on Images

A DDEV image can carry two labels that look similar and mean different things. `docker inspect` on a locally built web image will show both, usually with different values, which is expected:

| Label | Set by | Means |
| --- | --- | --- |
| `com.ddev.image-tag` | baked in when the image is built | The tag this image was published as. Inherited through `FROM`, so a derived image keeps the tag of the DDEV image it descends from, even after it is given its own name and tag. |
| `com.ddev.webtag` | the running DDEV CLI | Which DDEV built or started this resource. Applied to containers, networks, and the build sections DDEV generates, so it always reflects the DDEV you are running rather than the image’s origin. |

So a project’s own web image, built from `.ddev/web-build`, inherits `com.ddev.image-tag` from the `ddev-webserver` base it was built on, and gets `com.ddev.webtag` from whichever DDEV built it. When you pin a [`webimage`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webimage>) or [`dbimage`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#dbimage>), only `com.ddev.image-tag` tells you which generation of DDEV images it came from, which is what DDEV checks to warn you that a pinned image has gone stale.

## Seeding a Custom Starter Database in `dbimage`

If you publish a derived `dbimage` (for example a CI-built image with your production dataset baked in, so teammates or preview environments get a ready-to-use database with no import step), bake it in as `/mysqlbase/custom/base_db.zst` using a `.ddev/db-build/Dockerfile.seed`:

```
# .ddev/db-build/Dockerfile.seed
COPY base_db.zst /mysqlbase/custom/base_db.zst
```

The database container uses this seed the first time its data volume is created (a brand-new project, or after `ddev delete` and `ddev start`), instead of the stock DDEV starter database. A project-level [seed snapshot](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#seeding-a-fresh-database-from-a-snapshot>) wins over it — so a teammate can still override your baked-in seed for their own project just by dropping a `seed` snapshot into `.ddev/db_snapshots`, without rebuilding the image.

A seed can also be baked in uncompressed, as `base_db.mbstream` (MariaDB) or `base_db.xbstream` (MySQL, or MariaDB 5.5/10.0) — the raw `mariabackup`/`xtrabackup` stream with no compression stage. This is an unusual, deliberate trade-off (see [Uncompressed Snapshots](<https://ddev.github.io/ddev/en/stable/users/usage/database-management/#uncompressed-snapshots>)): it trades a much larger image layer for zero first-boot decompression cost, and only makes sense if you’ve already decided that trade-off is worth it.

When `ddev start` seeds a fresh database volume from a baked-in seed, it says so and warns that a large one may take a while:

```
Initializing new database volume from /mysqlbase/custom/base_db.zst baked into dbimage ddev/ddev-dbserver-mariadb-11.8:v1.25.0...
A large database may take a while; the 600s timeout is set by default_container_timeout.
```

> [!NOTE]
>
> Only supported for `mysql` and `mariadb` database types (excluding the very old, EOL `mysql:5.5` and `mariadb:5.5`). PostgreSQL projects use the stock upstream `postgres` image and its own startup process, which this seeding mechanism doesn’t hook into, so a baked-in seed is silently ignored.

## Adding EOL Versions of PHP

If your project requires multiple versions of PHP—such as using PHP 8.3 but also needing an older, unsupported, unmaintained version like PHP 7.4 for specific scripts—and you don’t want to fully switch to PHP 7.4 with `ddev config --php-version=7.4`, you can install it using the `pre.Dockerfile.*` technique from the previous section.

Create a `.ddev/web-build/pre.Dockerfile.php7.4` file with the following content:

```
# .ddev/web-build/pre.Dockerfile.php7.4
RUN /usr/local/bin/install_php_extensions.sh "php7.4" "${TARGETARCH}"
```

After restarting the project, you can use PHP 7.4 with the command `ddev exec php7.4 -v`.

## Installing into the home directory

The in-container home directory is rebuilt when you run `ddev restart`, so if you have something that installs into the home directory (like `~/.cache`) you’ll want to switch users in the Dockerfile. In this example, `npx playwright install` puts browsers into `~/.cache`, so this `.ddev/web-build/Dockerfile.playwright` switches to the in-container user before running it, and back to `root` afterwards to avoid surprises with any other Dockerfile that may follow. `--with-deps` installs the Debian packages the browsers need with `sudo`. For files that change while the container runs, see [Persisting Changes Across Restarts](<https://ddev.github.io/ddev/en/stable/users/extend/in-container-configuration/#persisting-changes-across-restarts>).

```
# .ddev/web-build/Dockerfile.playwright
# The version in your project's package.json, so the browsers match it
ARG PLAYWRIGHT_VERSION=1.64.1
USER $username
RUN npx --yes "playwright@${PLAYWRIGHT_VERSION}" install --with-deps
USER root
```

### Debugging the Dockerfile Build

It can be complicated to figure out what’s going on when building a Dockerfile, and even more complicated when you’re seeing it go by as part of [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).

1. Use [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) first of all to pioneer the steps you want to take. You can do all the things you need to do there and see if it works. If you’re doing something that affects PHP, you may need to `sudo killall -USR2 php-fpm` for it to take effect.
2. Put the steps you pioneered into a `.ddev/web-build/Dockerfile.*` file as above.
3. If you can’t figure out what’s failing or why, running `ddev utility rebuild` will show the full output of the build process. You can also run `export DDEV_VERBOSE=true && ddev start` to see what’s happening during the `ddev start` Dockerfile build.

# Database Server Types

DDEV supports many versions of the MariaDB, MySQL, and PostgreSQL database servers.

The following database types are currently supported:

- MariaDB 5.5-10.8, 10.11, 11.4, 11.8, 12.3
- MySQL 5.5-8.0, 8.4, 9.7
- Postgres 9-18

The default database type is MariaDB, and the default version is currently 11.8.

For very old database types and situations see [Using DDEV to spin up a legacy PHP application](<https://ddev.com/blog/legacy-projects-with-unsupported-php-and-mysql-using-ddev/>). New LTS versions of each of these are typically added soon after they are released. The very old versions are kept for compatibility with older projects.

You could set these using the [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>) command like this:

- `ddev config --database=mysql:5.7`
- `ddev config --database=mariadb:10.11`
- `ddev config --database=postgres:14`

Or by editing the [`database`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#database>) setting in `.ddev/config.yaml`:

```
database:
  type: mysql
  version: 5.7
```

```
database:
  type: mariadb
  version: 10.11
```

```
database:
  type: postgres
  version: 14
```

## Checking the Existing Database and/or Migrating

Since the existing binary database may not be compatible with changes to your configuration, you need to check and/or migrate your database.

- [`ddev utility get-volume-db-version`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-get-volume-db-version>) will show the current binary database type.
- [`ddev utility check-db-match`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-check-db-match>) will show if your configured project matches the binary database type.
- [`ddev utility migrate-database`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-migrate-database>) allows an automated attempt at migrating your database to a different type/version.

  - This only works with databases of type `mysql` or `mariadb`.
  - MySQL 8.0 has diverged in syntax from most of its predecessors, including earlier MySQL and all MariaDB versions. As a result, you may not be able to migrate *from* databases of type `mysql:8.0` because dumps from MySQL 8.0 often have keywords or other features not supported elsewhere.
  - Examples: `ddev utility migrate-database mariadb:10.7`, `ddev utility migrate-database mysql:8.0`.

## Caveats

- If you change the database type or version in an existing project, the existing database will not be compatible with your change, so you’ll want to use [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>) to save a dump first.
- When you change database type, destroy the existing database using [`ddev delete --omit-snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) before changing, then after [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) use [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) to import the dump you saved.
- Snapshots are always per database type and database version. So if you have snapshots from MariaDB 10.2 and you switch to MariaDB 10.5, don’t expect to be able to restore the old snapshot.

## Other databases types

Through add-ons, additional database types are also supported. The following official add-ons are available:

- [`ddev/ddev-mongo`](<https://github.com/ddev/ddev-mongo>)
- [`ddev/ddev-sqlsrv`](<https://github.com/ddev/ddev-sqlsrv>)

Use `ddev add-on list --all` to see a list of all add-ons, including additional community-supported database types.

# In-Container Home Directory and Shell Configuration

Custom shell configuration (Bash or your preferred shell), your usual Git configuration, a Composer `auth.json` and more can be achieved within your containers.

## Using `homeadditions` to Customize In-Container Home Directory

> [!TIP]
>
> **Finding Your Global DDEV Directory**
>
> The examples below automatically detect the correct global DDEV directory (including when `$DDEV_XDG_CONFIG_HOME` is set) using the `DDEV_DIR` variable. See [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>) for details.

Place all your dotfiles in your global `homeadditions` directory or your project’s `.ddev/homeadditions` directory and DDEV will use these in your project’s `web` containers.

> [!TIP]
>
> **Ignore `.ddev/.homeadditions`!**
>
> A hidden/transient `.ddev/.homeadditions`—emphasis on the leading `.`—is used for processing global `homeadditions` and should be ignored.

On [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>), DDEV attempts to create a user inside the `web` and `db` containers with the same name and user ID as the one you have on the host machine.

DDEV looks for the `homeadditions` directory both in the global `homeadditions` directory and the project-level `.ddev/homeadditions` directory, and will copy their contents recursively into the in-container home directory during `ddev start`. Project `homeadditions` contents override the global `homeadditions`.

Usage examples:

### Git Configuration

If you use Git inside the container, you may want to symlink your `$HOME/.gitconfig` into the global `homeadditions` directory or the project’s `.ddev/homeadditions` so that in-container `git` commands use whatever username and email you’ve configured on your host machine.

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
ln -s $HOME/.gitconfig $DDEV_DIR/homeadditions/.gitconfig
```

### SSH Configuration

If you use SSH inside the container and want to use your `.ssh/config`, you can symlink it into the homeadditions directory. Some people will be able to symlink their entire `.ssh` directory.

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
mkdir -p $DDEV_DIR/homeadditions/.ssh
ln -s $HOME/.ssh/config $DDEV_DIR/homeadditions/.ssh/config
```

Or symlink the entire directory:

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
ln -s $HOME/.ssh $DDEV_DIR/homeadditions/.ssh
```

If you provide your own `.ssh/config` though, please make sure it includes these lines:

```
UserKnownHostsFile=/home/.ssh-agent/known_hosts
StrictHostKeyChecking=accept-new
```

Alternately, you may also place multiple SSH config files within the global or project `.ddev/homeadditions/.ssh/config.d` directory, and they’ll be automatically included as part of the default DDEV SSH config. The files must have a `.conf` extension in order to be included.

### Custom Scripts and Executables

If you need to add a script or other executable component into the project (or global configuration), you can put it in the project or global `.ddev/homeadditions/bin` directory and `$HOME/bin/<script>` will be created inside the container. This is useful for adding a script to one project or every project, or for overriding standard scripts, as `$HOME/bin` is first in the `$PATH` in the `web` container.

For example, to add a custom script:

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
# Create the bin directory
mkdir -p $DDEV_DIR/homeadditions/bin
# Add your script
echo '#!/usr/bin/env bash' > $DDEV_DIR/homeadditions/bin/myscript
echo 'echo "Hello from custom script"' >> $DDEV_DIR/homeadditions/bin/myscript
chmod +x $DDEV_DIR/homeadditions/bin/myscript
```

### Composer Authentication

If you use private, password-protected Composer repositories with [Satis](<https://composer.github.io/satis/>), for example, and use a global `auth.json`, you can symlink it into `homeadditions`. Be careful to exclude it from getting checked in by using a `.gitignore` or equivalent.

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
mkdir -p "$DDEV_DIR/homeadditions/.composer"
# Find the correct location of the auth.json file if Composer is installed
COMPOSER_AUTH_FILE="$(composer config --global home 2>/dev/null)/auth.json"
# Otherwise default to the location on Debian
if [ ! -f "$COMPOSER_AUTH_FILE" ]; then
  COMPOSER_AUTH_FILE="$HOME/.composer/auth.json"
fi
ln -s "$COMPOSER_AUTH_FILE" $DDEV_DIR/homeadditions/.composer/auth.json
```

### Startup Scripts

You can add small scripts to the `.bashrc.d` directory, and they will be executed on [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>).

For example, create a script that shows which container you’re in:

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"

# Create the .bashrc.d directory
mkdir -p $DDEV_DIR/homeadditions/.bashrc.d

# Add a script that runs on ddev ssh
echo 'echo "I am in the $(hostname) container"' > $DDEV_DIR/homeadditions/.bashrc.d/whereami
```

After `ddev restart`, when you `ddev ssh` this script will be executed.

### Custom Bashrc

If you have a favorite `.bashrc`, copy it into either the global or project `homeadditions`:

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
cp $HOME/.bashrc $DDEV_DIR/homeadditions/.bashrc
```

### Bash Aliases

If you like the traditional `ll` Bash alias for `ls -lhA`, add a `.bash_aliases` file to either the global or project `homeadditions`:

```
DDEV_DIR="$(ddev version -j | docker run -i --rm ddev/ddev-utilities jq -r ".raw.\"global-ddev-dir\" | select (.!=null) // \"$HOME/.ddev\"" 2>/dev/null)"
echo 'alias ll="ls -lhA"' > $DDEV_DIR/homeadditions/.bash_aliases
```

### Altering the In-Container `$PATH`

Sometimes it’s easiest to put the command you need into the existing `$PATH` using a symbolic link rather than changing the in-container `$PATH`. For example, the project `bin` directory is already included the `$PATH`. So if you have a command you want to run that’s not already in the `$PATH`, you can add a symlink.

Examples:

- On Craft CMS, the `craft` script is often in the project root, which is not in the `$PATH`. But if you `mkdir bin && ln -s craft bin/craft` you should be able to run `ddev exec craft`. (Note however that `ddev craft` takes care of this for you.)
- On projects where the `vendor` directory is not in the project root (Acquia projects, for example, have `composer.json` and `vendor` in the `docroot` directory), you can `mkdir bin && ln -s docroot/vendor/bin/drush bin/drush` to put `drush` in your `$PATH`. (With projects like this, make sure to set `composer_root: docroot` so that `ddev composer` works properly.)

You can also modify the `PATH` environment variable by adding a script to `<project>/.ddev/homeadditions/.bashrc.d/` or (global) `$HOME/.ddev/homeadditions/.bashrc.d/` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)). For example, if your project vendor directory is not in the expected place (`/var/www/html/vendor/bin`) you can add a `<project>/.ddev/homeadditions/.bashrc.d/path.sh`:

```
export PATH=$PATH:/var/www/html/somewhereelse/vendor/bin
```

## Persisting Changes Across Restarts

The `web` container is created again from its image after every [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>), [`ddev stop`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#stop>), or [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>). Project files and databases are kept, but other changes in the container are lost, including everything in the home directory. `homeadditions` only copies files into the container, never back out.

By default, only the [`ddev-global-cache` volume](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#the-ddev-global-cache-volume>) survives outside the project. This is where DDEV keeps caches and shell history.

| Change made in the container | How to keep it |
| --- | --- |
| `composer global require` | [Keep `~/.composer` in `ddev-global-cache`](<#persisting-home-subdirectories-in-ddev-global-cache>), or install the tool with a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#examples>) |
| `composer self-update` | [`composer_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#composer_version>) |
| `n install <version>` | [`nodejs_version`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#nodejs_version>) |
| `npm install -g` | `RUN npm install -g` in a [custom Dockerfile](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/#examples>) |
| `sudo apt-get install` | [`webimage_extra_packages`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#webimage_extra_packages>) |
| Edited dotfiles, like `~/.bashrc` | [`homeadditions`](<#using-homeadditions-to-customize-in-container-home-directory>) |
| Files a tool writes, like `~/.config/gh` | [Keep the directory in `ddev-global-cache`](<#persisting-home-subdirectories-in-ddev-global-cache>) |

### Persisting Home Subdirectories in `ddev-global-cache`

To persist a subdirectory from your `ddev-webserver` home directory, move it to `ddev-global-cache` and leave a symlink in its place. This script does that each time the `web` container starts:

```
# .ddev/web-entrypoint.d/persist.sh
# Keep these home subdirectories in ddev-global-cache so they survive restarts.
# Files from the image and homeadditions replace the stored copies at each start.
(
  for dir in .composer; do
    target="/mnt/ddev-global-cache/persist/${HOSTNAME}/${dir}"
    mkdir -p "${target}" "$(dirname ~/"${dir}")" &&
      if [ -d ~/"${dir}" ] && [ ! -L ~/"${dir}" ]; then
        cp -a ~/"${dir}"/. "${target}"/ && rm -rf ~/"${dir}"
      fi &&
      ln -sfn "${target}" ~/"${dir}" ||
      echo "persist.sh: unable to keep ~/${dir}" >&2
  done
)
```

- Add directories to the `for` line, relative to the home directory, for example `for dir in .composer .config/gh; do`. They must be owned by your user, not `root`. If the script can’t move a directory, it leaves it in place and prints a warning in `ddev logs -s web`.
- Each project gets its own copy in `/mnt/ddev-global-cache/persist/<project>-web`. You can rename `persist` to anything DDEV doesn’t [already use](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#the-ddev-global-cache-volume>), but keep `${HOSTNAME}` directly under it, because `ddev delete` doesn’t look deeper.
- At each start, files from the image and from `homeadditions` replace their stored copies. Files that exist only in the stored copy, like the packages you installed, are kept.
- DDEV runs `chown -R` on the whole `ddev-global-cache` volume at every start of every project, so keeping a directory with many files, like `node_modules`, makes every start slower.

For `.composer`, also add Composer’s global `bin` directory to `$PATH` with a `homeadditions` script:

```
# .ddev/homeadditions/.bashrc.d/composer-global.sh
export PATH="$PATH:$HOME/.composer/vendor/bin"
```

> [!WARNING]
>
> **Data, not programs**
>
> Because files from the image replace their stored copies, this doesn’t keep updates a tool makes to itself, see [Tools That Update Themselves](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/#tools-that-update-themselves>). Keep directories, not single files: many tools save a file by replacing it, which removes the symlink.

[`ddev delete`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#delete>) removes the stored directories. To remove them without deleting the project:

```
ddev exec 'rm -rf /mnt/ddev-global-cache/persist/${HOSTNAME}'
ddev restart
```

Use single quotes, so `${HOSTNAME}` expands inside the container.

### Keeping a Directory in a Docker Volume

Instead of the script, you can mount a Docker volume over the directory with a `.ddev/docker-compose.*.yaml` file. Each directory needs its own volume:

```
# .ddev/docker-compose.composer-home.yaml
services:
  web:
    volumes:
      - composer-home:/home/${DDEV_USER}/.composer
volumes:
  composer-home:
```

On first use, Docker fills the empty volume with what the image has in that directory. After that, the volume hides the image’s copy, so changes to that directory from DDEV upgrades or add-ons don’t show up. `homeadditions` files are still copied in at each start. `ddev delete` removes the volume.

## Changing `ddev ssh` Shell

You can define a default shell for [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) using the `x-ddev` extension field in your `.ddev/docker-compose.*.yaml` configuration.

Use the `x-ddev.ssh-shell` key and make sure that shell (such as `zsh` or `bash`) is included in the container image so `ddev ssh` work correctly. The selected shell also appears in the [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) output (if it’s not the default one).

Changing the default shell to `zsh` in the `web` and `db` containers:

```
# .ddev/config.yaml
webimage_extra_packages: [zsh]
dbimage_extra_packages: [zsh]
```

```
# .ddev/docker-compose.ssh-shell.yaml
services:
  web:
    x-ddev:
      ssh-shell: zsh
  db:
    x-ddev:
      ssh-shell: zsh
```

To change the shell for a custom service, add the `x-ddev.ssh-shell` field to that service’s configuration and ensure the desired shell is [installed in the image](<https://ddev.github.io/ddev/en/stable/users/extend/customizing-images/index.md>).

## Changing the Container User

Some third-party images expect work to happen as a specific non-root user, so the image’s default user isn’t right for that service. Set `x-ddev.container-user` on that service so [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>), [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>), and [custom commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/index.md>) all run as that user without requiring an explicit `-u`. An explicit `-u` still wins.

```
# .ddev/docker-compose.devilbox-php.yaml
services:
  devilbox-php:
    container_name: ddev-${DDEV_SITENAME}-devilbox-php
    image: devilbox/php-fpm-5.3
    x-ddev:
      ssh-shell: bash
      container-user: www-data
```

With this in place, `ddev ssh -s devilbox-php` logs in as `www-data`, and the configured user also appears in [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) output.

> [!TIP]
>
> See the [`x-ddev` Extension](<https://ddev.github.io/ddev/en/stable/users/extend/custom-docker-services/#x-ddev-extension>) for all supported keys, including `describe-*` and `omit-ddev-labels`.

## Using `NO_COLOR` Inside Containers

To set the `NO_COLOR` variable in all containers across all projects, define the `NO_COLOR` environment variable in your shell configuration file (e.g., `$HOME/.bashrc` or `$HOME/.zshrc`), outside of DDEV, for example:

```
export NO_COLOR=1
```

`NO_COLOR=1` can also be implicitly set using [`simple_formatting`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#simple_formatting>) option.

## Using `PAGER` Inside Containers

To set the `PAGER` variable in the `web` and `db` containers across all projects, define the `DDEV_PAGER` environment variable in your shell configuration file (e.g., `$HOME/.bashrc` or `$HOME/.zshrc`), outside of DDEV, for example:

```
export DDEV_PAGER="less -SFXR"
```

## In-container `ssh` or `rsync` failures

If you use `ddev auth ssh` and use `ssh` or `rsync` inside the container and see a message like this:

```
$ ddev exec ssh <hostname>
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
```

It means that the host you are connecting to has actually changed its identification. If you know why that is, and accept the situation, you can clean up the situation with this command:

```
ddev exec ssh-keygen -f '/home/.ssh-agent/known_hosts' -R '<hostname>'
```

Use the hostname that gave you trouble.

## Too Many Authentication Failures

If `ssh` or `rsync` inside the container fails with:

```
Received disconnect from <host> port 22:2: Too many authentication failures
```

the *server* you’re connecting to has a `MaxAuthTries` limit and gave up after your agent offered more keys than it allows, not because any key was wrong. This is more likely with [`ssh_agent_upstream`](<https://ddev.github.io/ddev/en/stable/users/usage/cli/#using-an-existing-ssh-agent>), which relays every key your agent holds, or with a large `~/.ssh` full of key files.

Limit which key gets offered for that host instead of pruning keys everywhere:

- With key files, use `ddev auth ssh -d <dir>` with a directory that has only the keys you need.
- With an agent, including `ssh_agent_upstream`, add a `Host` block to your [homeadditions `~/.ssh/config`](<#ssh-configuration>) with `IdentitiesOnly yes` and `IdentityFile` pointing at the key’s `.pub` file — safe to keep in the container, since it’s public. The agent then offers only the matching private key for that host:

```
Host github.com
    IdentitiesOnly yes
    IdentityFile ~/.ssh/id_ed25519.pub
```

# Custom Share Providers

You can customize the built-in providers or create your own share providers in `.ddev/share-providers/`.

## Customizing Built-in Providers

### Take Ownership of a Built-in Provider

1. Edit the provider script (e.g., `.ddev/share-providers/ngrok.sh`)
2. Remove the `#ddev-generated` line at the top
3. Make your changes
4. DDEV will never overwrite this file again

### Create a Custom Variant

```
# Copy built-in provider
cp .ddev/share-providers/ngrok.sh .ddev/share-providers/my-ngrok.sh

# Edit my-ngrok.sh:
# - Remove '#ddev-generated' line
# - Customize as needed

# Use your variant
ddev share --provider=my-ngrok
```

## Creating a New Provider

Create a new executable script in `.ddev/share-providers/`:

```
#!/usr/bin/env bash
set -euo pipefail

# Start your tunnel tool
mytunnel http "$DDEV_LOCAL_URL" &
TUNNEL_PID=$!

trap "kill $TUNNEL_PID 2>/dev/null || true" EXIT

# Capture public URL (however your tool exposes it)
URL=$(get-tunnel-url)

# Output URL to stdout (CRITICAL: first line only)
echo "$URL"

# Wait for tunnel to exit
wait $TUNNEL_PID
```

## Provider Script Contract

Every share provider must follow this contract:

### Input (Environment Variables)

| Variable | Description |
| --- | --- |
| `DDEV_LOCAL_URL` | Local URL to tunnel (e.g., `http://127.0.0.1:8080`) |
| `DDEV_SHARE_ARGS` | Provider-specific arguments (optional) |

All standard DDEV environment variables are also available.

### Output

- **`stdout`**: Public URL (first line only - captured by DDEV)
- **`stderr`**: Logs, status messages (passed through to user)

### Lifecycle

1. Validate tool is installed
2. Validate required environment variables
3. Start tunnel process in background
4. Capture public URL (via API, stdout, file, etc.)
5. Output URL to stdout
6. Wait for tunnel process to exit

### Signal Handling

Providers must handle `SIGINT` (Ctrl+C) and `SIGTERM` gracefully. Use `trap` to cleanup background processes:

```
cleanup() {
    if kill -0 $PID 2>/dev/null; then
        kill $PID 2>/dev/null || true
    fi
}
trap cleanup EXIT
```

## Hooks Integration

After the tunnel URL is captured, DDEV sets the `DDEV_SHARE_URL` environment variable and runs pre-share hooks. This allows you to alter projects as needed (like WordPress `ddev wp search-replace`, for example).

Example `.ddev/config.share.yaml`:

```
hooks:
  pre-share:
    - exec: |
        echo "Tunnel URL: ${DDEV_SHARE_URL}"
        wp search-replace ${DDEV_PRIMARY_URL} ${DDEV_SHARE_URL}
```

## Troubleshooting Custom Providers

**Provider not found:**

```
Error: share provider 'foo' not found
```

Check that `.ddev/share-providers/foo.sh` exists and is executable:

```
ls -la .ddev/share-providers/
chmod +x .ddev/share-providers/foo.sh
```

**Provider outputs no URL:**

```
Error: provider 'ngrok' did not output a URL
```

Common causes: tool not installed, authentication required, no internet. Debug by running the provider directly:

```
export DDEV_LOCAL_URL=http://127.0.0.1:8080
.ddev/share-providers/ngrok.sh
```

# Router Customization and Debugging (Traefik)

DDEV uses the well-known open-source [Traefik](<https://traefik.io/traefik/>) for its router container.

DDEV’s router plays an important role in its [container architecture](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#container-architecture>), receiving HTTP and HTTPS traffic for requests like `*.ddev.site` and delivering them to the appropriate project’s web container.

## Traefik Configuration

Before continuing, it’s important to note that **very few users ever experiment with custom Traefik configuration**. This is an advanced topic, and the vast majority of users never need to know anything about it, as DDEV generates all the necessary configuration. In general you don’t need to understand Traefik configuration.

However, you can fully customize the router’s [Traefik configuration](<https://doc.traefik.io/traefik/getting-started/configuration-overview/>). (DDEV uses the Traefik `v3` rule syntax.)

All Traefik configuration uses the *file* provider, not the *Docker* provider. Even though the Traefik daemon itself is running inside the `ddev-router` container, it uses mounted files for configuration, rather than listening to the Docker socket.

> [!TIP]
>
> Like other DDEV configuration, any file with `#ddev-generated` will be overwritten unless you choose to “take over” it yourself. You can do this by removing the `#ddev-generated` line. DDEV will stop making changes to that file, and you’ll be responsible for updating it.

### Traefik Static Configuration

Static configuration is automatically generated in the `$HOME/.ddev/traefik` directory (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)). “Static” configuration means Traefik configuration which is only read when the router is started.

- `.static_config.yaml` (a hidden file) is the configuration that gets used. It is not to be edited; it is generated from DDEV’s base configuration while merging any files named `static_config.*.yaml`. It is read on router startup, and does not change until the router starts again (normally after `ddev poweroff`).
- Additional static configuration may be added by adding `static_config.*.yaml` files, which will be merged into the generated `.static_config.yaml`. For example, a `static_config.loglevel.yaml` might override logging configuration, a `static_config.plugin.yaml` might contain external Traefik plugins, or a `static_config.dnschallenge.yaml` might provide configuration for additional `certificatesResolvers`. Merging is done with an **override** strategy, meaning that the final file in alphanumeric sort to touch a particular element of the YAML structure wins. Some examples of `static_config.*.yaml` files are:

  - `static_config.loglevel.yaml`:

    ```
    # Enable extensive error and access logging
    log:
      level: DEBUG
    accessLog:
      filters:
        statusCodes: {}
    ```
  - `static_config.cloudflare.yaml`:

    ```
    certificatesResolvers:
      acme-dnsChallenge:
        acme:
          email: admin@example.com
          dnsChallenge:
            provider: cloudflare
    ```
  - `static_config.fail2ban.yaml`

    ```
    experimental:
      plugins:
        fail2ban:
          moduleName: "github.com/tomMoulard/fail2ban"
          version: "v0.8.1"
    ```
- `certs/default_cert.*` files are the default DDEV-generated certificates, normally created by `mkcert`.
- `config/default_config.yaml` contains global *dynamic* configuration, including pointers to the default certificates. It’s unusual to change its content, but if you wanted to change the content you would override with a file in `custom-global-config`.
- `custom-global-config` is a directory where you can add custom Traefik dynamic configuration files (such as middleware, routers, or services) that will be automatically included for all projects. Files in this directory are copied to the router’s config volume on each `ddev start`. For example, a `custom-global-config/global_middlewares.yaml` file might provide middleware implementations that could be used in all projects:

  ```
  http:
    middlewares:
      global-ratelimit:
        rateLimit:
          average: 100
          burst: 50
  ```

### Project Traefik Configuration

Project-specific configuration is automatically generated in the project’s `.ddev/traefik/config` directory. For example, a project named `example` will have a `.ddev/traefik/config/example.yaml` which describes the routers, middlewares, and services generated by default for that project. These are based on the base hostname, `additional_hostnames`, and `additional_fqdns` defined for the project. They also include support for add-ons and services that use `HTTP_EXPOSE`, `HTTPS_EXPOSE`, and `VIRTUAL_HOST` configurations (see [Conventions for Defining Additional Services](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/#conventions-for-defining-additional-services>) for more details).

- The `certs` directory contains the `<projectname>.crt` and `<projectname>.key` certificate generated for the project.
- The `config/<projectname>.yaml` file contains the base configuration for the project, including information about routers, services, and certificates.
- **Adding Custom Configuration**: You can add custom Traefik configuration by creating additional `*.yaml` files in the `.ddev/traefik/config` directory. All YAML files in this directory will be automatically merged together, with `<projectname>.yaml` serving as the base. The merged result is then copied to the global Traefik configuration as `<projectname>_merged.yaml`. This allows you to add custom routers, middlewares, or services without modifying the main configuration file.

  For example, to add custom middleware to a project named `example`, you could create `.ddev/traefik/config/custom-middleware.yaml`:

  ```
  http:
    middlewares:
      example-custom-headers:
        headers:
          customRequestHeaders:
            X-Custom-Header: "my-value"
  ```
- **Taking Over Configuration**: If you want to completely customize the configuration and prevent DDEV from regenerating it, remove the `#ddev-generated` line from the top of the `config/<projectname>.yaml` file. DDEV will then stop regenerating it, and you’ll be responsible for maintaining it. If you do this and then change the name of the project, you have to either remove the file and have DDEV regenerate it, or you have to update it yourself.

## Router `docker-compose` Customization

The default Docker Compose configuration for the router container is found in `$HOME/.ddev/.router-compose.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)). It is quite unusual to override this configuration, but it can be overridden in the same way project configuration can be overridden (project `.ddev/docker-compose.*.yaml`). These ultimately get merged into `$HOME/.ddev/.router-compose-full.yaml`

You can create a `$HOME/.ddev/router-compose.*.yaml`. For example, as `$HOME/.ddev/router-compose.cloudflare.yaml` might contain environment variables like this:

```
# $HOME/.ddev/router-compose.cloudflare.yaml
services:
  ddev-router:
    environment:
      - CLOUDFLARE_EMAIL=you@example.com
      - CLOUDFLARE_API_KEY=some-key
```

### Custom Maintenance Page

When a request reaches the router for a hostname that no running project serves, for example while a project is stopped or restarting, the router answers with a DDEV page explaining why. If you [host with DDEV](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>), you can replace it with your own maintenance page using `configs` in a `$HOME/.ddev/router-compose.maintenance.yaml`:

```
# $HOME/.ddev/router-compose.maintenance.yaml
services:
  ddev-router:
    configs:
      - source: unmatched-route.html
        target: /var/www/ddev-router-fallback/unmatched-route.html
        mode: "0444"
      - source: ddev-router-fallback-responder.sh
        target: /usr/local/bin/ddev-router-fallback-responder.sh
        mode: "0755"

configs:
  unmatched-route.html:
    content: |
      <h1>Under maintenance</h1>
      <p>We'll be back shortly.</p>
  ddev-router-fallback-responder.sh:
    content: |
      #!/bin/sh
      printf 'HTTP/1.1 503 Service Unavailable\r\nContent-Type: text/html; charset=utf-8\r\nRetry-After: 60\r\nConnection: close\r\n\r\n'
      cat /var/www/ddev-router-fallback/unmatched-route.html
```

Run `ddev poweroff` and `ddev start` to recreate the router. The page is served with a `503` status instead of DDEV’s `404`, and without DDEV’s `X-Ddev-404-Source` header. To change only the page, keep just the `unmatched-route.html` config. In `content`, write each `$` as `$$` so that Docker Compose doesn’t treat it as a variable.

## Troubleshooting Traefik Routing

Traefik provides a dynamic description of its configuration you can visit at `http://localhost:10999`. When things seem to be going wrong, run [`ddev poweroff`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) and then start your project again by running [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). Examine the router’s logs to see what the Traefik daemon is doing (or failing at) by running `docker logs ddev-router` or `docker logs -f ddev-router`. The Traefik logs are set to a minimal set by default, but you can enable much more extensive logging and access logs with a `static_config.loglevel.yaml` as [described above](<#traefik-static-configuration>).

### Warning: There are router configuration problems

If you see a warning on `ddev start` about router configuration problems, it is most likely a result of custom configuration problems, which could be an invalid `docker-compose.*.yaml` or leftover project `.ddev/traefik/config/*.yaml` files. Only Traefik **error**-level (ERR) messages are shown there; **warning**-level (WRN) and debug output from Traefik appear only in `docker logs ddev-router`.

On Linux systems, file watcher errors related to the `*file.Provider` are a common cause. See the section below for solutions.

### Linux file watcher errors

If you encounter Traefik file watcher errors on Linux systems, these are common solutions:

#### Error adding file watcher: no space left on device

This error appears during `ddev start` or in the router logs, `docker logs ddev-router`, as:

> ERR Cannot start the provider \*file.Provider error=”error adding file watcher: no space left on device”

This indicates that the system has reached the limit for inotify watches on your Linux computer. First, check the current value:

```
sysctl fs.inotify.max_user_watches
```

Then create a configuration file to increase the limit (for example, if the current value is `65536`, you can increase it to `524288`):

```
echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.d/60-inotify.conf
```

Apply the changes without restarting the system:

```
sudo sysctl -p /etc/sysctl.d/60-inotify.conf
```

#### Error creating file watcher: too many open files

This error appears during `ddev start` or in the router logs, `docker logs ddev-router`, as:

> ERR Cannot start the provider \*file.Provider error=”error creating file watcher: too many open files”

This indicates that too many inotify instances are open. First, check the current value:

```
sysctl fs.inotify.max_user_instances
```

Then create a configuration file to increase the limit (for example, if the current value is `128`, you can increase it to `8192`):

```
echo 'fs.inotify.max_user_instances=8192' | sudo tee -a /etc/sysctl.d/60-inotify.conf
```

Apply the changes without restarting the system:

```
sudo sysctl -p /etc/sysctl.d/60-inotify.conf
```

# Using DDEV Add-ons

DDEV add-ons are pre-packaged extensions that add functionality to your development environment with a single command. They handle installation, configuration, and integration automatically.

## Add-ons vs. Custom Docker Compose Services

**Use add-ons when:**

- A standard, tested service is available as an add-on (Redis, Elasticsearch, Solr)
- You want automatic configuration and setup

**Use custom Docker Compose services when:**

- You need a custom or highly specialized service
- You require deep customization of the service configuration
- You’re prototyping or experimenting with service configurations

See [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>) for custom Docker Compose service setup.

## Discovering Add-ons

### Web-based Add-on Registry

Use [DDEV Add-on Registry](<https://addons.ddev.com/>) to discover, explore, and leave comments on available add-ons.

### Command Line Discovery

List all available add-ons:

```
ddev add-on list
```

Search for specific add-ons by name or description:

```
# Search for Redis-related add-ons
ddev add-on search redis

# Search with multiple terms (all must be present)
ddev add-on search redis web

# Search with multiple terms using quotes (currently same behavior)
ddev add-on search "redis insight"
```

## Installing Add-ons

### Public Add-ons

Install any public add-on using the repository format:

```
ddev add-on get <owner>/<repo>
```

Examples:

```
# Download the official Redis add-on
ddev add-on get ddev/ddev-redis

# Get debug info about `ddev add-on get` failure
ddev add-on get ddev/ddev-redis --verbose

# Download the official Redis add-on, version v1.0.4
ddev add-on get ddev/ddev-redis --version v1.0.4

# Download the Drupal Solr add-on from its v1.2.3 release tarball
ddev add-on get https://github.com/ddev/ddev-drupal-solr/archive/refs/tags/v1.2.3.tar.gz

# Download the Drupal Contrib add-on from its main branch tarball
ddev add-on get https://github.com/ddev/ddev-drupal-contrib/tarball/main

# Download the OpenSearch add-on from a pull request #15 tarball
ddev add-on get https://github.com/ddev/ddev-opensearch/tarball/refs/pull/15/head

# Copy an add-on available in another directory
ddev add-on get /path/to/package

# Copy an add-on from a tarball in another directory
ddev add-on get /path/to/tarball.tar.gz

# Download the official Redis add-on and install it into a project named "my-project"
ddev add-on get ddev/ddev-redis --project my-project
```

Add-ons are installed into your project’s `.ddev` directory and automatically integrated with your project configuration.

### Private Add-ons

Add-ons from private GitHub repositories are supported, but you have to provide a GitHub token with the correct privileges to allow access to them:

- [Fine-grained personal access tokens](<https://github.com/settings/personal-access-tokens/new?contents=read>) with the `contents:read` scope are recommended for better security.
- [Classic tokens](<https://github.com/settings/tokens/new>) with the `repo` scope also work.

> [!TIP]
>
> **Can I reuse my token from a different environment variable?**
>
> Yes, supported [environment variables](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#add-on>) include:
>
> - `DDEV_GITHUB_TOKEN` (highest priority)
> - `GH_TOKEN` (lower priority than `DDEV_GITHUB_TOKEN`)
> - `GITHUB_TOKEN` (lowest priority)

```
export DDEV_GITHUB_TOKEN=<your-github-token>

# Get the private add-on from the latest stable release
ddev add-on get <owner>/<repo>

# Or get a tarball for a specific branch, tag, or commit SHA
ddev add-on get https://api.github.com/repos/<owner>/<repo>/tarball/<ref>

# Note: the format below may not work with fine-grained tokens
ddev add-on get https://github.com/<owner>/<repo>/tarball/<ref>
```

Private repositories on other platforms:

```
git clone <private-repo-url> /tmp/private-addon
ddev add-on get /tmp/private-addon
```

## Managing Add-ons

### View Installed Add-ons

```
ddev add-on list --installed
```

### Update an Add-on

```
ddev add-on get <owner>/<repo>
```

This updates to the latest version while preserving your customizations.

To check and update every installed add-on at once:

```
ddev add-on update
```

Add `--dry-run` to see what would be updated without installing anything.

### Remove an Add-on

```
ddev add-on remove <addon-name>
```

This cleanly removes all add-on files and configurations.

## Customizing Add-on Configuration

Sometimes you need to customize an add-on’s default configuration.

### Method 1: Environment Variables (Recommended)

Many add-ons support customization through environment variables. For example, to change the Redis version in [`ddev-redis`](<https://github.com/ddev/ddev-redis>):

```
ddev dotenv set .ddev/.env.redis --redis-tag 7-bookworm
ddev restart
```

This sets `REDIS_TAG="7-bookworm"` which the add-on uses during service startup.

You can also edit the `.ddev/.env.redis` file directly:

```
REDIS_TAG="7-bookworm"
REDIS_FOO="bar"
```

In DDEV v1.25.4+, if an add-on needs an API token or anything else you would rather not commit, put that value in a `.local` file instead, named `.ddev/.env.<addon>.local`. DDEV keeps those out of Git and applies them right after `.ddev/.env.<addon>`, so the shared settings can stay in Git while the secret doesn’t. See [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) for the full set of filenames and the order they override each other in.

> [!TIP]
>
> **Check add-on documentation**
>
> Each add-on documents its available environment variables. Check the add-on’s GitHub repository for configuration options.

### Method 2: Docker Compose Override

For more complex customizations, create an override file. For example, `.ddev/docker-compose.redis_extra.yaml`:

```
services:
  redis:
    image: redis:7-bookworm
    command: ["redis-server", "--maxmemory", "256mb"]
```

This approach:

- Maintains your customizations when updating the add-on
- Allows complex service modifications
- Doesn’t require modifying the original add-on files

> [!NOTE]
>
> Remove the `#ddev-generated` line from any add-on file you customize directly, but using override files is preferred.

## Official Add-ons

### Database and Caching

- **[`ddev/ddev-redis`](<https://github.com/ddev/ddev-redis>)** - Redis cache and data store service
- **[`ddev/ddev-memcached`](<https://github.com/ddev/ddev-memcached>)** - High-performance Memcached caching service
- **[`ddev/ddev-mongo`](<https://github.com/ddev/ddev-mongo>)** - MongoDB database support

### Search and Analytics

- **[`ddev/ddev-elasticsearch`](<https://github.com/ddev/ddev-elasticsearch>)** - Elasticsearch full-text search and analytics engine
- **[`ddev/ddev-opensearch`](<https://github.com/ddev/ddev-opensearch>)** - OpenSearch analytics, logging, and full-text search
- **[`ddev/ddev-solr`](<https://github.com/ddev/ddev-solr>)** - Apache Solr server setup for search indexing
- **[`ddev/ddev-drupal-solr`](<https://github.com/ddev/ddev-drupal-solr>)** - Apache Solr search engine integration for Drupal

### Development Tools

- **[`ddev/ddev-adminer`](<https://github.com/ddev/ddev-adminer>)** - Adminer web-based MySQL, MariaDB, PostgreSQL database browser
- **[`ddev/ddev-phpmyadmin`](<https://github.com/ddev/ddev-phpmyadmin>)** - Web-based phpMyAdmin interface for MySQL, MariaDB
- **[`ddev/ddev-redis-insight`](<https://github.com/ddev/ddev-redis-insight>)** - Redis Insight Web UI for use with Redis service
- **[`ddev/ddev-browsersync`](<https://github.com/ddev/ddev-browsersync>)** - Live-reload and HTTPS auto-refresh on file changes

### Platform and Cloud Integration

- **[`ddev/ddev-upsun`](<https://github.com/ddev/ddev-upsun>)** - Upsun Fixed (formerly Platform.sh) and Flex integration for project syncing and workflows
- **[`ddev/ddev-ibexa-cloud`](<https://github.com/ddev/ddev-ibexa-cloud>)** - Pull projects and data from Ibexa Cloud
- **[`ddev/ddev-minio`](<https://github.com/ddev/ddev-minio>)** - MinIO S3-compatible object storage solution

### Specialized Services

- **[`ddev/ddev-rabbitmq`](<https://github.com/ddev/ddev-rabbitmq>)** - RabbitMQ message broker, queue manager
- **[`ddev/ddev-cron`](<https://github.com/ddev/ddev-cron>)** - Run scheduled tasks and cron jobs inside web container
- **[`ddev/ddev-ioncube`](<https://github.com/ddev/ddev-ioncube>)** - Enable ionCube PHP loaders for encoded files
- **[`ddev/ddev-selenium-standalone-chrome`](<https://github.com/ddev/ddev-selenium-standalone-chrome>)** - Headless Chrome browser testing with Selenium

### Development Environment

- **[`ddev/ddev-drupal-contrib`](<https://github.com/ddev/ddev-drupal-contrib>)** - Contrib module development environment for Drupal projects

## Troubleshooting Add-ons

### Check Add-on Status

```
ddev describe
```

```
ddev logs -s <service>
```

This shows logs from an add-on’s service.

### Explore Add-on Files

```
ls -la .ddev/
```

Look for files created by the add-on, typically:

- `docker-compose.<addon-name>.yaml`
- Configuration files in `.ddev/<addon-name>/`
- Custom commands in `.ddev/commands/`

### Restart Services

```
ddev restart
```

This restarts all services and applies any configuration changes.

```
ddev restart -s <service>
```

This restarts only the add-on’s service and applies changes to its configuration and Dockerfile. Add `--no-cache` to rebuild its image without Docker cache.

### Review Add-on Configuration

```
ddev utility compose-config
```

This shows the final Docker Compose configuration including add-on services.

### Common Issues

**Service not starting**: Check `ddev logs -s <service>` for error messages from the add-on service.

**Configuration not applied**: Ensure you’ve run `ddev restart` after making configuration changes.

## Getting Help

- **Add-on documentation**: Check the add-on’s GitHub repository readme
- **DDEV Discord**: Join the [DDEV Discord](<https://ddev.com/s/discord>) for community support
- **GitHub Issues**: Report add-on-specific issues to the add-on’s repository

## Next Steps

- **Create custom add-ons**: See [Creating Add-ons](<https://ddev.github.io/ddev/en/stable/users/extend/creating-add-ons/index.md>)
- **Manual services**: See [Defining Additional Services with Docker Compose](<https://ddev.github.io/ddev/en/stable/users/extend/custom-compose-files/index.md>)
- **Advanced customization**: See [Extending and Customizing Environments](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/index.md>)

# Debugging and Profiling

# Blackfire Profiling

DDEV has built-in [Blackfire](<https://www.blackfire.io/>) integration.

## Basic Blackfire Usage (Using Browser Plugin)

1. Create a [Blackfire](<https://www.blackfire.io/>) account. (Free Blackfire accounts are no longer available; see [Blackfire pricing](<https://www.blackfire.io/pricing/>).)
2. Install the Chrome or Firefox [browser plugin](<https://blackfire.io/docs/profiling-cookbooks/profiling-http-via-browser>).
3. From Blackfire’s control panel, get the Server ID, Server Token, Client ID, and Client Token from your Account → Credentials or environment.
4. Configure DDEV with the credentials, `ddev config global --web-environment-add="BLACKFIRE_SERVER_ID=<id>,BLACKFIRE_SERVER_TOKEN=<token>,BLACKFIRE_CLIENT_ID=<id>,BLACKFIRE_CLIENT_TOKEN=<token>"`. It’s easiest to do this globally, but you can do the same thing at the project level using `ddev config --web-environment-add`. (It may be easier to manually edit the relevant config file, `.ddev/config.yaml` or `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)).)
5. [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).
6. [`ddev blackfire on`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#blackfire>) to enable, `ddev blackfire off` to disable, `ddev blackfire status` to see status.
7. With Blackfire enabled, you can use the [browser extension](<https://blackfire.io/docs/profiling-cookbooks/profiling-http-via-browser>).

## Profiling with the Blackfire CLI

The Blackfire CLI is built into the web container, so you don’t need to install it yourself.

1. Add the `BLACKFIRE_SERVER_ID`, `BLACKFIRE_SERVER_TOKEN`, `BLACKFIRE_CLIENT_ID`, and `BLACKFIRE_CLIENT_TOKEN` environment variables to `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) via the `web_environment` key:

   ```
   web_environment:
       - OTHER_ENV=something
       - BLACKFIRE_SERVER_ID=dde5f66d-xxxxxx
       - BLACKFIRE_SERVER_TOKEN=09b0ec-xxxxx
       - BLACKFIRE_CLIENT_ID=f5e88b7e-xxxxx
       - BLACKFIRE_CLIENT_TOKEN=00cee15-xxxxx1
   ```

   You can also do this with `ddev config global --web-environment-add="BLACKFIRE_SERVER_ID=<id>,BLACKFIRE_SERVER_TOKEN=<token>,BLACKFIRE_CLIENT_ID=<id>,BLACKFIRE_CLIENT_TOKEN=<token>"`.
2. [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>).
3. `ddev blackfire on`.
4. Click the “Blackfire” browser extension to profile.

## Examples of Using the Blackfire CLI

- `ddev blackfire on` and `ddev blackfire off`
- [`ddev exec blackfire curl https://<yoursite>.ddev.site`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>)
- `ddev exec blackfire run drush st`
- `ddev exec blackfire curl https://<yoursite>.ddev.site`
- [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) and use the Blackfire CLI as described in [Profiling HTTP Requests with the CLI](<https://blackfire.io/docs/profiling-cookbooks/profiling-http-via-cli>).

# Step Debugging with Xdebug

Every DDEV project is automatically configured with Xdebug so that popular IDEs can do step debugging of PHP code.

Xdebug is a server-side tool, and it’s installed automatically in the container so you don’t have to install or configure it on your workstation. Xdebug is disabled by default for performance reasons, so you’ll need to enable it and configure your IDE before can start debugging.

All IDEs basically work the same, listening on a port and reacting when they’re contacted there. IDEs other than those listed here work fine, if they listen on Xdebug’s default port 9003.

**Key facts:**

- Enable Xdebug by running [`ddev xdebug`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>) or `ddev xdebug on` from your project directory. It will remain enabled until you start or restart the project.
- Disable Xdebug for better performance when not debugging with `ddev xdebug off`.
- Toggle Xdebug on and off easily with `ddev xdebug toggle`.
- `ddev xdebug status` will show Xdebug’s current status.
- You may need to open port 9003 in your firewall to allow Xdebug access. (See [Troubleshooting Xdebug](<#troubleshooting-xdebug>) below.)
- The IDE’s debug server port must be set to Xdebug’s default 9003, which is already the case in popular IDEs. If the unusual case that you have a port conflict, see [Using Xdebug on a Port Other than the Default 9003](<#using-xdebug-on-a-port-other-than-the-default-9003>) below.
- In the case of using running your IDE inside WSL2 (using WSLg) or with a proxy setup like JetBrains Gateway, you can set that with `ddev config global --xdebug-ide-location=wsl2`. If you’re running your IDE with a proxy inside the web container, you can set that with `ddev config global --xdebug-ide-location=container`.
- To debug Drush 13+ commands on Drupal [see instructions](<https://ddev.github.io/ddev/en/stable/users/usage/cms-settings/#drush-and-xdebug>).

For more background on Xdebug, see [Xdebug documentation](<https://xdebug.org/docs/remote>). The intention here is that one won’t have to understand Xdebug to do debugging.

## IDE Setup

- [PhpStorm](<#phpstorm-debugging-setup>)
- [Visual Studio Code (VS Code)](<#visual-studio-code-vs-code-debugging-setup>)

### PhpStorm Debugging Setup

[PhpStorm](<https://www.jetbrains.com/phpstorm/download>) is a leading PHP development IDE with extensive built-in debugging support. It provides two ways to do debugging: “zero-configuration” debugging which requires very little effort in the PhpStorm IDE, and a “run configuration” you can set up like Netbeans or Eclipse.

> [!TIP]
>
> **If you’re using PhpStorm inside WSL2 or Linux**
>
> Make PhpStorm listen for Xdebug using IPv4 by visiting Help → Edit Custom VM Options, and adding an additional line: `-Djava.net.preferIPv4Stack=true`. The Linux version of PhpStorm seems to otherwise default to only using IPv6.

> [!TIP]
>
> **If using PhpStorm inside WSL2 or with JetBrains Gateway**
>
> Make PhpStorm listen to the right IP address with `ddev config global --xdebug-ide-location=wsl2`

#### PhpStorm Zero-Configuration Debugging

PhpStorm [zero-configuration debugging](<https://confluence.jetbrains.com/display/PhpStorm/Zero-configuration+Web+Application+Debugging+with+Xdebug+and+PhpStorm>) will automatically detect a connection and offer to create a “server” that maps your workstation files to the container. This means you only have to:

1. Toggle the “Start Listening for PHP Debug Connections” button: ![Start listening for debug connections button](<https://ddev.github.io/ddev/en/stable/images/phpstorm-listen-for-debug-connections.png>)
2. Set a breakpoint.
3. Visit a page that should stop in the breakpoint you set.
4. PhpStorm will ask you what mapping to use, so it can figure out how to map the path inside the container to the path on your workstation. The first time you do this with a project, PhpStorm will pop up a “server” dialog box to set the mapping. The default will work, but it’s best to click the checkbox to map the whole project directory to `/var/www/html`.

When using this zero-configuration option:

1. Use the latest DDEV version.
2. Under *Run* → *Edit Configurations*, check that there are no servers already defined. PhpStorm will create a new server for you if no others exist. You can delete all servers and have PhpStorm create a new one, or you can create/edit an existing server as discussed below.

#### PhpStorm “Run/Debug Configuration” Debugging

PhpStorm [run/debug configurations](<https://www.jetbrains.com/help/phpstorm/run-debug-configuration.html>) require more setup but may be easier and more flexible for some people.

1. Under the *Run* menu select *Edit configurations*.
2. Click the *\+* in the upper left and choose *PHP Web Page* to create a configuration. Give it a reasonable name.
3. Create a “server” for the project. Make sure *Name* is exactly the same as your host (e.g. `my-site.ddev.site`): ![PhpStorm server creation](<https://ddev.github.io/ddev/en/stable/images/phpstorm-config-server-config.png>)
4. Add file mappings for the files on the server. Click on the local repository path and add `/var/www/html` as the *Absolute path on the server* and your repository root as the path on the host.
5. Set an appropriate breakpoint.
6. Start debugging by clicking the “debug” button, which will launch a page in your browser: ![PhpStorm debug start](<https://ddev.github.io/ddev/en/stable/images/phpstorm-config-debug-button.png>)

> [!TIP]
>
> **If you’re using [additional\_hostnames](<https://ddev.github.io/ddev/en/stable/users/extend/additional-hostnames/index.md>)**
>
> If you also want Xdebug to trigger when using a URL other than the primary URL (as with `additional_hostnames` or `additional_fqdns`), create a copy of the PhpStorm `server` (Settings-\>PHP-\>Servers) with the current settings and change the host and name to the desired ones. This will tell PHP Storm to listen to that hostname with the appropriate mapping.

#### PhpStorm and Command-Line Debugging

If you need to debug command-line PHP processes, especially code that’s outside the docroot, the environment variable `PHP_IDE_CONFIG` is already set inside the web container, so you don’t have to do much more.

However, if you’ve not yet used PhpStorm with Xdebug for a regular web request, do that to automatically create the PhpStorm “server” with the same name as your primary URL (*Languages and Frameworks* → *PHP* → *Servers*). The key job of the server is to map filesystem locations on the workstation (your computer) to filesystem locations on the remote server—in this case the `ddev-webserver` container. Often, PhpStorm automatically sets up a mapping that doesn’t include the entire project, meaning things like the `vendor` directory may not be mapped. You can fix this by mapping the top-level directory of your project to `/var/www/html` in the container: ![PhpStorm mapping](<https://ddev.github.io/ddev/en/stable/images/phpstorm-server-mapping.png>)

If you encounter the error: “Can’t find a source position. Server with name ‘SITE\_NAME.ddev.site’ doesn’t exist”, change the “PHP | Servers” **Name** to **`SITE_NAME.ddev.site`**. In the example screenshot above both Name and Host are “**`d8composer.ddev.site`**”.

### Visual Studio Code (VS Code) Debugging Setup

1. Install the [PHP Debug](<https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug>) extension.
2. In the menu, choose *Run* → *Open Configuration* and add the [“Listen for Xdebug” configuration snippet](<https://ddev.github.io/ddev/en/stable/users/snippets/launch.json>) to the project’s `.vscode/launch.json`.
3. In the menu, choose *Terminal* → *Configure tasks* → *Create task.json from template* → *Others* and add the [“DDEV: Enable Xdebug” and “DDEV: Disable Xdebug” task snippet](<https://ddev.github.io/ddev/en/stable/users/snippets/tasks.json>) to the project’s `.vscode/tasks.json`.
4. Set a breakpoint in your `index.php`. If it isn’t solid red, restart.
5. In the menu, choose *Run* → *Start Debugging*. You may have to select “Listen for Xdebug” by the green arrowhead at the top left. The bottom pane of VS Code should now be orange (live) and should say “Listen for Xdebug”.
6. In a browser, visit your project and confirm you hit the breakpoint.

> [!TIP]
>
> **If you’re using VS Code on Windows with WSL2**
>
> VS Code should suggest two extensions if you have WSL2 enabled along with a PHP project: “[PHP Debug](<https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug>)” and “[WSL](<https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl>)”. You’ll need to enable both of these extensions in your distro (e.g. Ubuntu).

## Using Xdebug on a Port Other than the Default 9003

By default, DDEV is set up to contact the default port, port 9003 on your IDE. However, if you have something else listening on that port or your IDE does not yet default to 9003, you’ll need to change the port. (PhpStorm and VS Code have switch to supporting 9003 instead of 9000 for some time now.)

- To override the port, add an override file in the project’s `.ddev/php directory`. For example, a file `.ddev/php/xdebug_client_port.ini` would change to use the legacy port 9000:

  ```
  [PHP]
  xdebug.client_port=9000
  ```
- Then change your IDE’s configuration to listen on the new port.

> [!TIP]
>
> If you’re using a PHP version below 7.2, you’ll be using Xdebug version 2.x instead of 3.x and your port config should be `xdebug.remote_port` instead.

## Composer

Composer disables Xdebug even if it’s enabled in DDEV. To debug Composer itself, you need to force Xdebug to stay active.

According to the [Composer docs](<https://getcomposer.org/doc/articles/troubleshooting.md#xdebug-impact-on-composer>), set the `COMPOSER_ALLOW_XDEBUG=1` [environment variable](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>) to allow all Composer commands to run with Xdebug when the extension is enabled.

> [!NOTE]
>
> **Debugging code in runtime**
>
> Composer may move some classes (like plugins) to temporary files at runtime, so IDE breakpoints may not always be triggered. Use `xdebug_break()` directly in code when needed.

## Troubleshooting Xdebug

### Use the Xdebug Diagnostics Tool

The easiest way to troubleshoot Xdebug issues is to use the (experimental) built-in diagnostic tool:

```
ddev utility xdebug-diagnose
```

This command checks your Xdebug configuration, network connectivity, and IDE settings. For a guided step-by-step diagnostic that tests your actual IDE, use:

```
ddev utility xdebug-diagnose --interactive
```

The interactive mode will walk you through each step and verify that your IDE is correctly configured and responding to Xdebug connections.

### Understanding the Xdebug Network Protocol

The basic thing to understand about Xdebug is that it’s a network protocol. Your IDE (like PhpStorm) will listen on the Xdebug port (port 9003). If Xdebug is enabled in the DDEV web container (`ddev xdebug on`), PHP inside that container will try to open a TCP connection to the IDE. Docker’s networking places the host-side listening IDE at `host.docker.internal:9003`, so you have to make sure the network connection is clear and can be made and everything should work. Firewalls may get in the way.

Here are basic steps to take to sort out any difficulty:

- Make sure your IDE is listening for Xdebug.
- If you have set the global [xdebug\_ide\_location](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>) to **anything** please reset it to defaults before continuing. It is only for a very tiny subset of users. `ddev config global --xdebug-ide-location=""` and `ddev restart`.
- `ddev logs` may show you something like `Xdebug: [Step Debug] Could not connect to debugging client. Tried: host.docker.internal:9003 (fallback through xdebug.client_host/xdebug.client_port) :-(`. If it does, it may mean that your firewall is blocking the connection, or in a small number of cases that `host.docker.internal` is not figured out successfully by DDEV or Docker. If it does:

  - Temporarily disable your firewall. On Windows/WSL this is typically Windows Defender; on macOS you’ll find it in settings; on Debian/Ubuntu it’s typically `ufw` so `sudo ufw disable`.
  - If disabling the firewall fixes the problem, re-enable the firewall and add an exception for port 9003. Your firewall will have a way to do this; on Debian/Ubuntu run `sudo ufw allow 9003`.
  - If your machine is managed by corporate endpoint security (Cisco Secure Endpoint, CrowdStrike, etc.), it may block container → host connections even when the OS firewall is “off”:

    - If possible, temporarily disable the endpoint security agent and try again.
    - If you can’t disable it, ask your IT/security team to allow inbound connections to your IDE on port 9003 from the container/VM subnet(s).
    - On macOS/Linux, you can confirm whether traffic is reaching the host by watching for packets while connecting from the container:

      ```
      # On the host (in one terminal)
      sudo tcpdump -ni any tcp port 9003

      # In the web container (in another terminal)
      ddev exec nc -vz -w2 host.docker.internal 9003
      ```

      If `tcpdump` shows nothing while `nc` runs, something upstream (often endpoint security) is filtering the traffic.
- Delete existing PhpStorm “servers” in settings, or recreate VS Code’s `launch.json` file exactly as shown in the instructions here.
- Remember the standard Xdebug port is port 9003, and that’s what all instructions here use. In the past some IDEs used port 9000.
- If your `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) has `xdebug_ide_location` set, remove that to begin with except for [very unusual situations](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>). You can set it to the default value with `ddev config global --xdebug-ide-location=""`.
- Reboot your computer.
- If you’re running WSL2 and have PhpStorm running inside WSL2 (the Linux version of PhpStorm) then `ddev config global --xdebug-ide-location=wsl2`. (This is very unusual.)
- Temporarily disable any *firewall* or *VPN* if you’re having trouble. Xdebug is a network protocol, and the PHP process inside the web container must be able to establish a TCP connection to the listening IDE (PhpStorm, for example).
- Confirm that DDEV’s [`xdebug_ide_location`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>) config setting is set properly, which in most cases should be set to an empty string. Check both your project’s `.ddev/config.yaml` and DDEV’s global `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)).
- Use `ddev xdebug on` to enable Xdebug when you want it, and `ddev xdebug off` when you’re done with it.
- You can also use `ddev xdebug toggle` to easily toggle Xdebug on and off.
- Set a breakpoint at the first executable line of your `index.php`.
- Tell your IDE to start listening. (PhpStorm: click the bug-listen button, VS Code: run the debugger.)
- Use `curl` or a browser to create a web request. For example, `curl https://d11.ddev.site` or run `ddev exec curl localhost`.
- `ddev ssh` into the web container. Can you run `telnet host.docker.internal 9003` and have it connect? If not, follow the instructions above about disabling firewall and adding an exception for port 9003.
- In PhpStorm, disable the “listen for connections” button so it won’t listen. Or exit PhpStorm. With another IDE like VS Code, stop the debugger from listening.
- `ddev ssh` into the web container. Can you run `telnet host.docker.internal 9003` and have it connect? If so, you have something else running on port 9003. On the host, use `sudo lsof -i :9003 -sTCP:LISTEN` to find out what’s there and stop it. Don’t continue debugging until your telnet command does not connect. (On Windows WSL2 you may have to look for listeners both inside WSL2 and on the Windows side.)
- Now click the “listen” button on PhpStorm to start listening for connections.
- `ddev ssh` and try the `telnet host.docker.internal 9003` again. It should connect. If not, maybe PhpStorm is not listening, or not configured to listen on port 9003?
- Check to make sure that Xdebug is enabled. You can use `php -i | grep -i xdebug` inside the container, or use any other technique you want that gives the output of `phpinfo()`, including Drupal’s `admin/reports/status/php`. You should see `with Xdebug v3` and `php -i | grep xdebug.mode` should give you `xdebug.mode => debug,develop => debug,develop"`.
- Set a breakpoint in the first relevant line of your `index.php` and then visit the site in a browser. It should stop at that first line.
- If you’re using a flavor of IDE that connects directly into the web container like VS Code Language Server, you may want to use the [global `xdebug_ide_location` setting](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>) to explain to DDEV the situation. For example, `ddev config global --xdebug-ide-location=container`, which tells the PHP/Xdebug to connect directly to the listener inside the container.
- To find out what DDEV is using for the value of `host.docker.internal` you can run `DDEV_DEBUG=true ddev start` and it will explain how it’s getting that value, which help troubleshoot some problems. You’ll see something like `host.docker.internal='' because no other case was discovered` which can explain the usage.

### WSL2 Xdebug Troubleshooting

WSL2 is a complicated environment for Xdebug, especially if you’re running your IDE on the Windows side, as most people do.

- Use `ddev utility xdebug-diagnose --interactive`, which normally will uncover any issues.
- When using an IDE inside WSL2—like you would when running PhpStorm or Visual Studio Code inside WSL2, or using PhpStorm’s “Remote Development” feature—you may need to use the [`xdebug_ide_location`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#xdebug_ide_location>) setting to tell Xdebug to expect the IDE under WSL2. You can do this by running `ddev config global --xdebug-ide-location=wsl2`. This is very unusual.
- `export DDEV_DEBUG=true && ddev start` will show you how DDEV is calculating the `host.docker.internal` IP address to be used when contacting the IDE, which may give a hint about problems you might discover in the general troubleshooting discussed above, when trying to connect to the listening IDE.
- If you’re using docker-ce and have the IDE on the Windows side, `ip -4 route show default` in the WSL2 distro is the best known way to figure out where the IDE is in the Windows networking scheme, so DDEV uses that to determine `host.docker.internal`. That value should be the same as `host.docker.internal`, so running `ddev exec ping -c 1 host.docker.internal` will show you what’s actually being used. If your IDE is actually at a different address, you can tell DDEV to override the discovered value for `host.docker.internal` by running `ddev config global --xdebug-ide-location=<some_ip_address>`.
- If you’re using PhpStorm inside WSL2 (or perhaps other Linux configurations), go to *Help* → *Edit Custom VM Options* and add an additional line: `-Djava.net.preferIPv4Stack=true` This makes PhpStorm listen for Xdebug using IPv4; the Linux version of PhpStorm seems to default to using only IPv6.
- If you’re on WSL2 using Docker Desktop, make sure that the `docker` command is the one provided by Docker Desktop. `ls -l $(which docker)` should show a link to `/mnt/wsl/docker-desktop...`. If you’re on WSL2 using Docker installed inside WSL2, make sure that `ls -l $(which docker)` is *not* a link to `/mnt/wsl`.
- You can run `export DDEV_DEBUG=true` and `ddev start` to get information about how `host.docker.internal` is figured out, which can help in some situations especially with WSL2. (`host.docker.internal` inside the web container is where Xdebug thinks it should connect to your IDE. You can see what it is set to by running `ddev exec ping host.docker.internal`.)
- On some WSL2 docker-ce systems you may have to work hard to find out the correct IP address for the Windows side. DDEV tries to figure this out for you, but it may not be able to do so. The IP address shown as `nameserver` in `/etc/resolv.conf` may be the correct one, and this used to be the recommended technique. If it’s the address you need you can change the address DDEV will use for `host.docker.internal` using `ddev config global --xdebug-ide-location=<some-ip-address>`.
- WSL2 networking can sometimes become corrupted. If `ping host.docker.internal` from inside the DDEV web container fails, and `telnet host.docker.internal 9003` also fails even when your IDE is listening, the most common cause is the Windows Firewall (see above). However, the WSL2 virtual switch or `HNS` networking layer may also be damaged. You can repair this by fully disabling and then re-enabling the Windows Subsystem for Linux and Virtual Machine Platform features. This forces Windows to rebuild the WSL2 networking stack without deleting any of your Linux distros. This is safe and does not destroy your WSL2 distro.
- **WSL2 Mirrored Networking Mode:** Requires `hostAddressLoopback=true` in your Windows-side `~/.wslconfig`.
- **WSL2 VirtioProxy Networking Mode (experimental):** If you’re using `networkingMode=VirtioProxy` in your Windows-side `~/.wslconfig`, DDEV supports Xdebug experimentally. On some systems where Windows creates a `vEthernet (WSL)` Hyper-V adapter, DDEV can discover the Windows host IP and a Windows-side IDE works. On most systems we’ve tested, though, Docker containers have no network path to the Windows host; in that case run your IDE inside WSL2: `ddev config global --xdebug-ide-location=wsl2`. Run `ddev utility xdebug-diagnose --interactive` to check your configuration.

# Xdebug Profiling

Although DDEV has more sophisticated profiling capabilities with [xhprof](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/xhprof-profiling/index.md>) and [Blackfire](<https://ddev.github.io/ddev/en/stable/users/debugging-profiling/blackfire-profiling/index.md>), it also has built-in support for [Xdebug profiling](<https://xdebug.org/>).

## Basic usage

- Create the directory `.ddev/xdebug`, which is where the output files will be dumped.
- Switch Xdebug to profiling mode by adding this in `.ddev/php/xdebug.ini`:

  ```
  xdebug.mode=profile
  xdebug.start_with_request=yes
  xdebug.output_dir=/var/www/html/.ddev/xdebug
  xdebug.profiler_output_name=trace.%c%p%r%u.out
  ```
- Enable Xdebug with [`ddev xdebug on`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xdebug>).
- Make an HTTP request to the DDEV project and the profile will be located in `.ddev/xdebug` directory.
- Analyze it with any call graph viewer, for example [kcachegrind](<https://kcachegrind.github.io/html/Home.html>).
- When you’re done, execute `ddev xdebug off` to avoid generating unneeded profile files.
- You can also toggle Xdebug on and off using `ddev xdebug toggle`.

## Information Links

- [Xdebug profiling docs](<https://xdebug.org/docs/profiler>)
- [kcachegrind](<https://kcachegrind.github.io/html/Home.html>)

# xhprof Profiling

DDEV has built-in support for [xhprof](<https://www.php.net/manual/en/book.xhprof.php>). The official PECL xhprof extension only supports PHP \>=7.x.

## Simplest XHProf Usage With XHGui

In DDEV v1.24.4+ you can switch to the XHGui profiling mode (permanently) with:

```
ddev config global --xhprof-mode=xhgui && ddev restart
```

Start profiling with:

```
ddev xhgui on
```

Visit a few pages in your app to collect profiling data, then:

```
ddev xhgui launch
```

The easiest way to work with XHProf is to turn on XHGui, `ddev config global --xhprof-mode=xhgui`.

You can launch the web interface with:

```
ddev xhgui
```

More details in [XHGui Feature Makes Profiling Even Easier](<https://ddev.com/blog/xhgui-feature/>).

## Traditional XHProf Usage with `prepend`

If you are having issues with XHGui, you can go back to the regular xhprof web interface.

- Use the `prepend` mode, `ddev config global --xhprof-mode=prepend`.
- Enable xhprof with [`ddev xhprof on`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#xhprof>) (or `ddev xhprof` or `ddev xhprof enable`) and check its status with `ddev xhprof status`.
- `ddev xhprof on` will show you the URL you can use to see the xhprof analysis, `https://<projectname>.ddev.site/xhprof` shows recent runs. (It’s often useful to keep a tab or window open with this URL and refresh as needed.)
- Use a web browser or other technique to visit a page whose performance you want to study. To eliminate first-time cache-building issues, you may want to hit it twice.
- Visit one of the links provided by `ddev xhprof on` and study the results.
- On the profiler output page, you can drill down to the function that you want to study, or use the graphical “View Full Callgraph” link. Click the column headers to sort by number of runs and inclusive or exclusive wall time, then drill down into the function you want to study and do the same.
- The runs are erased on [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
- If you’re using Apache with a custom `.ddev/apache/apache-site.conf`, you’ll need to make sure it includes `Alias "/xhprof" "/var/xhprof/xhprof_html"` from DDEV’s [default apache-site.conf](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/webserver_config_assets/apache-site-php.conf>).

For a tutorial on how to study the various xhprof reports, see the section “How to use XHPROF UI” in [A Guide to Profiling with XHPROF](<https://inviqa.com/blog/profiling-xhprof>). It takes a little time to get your eyes used to the reporting. (You don’t need to do any of the installation described in that article!)

## Advanced XHProf `prepend` Configuration

You can change the contents of the `xhprof_prepend` function in `.ddev/xhprof/xhprof_prepend.php`.

For example, you may want to add a link to the profile run to the bottom of the profiled web page. The provided `xhprof_prepend.php` has comments and a sample function to do that, which works with Drupal 7. If you change it, remove the `#ddev-generated` line from the top, and check it in (`git add -f .ddev/xhprof/xhprof_prepend.php`).

Another example: you could exclude memory profiling so there are fewer columns to study. Change `xhprof_enable(XHPROF_FLAGS_MEMORY);` to `xhprof_enable();` in `.ddev/xhprof/xhprof_prepend.php` and remove the `#ddev-generated` at the top of the file. See the docs on [xhprof\_enable()](<https://www.php.net/manual/en/function.xhprof-enable.php>).

## Information Links

- [php.net xhprof](<https://www.php.net/manual/en/book.xhprof.php>)
- [Old Facebook xhprof docs](<https://web.archive.org/web/20110514095512/http://mirror.facebook.net/facebook/xhprof/doc.html>)
- [pecl.php.net docs](<https://pecl.php.net/package/xhprof>)
- [Upstream GitHub repository `lonngxhinH/xhprof`](<https://github.com/longxinH/xhprof>)

# Hosting and Deployment

# Hosting with DDEV

> [!WARNING]
>
> **Experimental Feature!**
>
> Hosting with DDEV is not a replacement for scalable, managed hosting. It is not known how much traffic can be handled this way. Lots of people really like it for a number of uses though.

Lightweight hosting with Let’s Encrypt for HTTPS support is a popular DDEV feature. You can run DDEV on a public web server, point DNS to it, and use it as a hosting environment.

This can be appropriate for many sites with modest traffic expectations, and works great for sites with special requirements (old versions of PHP, old database servers, etc.) A number of teams use it for continuous integration (CI) and for staging and demonstration sites.

There is no security team behind this approach, although efforts have been made to secure the approach with hardened Docker images and removal of tools like `sudo`.

Here’s how to try it for yourself:

1. Install DDEV on an internet-connected Linux server. (You’re responsible for your firewall and maintenance of the server!)
2. On Debian/Ubuntu, you can set up a simple firewall with  
   `ufw allow 80 && ufw allow 443 && ufw allow 22 && ufw enable`.
3. Point DNS for the site you’re going to host to the server.
4. Before proceeding, your system and your project must be accessible on the internet on port 80 and your project DNS name (`myproject.example.com`) must resolve to the appropriate server.
5. Configure your project with [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).
6. Import your database and files using [`ddev import-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-db>) and [`ddev import-files`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-files>).
7. Save all databases with `ddev snapshot --all` before beginning, so you can restore your database if you have to change the name of the project.
8. Tell DDEV to listen on all network interfaces, omit the SSH agent, use hardened images, and enable Let’s Encrypt:

   ```
   ddev config global --router-bind-all-interfaces --omit-containers=ddev-ssh-agent --use-hardened-images --performance-mode=none --use-letsencrypt --letsencrypt-email=you@example.com
   ```
9. Use a `.ddev/config.prod.yaml` to provide overrides for project configuration, rather than changing the `.ddev/config.yaml`, so that your checked-in local development code works as well as possible. An example `.ddev/config.prod.yaml` might be:

   ```
   project_tld: com
   additional_hostnames:
       - hobobiker
       - www.hobobiker
   timezone: America/Denver
   ```

   > **Complex configuration with apex domains**
   >
   > Unfortunately, the `traefik` integration with Let’s Encrypt does not work if you have hostnames specified that are not resolvable, so every single hostname referenced must be resolvable in DNS. (You can use `additional_fqdns` as well as `additional_hostnames`, but all combinations must be resolvable in DNS.) Some examples:
   >
   > **Project name = example, URL = `example.com`, also serving `www.example.com` and `mysite.com`**
   >
   > ```
   > project_tld: com
   > name: example
   > additional_hostnames:
   >     - www.example
   > additional_fqdns:
   >     - mysite.com
   > ```
   >
   > **Project name = `stories`, URL = `stories.example.org`**
   >
   > ```
   > name: stories
   > project_tld: example.org
   > ```
10. If you want to redirect HTTP to HTTPS, edit the `.ddev/traefik/config/<projectname>.yaml` to remove the `#ddev-generated` and uncomment the `middlewares:` and `- "redirectHttps"` lines in the HTTP router section.
11. Run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and visit your site. With some CMSes, you may also need to clear your cache.
12. If you see trouble with Let’s Encrypt `ACME` failures, you can temporarily switch to the `ACME` staging server, and avoid getting rate-limited while you are experimenting. The certificates it serves will not be valid, but you’ll see that they’re coming from Let’s Encrypt anyway. Add a `$HOME/.ddev/traefik/static_config.staging.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) with the contents:

    ```
    certificatesResolvers:
        acme-tlsChallenge:
            acme:
                caServer: "https://acme-staging-v02.api.letsencrypt.org/directory"
    ```

You may have to restart DDEV with `ddev poweroff && ddev start --all` if Let’s Encrypt has failed for some reason or the DNS name is not yet resolving. (Use `docker logs -f ddev-router` to see Let’s Encrypt activity.)

## Additional Server Setup

- Depending on how you’re using this, you may want to set up automated database and file backups—ideally off-site—like you would on any production system. Many CMSes have modules/plugins to allow this, and you can use `ddev export-db` or `ddev snapshot` as you see fit and do the backup on the host.
- You may want to allow your host system to send email. On Debian/Ubuntu `sudo apt-get install postfix`. Typically you’ll need to set up reverse DNS for your system, and perhaps SPF and/or DKIM records to for more reliable delivery to other mail systems.
- You may want to generally tailor your PHP settings for hosting rather than local development. Error-reporting defaults in `php.ini`, for example, may be too verbose and expose too much information publicly. You may want something less:

  ```
  ; Error handling and logging
  error_reporting = E_ALL
  display_errors = On
  display_startup_errors = On
  log_errors = On
  ```
- To make DDEV start sites on system boot, you’ll want to set up a `systemd` unit on systems like Debian/Ubuntu and Fedora. For example, a file named `/etc/systemd/system/ddev.service` containing:

  ```
  # Start DDEV when system starts (after Docker)
  # Stop DDEV when Docker shuts down
  # Start with `sudo systemctl start ddev`
  # Enable on boot with `sudo systemctl enable ddev`
  # Make sure to edit the User= for your user and the
  # full path to `ddev` on your system.
  # Optionally give a list of sites instead of --all
  [Unit]
  Description=DDEV sites
  After=multi-user.target
  Requires=docker.service
  PartOf=docker.service
  [Service]
  User=rfay
  Type=oneshot
  ExecStart=/usr/local/bin/ddev start --all
  RemainAfterExit=true
  ExecStop=/usr/local/bin/ddev poweroff

  [Install]
  WantedBy=multi-user.target
  ```
- You’ll likely want to turn off PHP errors to screen in a `.ddev/php/noerrors.ini`:

  ```
  display_errors = Off
  display_startup_errors = Off
  ```
- While a project is stopped or restarting, visitors see DDEV’s page for unmatched hostnames, which reveals that the site runs on DDEV. To show your own maintenance page instead, see [Custom Maintenance Page](<https://ddev.github.io/ddev/en/stable/users/extend/traefik-router/#custom-maintenance-page>).

## Troubleshooting

- `docker logs -f ddev-router` is a great way to see what’s going on with the router, including all requests and attempts at getting certificates from Let’s Encrypt.
- You may want to see more than just error output. You can enable debug output with the command below (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)). You can make additional changes to the logging level as needed.

  ```
  cp $HOME/.ddev/traefik/static_config.loglevel.yaml.example $HOME/.ddev/traefik/static_config.loglevel.yaml
  ddev poweroff
  ```
- Do not rename projects without going through the proper process in the [FAQ](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#how-can-i-change-a-projects-name>), and make sure you don’t have conflicting `additional_hostnames` or `additional_fqdns` between projects.
- If you’re having trouble with a particular project’s Traefik configuration, try `docker exec -it ddev-router bash -c "rm -f config/<projectname>.yaml"` and `rm -rf .ddev/traefik` in the project, then `ddev poweroff && ddev start`. This deletes all existing Traefik configuration for that project and it will be regenerated.

### Let’s Encrypt Errors

These show up in the router logs (`docker logs -f ddev-router`).

> `ERR Unable to obtain ACME certificate for domains error="unable to generate a certificate for the domains [project.ddev.tld livedomain.com]: error: one or more domains had a problem:\n[livedomain.com]`

A message like this means your DNS is wrong. Make sure the domain resolves to your server.

---

> `ERR Unable to obtain ACME certificate for domains error="unable to generate a certificate for the domains [project.ddev.live]: acme: error: 429 :: POST :: https://acme-v02.api.letsencrypt.org/acme/new-order :: urn:ietf:params:acme:error:<strong>rateLimited :: too many failed authorizations</strong> (5) for \"project.ddev.live\" in the last 1h0m0s, retry after 2026-07-01 12:19:07 UTC: see https://letsencrypt.org/docs/rate-limits/#authorization-failures-per-identifier-per-account"`

A message like this means you’ve been rate-limited. Let’s Encrypt tries to create certificates for *all* of your sites on the server, so make sure every domain for every site resolves — otherwise DDEV will keep retrying and you risk hitting the rate limit, even if DNS resolves and you’ve tried `ddev restart`.

## Caveats

- It’s unknown how much traffic a given server and Docker setup can sustain, or what the results will be if the traffic is more than the server can handle.
- DDEV does not provide outgoing SMTP mail handling service, and the development-focused Mailpit feature is disabled if you’re using `use_hardened_images`. You can provide SMTP service a number of ways, but the recommended way is to use SMTP in your application via a third-party transactional email service such as [SendGrid](<https://sendgrid.com>), [Postmark](<https://postmarkapp.com>), or [Mailgun](<https://www.mailgun.com>). This is the best way to ensure mail is actually delivered.
- You may need an external cron trigger for some CMSes.
- Debugging Let’s Encrypt failures requires viewing the `ddev-router` logs with `docker logs ddev-router`.
- A malicious attack on a website hosted with `use_hardened_images` will likely not be able to do anything significant to the host, but it can certainly change your code, which is mounted on the host.

When `use_hardened_images` is enabled, Docker runs the web image as an unprivileged user, and the container does not have sudo. However, any Docker server hosted on the internet is a potential vulnerability. Keep your packages up to date and make sure your firewall does not allow access to ports other than (normally) 22, 80, and 443.

There are no warranties implied or expressed.

# Hosting, Deployment, and Sharing

DDEV does not provide capabilities for deploying your code, as it’s focused on being a **local development** solution. Teams almost universally use Git to manage their code and some Git provider like GitHub or GitLab to store it. They use many different types of deployment tools to actually get the code to their upstream servers or integration environments. For local development, DDEV provides capabilities to pull upstream databases and user-generated files as well as push those in some circumstances.

- [Sharing your project](<https://ddev.github.io/ddev/en/stable/users/topics/sharing/index.md>)
- [Hosting with DDEV](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>)
- [Remote Docker environments](<https://ddev.github.io/ddev/en/stable/users/topics/remote-docker/index.md>)
- [Hosting integrations](<https://ddev.github.io/ddev/en/stable/users/providers/index.md>) including Acquia, Lagoon, Pantheon, Upsun, rsync-based solutions, Git-based solutions, local files (like Dropbox), etc.

# Remote Docker Environments

## Remote Docker Instances

You can use remote Docker instances, whether on the internet, inside your network, or running in a virtual machine. This lets you offload Docker resource usage from your local machine, which can improve battery life and performance on less powerful devices.

### Connecting to the Remote Docker Host

There are two main ways to connect to a remote Docker instance:

#### SSH-Based Docker Context (Recommended)

The SSH approach is more secure because it uses your existing SSH authentication and does not require exposing the Docker port on the network:

```
docker context create remotedocker --docker "host=ssh://user@remote-host"
docker context use remotedocker
```

#### TCP-Based Docker Context

You can expose the Docker API over TCP, but **be aware that this has serious security implications**. See [instructions](<https://gist.github.com/styblope/dc55e0ad2a9848f2cc3307d4819d819f>) for how to do this on a systemd-based remote server. `dockerd` will warn:

> Binding to IP address without `--tlsverify` is insecure and gives root access on this machine to everyone who has access to your network. host=”tcp://0.0.0.0:2375”.

```
docker context create remote --docker "host=tcp://remote-host:2375"
docker context use remote
```

If you do not already have the Docker client installed (like you would from Docker Desktop), install *only* the client with `brew install docker`.

Verify your connection with `docker ps`.

### Required DDEV Configuration

- **Disable bind mounts**: Bind mounts cannot work with a remote Docker setup, so you must use `ddev config global --no-bind-mounts`. This causes DDEV to push needed information to and from the remote Docker instance when needed. This also automatically turns on Mutagen caching.

### Accessing Your Sites

The DDEV site will *not* be at `127.0.0.1`. You have two options:

- **SSH tunnel**: Forward DDEV ports (like 8080, 8443) from the remote host to your local machine. This lets you access sites at `localhost:<port>` without exposing ports on the remote host.
- **Direct access with custom FQDN**: Use `ddev config --additional-fqdns=remote-host` and access the site at `https://remote-host`. If the Docker host is reachable on the internet, you can enable real HTTPS using Let’s Encrypt as described in [Hosting with DDEV](<https://ddev.github.io/ddev/en/stable/users/topics/hosting/index.md>). Make sure port 2375 is not available on the internet.

## Continuous Integration (CI)

A number of people have found it easy to test their projects using DDEV on a CI system like GitHub Actions, Travis CI, or CircleCI. Instead of setting up a hosting environment for testing, they start the project using DDEV and run their tests.

Examples of this approach are demonstrated in [Codeception Tests in Travis CI with DDEV and Selenium](<https://dev.to/tomasnorre/codeception-tests-in-travis-ci-with-ddev-and-selenium-1607>) and [Setup DDEV in GitHub Workflows](<https://github.com/marketplace/actions/setup-ddev-in-github-workflows>).

## Integration of DDEV Docker Images Into Other Projects

You can use DDEV Docker images outside the context of the DDEV environment. People have used the `ddev-webserver` image for running tests in PhpStorm, for example.

# Sharing Your Project

Even though DDEV is intended for local development on a single machine, not as a public server, there are a number of reasons you might want to expose your work in progress more broadly:

- Testing with a mobile device
- Sharing on a local network so that everybody on the local network can see your project
- Some CI applications

There are at least three different ways to share a running DDEV project outside the local developer machine:

- [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) (using a tunnel provider like ngrok or cloudflared to share over the internet)
- Local name resolution and sharing the project on the local network
- Sharing the HTTP port of the local machine on the local network

## Using `ddev share` (Easiest)

`ddev share` proxies the project via a tunnel provider for sharing your project with others on your team or around the world. DDEV supports multiple providers:

- **ngrok** (default) - Requires an [ngrok.com](<https://ngrok.com>) account
- **cloudflared** - Free, no account required. Requires [cloudflared](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation>) to be installed
- **Custom providers** - You can add your own providers in `.ddev/share-providers/`

Run `ddev share` to use the default provider, or `ddev share --provider=cloudflared` to use a specific provider. The URL will be displayed, along with a QR code you can scan with a mobile device, and can be shared with collaborators.

CMSes like WordPress and Magento 2 make this a little harder by only responding to a single base URL that’s coded into the database. ngrok allows you to use one static domain for free so you won’t have to frequently change the base URL. Cloudflared stable custom domains require a free Cloudflare account and a domain with DNS hosted on Cloudflare.

## Using ngrok

[ngrok](<https://ngrok.com/docs/what-is-ngrok>) is the traditional tunneling solution used by DDEV. It requires an ngrok account (free or paid) and the free account allows you to create tunnels with random URLs or a single static URL.

### Installing ngrok

1. Create an ngrok account at [ngrok.com](<https://ngrok.com/signup>).
2. Install ngrok with one of [many techniques](<https://ngrok.com/download/mac-os>) including `brew install ngrok` (macOS) or `snap install ngrok` (Linux/WSL2).
3. Get your token from the [dashboard](<https://dashboard.ngrok.com/get-started/your-authtoken>).
4. Connect ngrok to your account with `ngrok config add-authtoken <your-token>`.

### Using your stable ngrok domain

All ngrok accounts come with a free stable domain that is automatically chosen when you use ngrok via `ddev share` or otherwise. You’ll see it the first time you use `ddev share`. No configuration is necessary.

## Using Cloudflared

[Cloudflared](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/>) is a free alternative to ngrok that doesn’t require an account. Each tunnel gets a random temporary URL like `https://example-name.trycloudflare.com`.

### Prerequisites

Install cloudflared from [Cloudflare’s installation guide](<https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation>).

### Usage

```
# Use cloudflared for a single share session
ddev share --provider=cloudflared

# Set cloudflared as default for all projects
ddev config global --share-default-provider=cloudflared

# Set cloudflared as default for current project only
ddev config --share-default-provider=cloudflared
```

The provider priority is: command-line flag \> project config \> global config \> default (ngrok).

### Cloudflared Configuration

You can configure cloudflared arguments in your `.ddev/config.yaml`:

```
share_provider_args: "--your-args-here"
```

Or pass them on the command line:

```
ddev share --provider=cloudflared --provider-args="--your-args-here"
```

### Setting up a Stable Cloudflared Domain

If you have a domain managed by Cloudflare, you can use a named tunnel for a stable, permanent URL instead of the random `trycloudflare.com` URLs.

#### Cloudflared Static Domain Requirements

- A domain managed by Cloudflare (DNS hosted on Cloudflare)
- cloudflared installed and authenticated: `cloudflared tunnel login`

#### Setup Steps

1. **Create a named tunnel:**

   ```
   cloudflared tunnel create my-ddev-tunnel
   ```

   This creates a tunnel and saves credentials in `~/.cloudflared/`.

   > **Multiple Tunnels**
   >
   > You can create multiple named tunnels for different projects. Each tunnel needs a unique name and DNS record.
2. **Add a DNS route for your tunnel:**

   ```
   cloudflared tunnel route dns my-ddev-tunnel mysite.example.com
   ```

   This creates a `CNAME` record pointing your subdomain to the tunnel.
3. **Configure DDEV to use the named tunnel:**

   ```
   ddev config --share-provider-args="--tunnel my-ddev-tunnel --hostname mysite.example.com"
   ```

   Or add to `.ddev/config.yaml`:

   ```
   share_provider_args: --tunnel my-ddev-tunnel --hostname mysite.example.com
   ```
4. **Share your project:**

   ```
   ddev share --provider=cloudflared
   ```

   Or use `--provider-args` to pass the tunnel configuration on the command line:

   ```
   ddev share --provider=cloudflared --provider-args="--tunnel my-ddev-tunnel --hostname mysite.example.com"
   ```

   Your project will be available at `https://mysite.example.com`.

## Special Handling for Complex CMSes

Some CMSes like WordPress and Magento require special handling because they don’t automatically handle the URL routed to them. For more extensive instructions and possibilities, read the [DDEV Share Blog](<https://ddev.com/blog/share-providers/>).

### TYPO3 special handling: Strip the host from `base`

TYPO3’s site configuration (`config/sites/<identifier>/config.yaml`) stores an absolute `base` URL for each site, for example:

```
base: 'https://typo3.ddev.site/'
```

TYPO3 only routes requests whose Host header exactly matches `base`, so an ngrok or cloudflared tunnel hostname will 404 until `base` is adjusted.

**Simplest fix (permanent):** Set `base: /` (or `/your-path/` if the site normally lives under a subpath) by hand, then run `ddev typo3 cache:flush` to clear the derived routing caches. This works indefinitely for local development and needs no further changes.

**Automatic fix (reversible, multi-site-safe):** Use `pre-share`/`post-share` hooks to strip only the scheme and host from `base`, preserving any existing path. This matters for multi-site projects — commenting out or blanking every `base` collapses all sites to the same host-less `/` route and only one wins; stripping just the host keeps each site’s own path distinct:

```
hooks:
  pre-share:
    - exec: |
        for f in config/sites/*/config.yaml; do
          cp "$f" "$f.pre-share-backup"
          newbase=$(yq '.base' "$f" | sed -E 's#^https?://[^/]+##')
          [ -z "$newbase" ] && newbase="/"
          yq -i ".base = \"$newbase\"" "$f"
        done
        typo3 cache:flush
  post-share:
    - exec: |
        for f in config/sites/*/config.yaml.pre-share-backup; do
          mv "$f" "${f%.pre-share-backup}"
        done
        typo3 cache:flush
```

This doesn’t handle `baseVariants` entries or per-language `base` overrides, which are more advanced, less common setups. (See the [DDEV Share Blog](<https://ddev.com/blog/share-providers/>) for more on writing `pre-share`/`post-share` hooks.)

### WordPress special handling: Change the URL using `wp search-replace`

WordPress only has the one base URL, but the `wp` command is built into DDEV’s web container.

This set of steps assumes an ngrok domain of `nonportentously-caulicolous-cedrick.ngrok-free.dev` and a starting URL of `https://wordpress.ddev.site`.

- Configure `.ddev/config.yaml` to use a custom domain: `share_provider_args: --domain nonportentously-caulicolous-cedrick.ngrok-free.dev`.
- Make a backup of your database with [`ddev export-db`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#export-db>) or [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>).
- Edit `wp-config-ddev.php` (or whatever your config is) to change `WP_HOME`, for example, `define('WP_HOME', 'https://nonportentously-caulicolous-cedrick.ngrok-free.dev');`
- `ddev wp search-replace https://wordpress.ddev.site https://nonportentously-caulicolous-cedrick.ngrok-free.dev`, assuming your project is configured for `https://wordpress.ddev.site` and your `share_provider_args` are configured for the `nonportentously-caulicolous-cedrick.ngrok-free.dev` domain.
- Now run [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>).

(This can also be done with `pre-share` and `post-share` hooks, see the [DDEV Share Blog](<https://ddev.com/blog/share-providers/>).)

### Magento2 special handling: Change the URL with Magento Tool

This set of steps assumes an ngrok domain `nonportentously-caulicolous-cedrick.ngrok-free.dev`:

- Configure `.ddev/config.yaml` to use a custom domain with `share_provider_args: --domain nonportentously-caulicolous-cedrick.ngrok-free.dev`.
- Make a backup of your database.
- Run [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>).
- Run `bin/magento setup:store-config:set --base-url="https://nonportentously-caulicolous-cedrick.ngrok-free.dev/"`.
- Run [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) and you’ll see your project at `nonportentously-caulicolous-cedrick.ngrok-free.dev`.

(This can also be done with `pre-share` and `post-share` hooks, see the [DDEV Share Blog](<https://ddev.com/blog/share-providers/>).)

## Using Custom Share Providers

You can customize the built-in providers or create your own share providers. See [Custom Share Providers](<https://ddev.github.io/ddev/en/stable/users/extend/share-providers/index.md>) for details.

## Using nip.io or Custom Name Resolution Locally

Another solution is to **not** use `*.ddev.site` as your project URLs, but to use DNS that you control and that points to the host machine where your project lives. In general, you’ll want to use HTTP URLs with this approach, because it requires manual configuration of the client machine to get it to trust the development certificate that DDEV uses and configures with `mkcert` on the local machine.

- Use [nip.io](<http://nip.io/>) to point a domain name to your host. If your computer’s IP address is 192.168.5.101, you can use a domain name like `mysite.192.168.5.101.nip.io` and that domain name will point to your computer. Add that to your project’s `additional_fqdns` with `ddev config --additional-fqdns=mysite.192.168.5.101.nip.io` and [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). Now people in your internal network should be able to `ping mysite.192.168.5.101.nip.io` if your firewall allows it. (If you have other convenient ways to create a DNS entry for this, you can use those instead of nip.io.)
- Configure `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) to bind to all ports: `ddev config global --router-bind-all-interfaces && ddev poweroff && ddev start`.
- Now mobile apps or other computers which are on your **local** network should be able to access your project. Use the HTTP URL rather than the HTTPS URL because computers outside yours don’t know how to trust the developer TLS certificate you’re using. (You can run [`ddev describe`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#describe>) to see the HTTP URL, but it’s typically the same as the HTTPS URL, but with `http` instead of `https`.)
- Make sure your firewall allows access from your local network to the main interface you’re using. In the example here, you should be able to ping 192.168.5.101 and `curl http://192.168.5.101` and get an answer in each case.
- If you’re using WordPress or Magento 2, you’ll need to change the base URL as described in the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) instructions above.

## Exposing a Host Port and Providing a Direct URL

DDEV’s web container also exposes an HTTP port directly, in addition to the normal routing by name and via `ddev_router`. You can expose this port and it may be a useful approach in some situations.

- Configure the project `host_webserver_port` to a known port (that does not conflict with already configured ports). For example, using port 8080, `ddev config --host-webserver-port=8080 --bind-all-interfaces`. This will configure the host-bound port to 8080 and allow it to bind to all network interfaces so colleagues (or hackers) on your local network can access this project’s ports.
- Make sure your firewall allows access to the port on your host machine.
- If you’re using WordPress or Magento 2 you’ll need to change the base URL as described in the [`ddev share`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#share>) instructions above.
- Each project on your computer must use different ports, or you’ll have port conflicts, and you can’t typically use ports 80 or 443 because `ddev-router` is already using those for normal routing.
- If you don’t want to run `ddev-router` at all, you can omit it globally with `ddev config global --omit-containers=ddev-router`. This is a specialty thing to do when you don’t need the reverse proxy.

Computers and mobile devices on your local network should now be able to access port 8080, on the (example) host address 192.168.5.23, so `http://192.168.5.23:8080` You’ll probably want to use the HTTP URL; your coworker’s browser will not trust the developer TLS certificate you’re using.

# Acquia Integration

DDEV provides integration with the [Acquia Cloud Platform](<https://www.acquia.com/choosing-right-acquia-cloud-platform>), which allows Acquia users to quickly download and provision a project from Acquia in a local DDEV-managed environment.

DDEV’s Acquia integration pulls database and files from an existing project into your local system so you can develop locally.

## Acquia Quickstart

1. Get your Acquia API token from *Account Settings* → *API Tokens*.
2. Make sure you’ve added your SSH key to your Acquia account in *Account Settings* → *SSH Keys*.
3. Run [`ddev auth ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#auth-ssh>). (Typically once per DDEV session, not every pull.)
4. In `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)) add or update the [`web_environment`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#web_environment>) section with the API keys:

   ```
   web_environment:
       - ACQUIA_API_KEY=xxxxxxxx
       - ACQUIA_API_SECRET=xxxxx
   ```

   You can also do this with:

   ```
   ddev config global --web-environment-add="ACQUIA_API_KEY=xxxxxxxx,ACQUIA_API_SECRET=xxxxx"
   ```

   > **What if I have more than one API key?**
   >
   > To use multiple API keys for different projects, add them to your per-project configuration using the [`.ddev/config.local.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) file instead. This file is gitignored by default.
   >
   > ```
   > web_environment:
   >     - ACQUIA_API_KEY=xxxxxxxx
   >     - ACQUIA_API_SECRET=xxxxx
   > ```
5. In the project `.ddev/config.yaml` add the `ACQUIA_ENVIRONMENT_ID` environment variable:

   ```
   web_environment:
       - ACQUIA_ENVIRONMENT_ID=yoursite.dev
   ```

   You can also do this with:

   ```
   ddev config --web-environment-add="ACQUIA_ENVIRONMENT_ID=yoursite.dev"
   ```
6. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
7. Use `ddev pull acquia` to pull the project database and files.
8. Optionally use `ddev push acquia` to push local files and database to Acquia. Be aware that [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) is a command that can potentially damage your production site, so we don’t recommend using it.

## Usage

- [`ddev pull acquia`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to the Acquia Cloud Platform to download the database and files; note that it will download the latest available backup on the requested environment, rather than use a fresh copy of the database. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull acquia --environment="ACQUIA_ENVIRONMENT_ID=yoursite.dev"
  ```

  You can combine multiple variables:

  ```
  ddev pull acquia --environment="ACQUIA_ENVIRONMENT_ID=yoursite.dev,ACQUIA_API_KEY=xxxxxxxx,ACQUIA_API_SECRET=xxxxx"
  ```
- If you need to change the `acquia.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.

# Hosting Provider Integration

DDEV offers hosting provider integration and sample integrations for [Pantheon](<https://pantheon.io>), [Upsun](<https://upsun.com/>), [Lagoon](<https://lagoon.sh/>) and [Acquia](<https://www.acquia.com>) hosting, along with other examples.

Hosting provider integration allows connecting with your upstream hosting. `ddev pull <provider>` downloads and `ddev push <provider>` uploads the **database** and the **user-generated files** to an upstream provider. It does *not* push (deploy) or pull your code. Your code should be under version control in for example Git.

DDEV provides ready-to-go integrations for Upsun, Acquia, and Lagoon in every project, see the .ddev/providers directory. These can be used as is, or they can be modified as you see fit (but remove the `#ddev-generated` line so DDEV doesn’t replace them with the defaults).

In addition, each project includes [example recipes](<https://github.com/ddev/ddev/tree/main/pkg/ddevapp/dotddev_assets/providers>) for Pantheon, Git, local files, and `rsync` in its `.ddev/providers` directory, which you can use and adapt however you’d like.

DDEV provides the `pull` command with whatever recipes you have configured. For example, `ddev pull platform` is available by default, and `ddev pull pantheon` is available if you have created `.ddev/providers/pantheon.yaml`.

DDEV also provides the `push` command to push database and files to upstream. This is very useful for pushing to non-production environments, but could be very dangerous to your upstream production environment and should only be used when appropriate. If you find the `push` section dangerous, you can disable it by removing it from your provider YAML file.

Each provider recipe is a YAML file that can have whatever name you want. The examples are mostly named after the hosting providers, but they could be named `upstream.yaml` or `live.yaml`, so you could `ddev pull upstream` or `ddev pull live`. If you wanted different upstream environments to pull from, you could name one “prod” and one “dev” and `ddev pull prod` and `ddev pull dev`.

[Recipes and Integrations](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/>) are provided for:

- [Acquia](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/acquia.yaml>)
- [Git](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/git.yaml.example>)
- [Lagoon](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/lagoon.yaml>)
- [Local files](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example>) (like Dropbox, for example)
- [Pantheon](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/pantheon.yaml>)
- [Upsun Fixed/Platform.sh](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/platform.yaml>)
- [rsync](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/rsync.yaml.example>)
- [Upsun Flex](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/upsun.yaml>)

We know you’ll find improvements to these examples and will have lots to contribute for other hosting providers, and we look forward to your contributions as pull requests here or as new add-ons.

Each provider recipe is a file named `<provider>.yaml` and consists of several mostly-optional stanzas:

- `environment_variables`: Environment variables will be created in the web container for each of these during pull or push operations. They’re used to provide context (project ID, environment name, etc.) for each of the other stanzas. This stanza is not used in more recent hosting integrations, since providing the environment variables in `config.yaml` or via `ddev pull xxx --environment=VARIABLE=value` is preferred.
- `db_pull_command`: A script that determines how DDEV should obtain a database. Its job is to create a gzipped database dump in `/var/www/html/.ddev/.downloads/db.sql.gz`. This is optional; if nothing has to be done to obtain the database dump, this step can be omitted.
- `db_import_command`: (optional) A script that imports the downloaded database. This is for advanced usages like multiple databases. The default behavior only imports a single database into the `db` database. The [localfile example](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example>) uses this technique.
- `files_pull_command`: A script that determines how DDEV can get user-generated files from upstream. Its job is to copy the files from upstream to `/var/www/html/.ddev/.downloads/files`. If nothing has to be done to obtain the files, this step can run `true`.
- `files_import_command`: (optional) A script that imports the downloaded files. There are a number of situations where it’s messy to push a directory of files around, and one can put it directly where it’s needed. The [localfile example](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/dotddev_assets/providers/localfile.yaml.example>) uses this technique.
- `db_push_command`: A script that determines how DDEV should push a database. Its job is to take a gzipped database dump from `/var/www/html/.ddev/.downloads/db.sql.gz` and load it on the hosting provider.
- `files_push_command`: A script that determines how DDEV push user-generated files to upstream. Its job is to copy the files from the project’s user-files directories (`$DDEV_FILES_DIRS`) to the correct places on the upstream provider.

The [environment variables provided to custom commands](<https://ddev.github.io/ddev/en/stable/users/extend/custom-commands/#environment-variables-provided>) are also available for use in these recipes.

There are [hooks](<https://ddev.github.io/ddev/en/stable/users/configuration/hooks/index.md>) available to execute commands before and after each pull or push: `pre-pull`, `post-pull`, `pre-push`, `post-push`. These could be for example a [`ddev snapshot`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#snapshot>) to backup the database before a pull or a specific task to clear/warm-up caches of your application.

## Example Integrations and Hints

- All of the [supplied integrations](<https://github.com/ddev/ddev/tree/main/pkg/ddevapp/dotddev_assets/providers>) are examples of what you can do.
- You can name a provider anything you want. For example, an Acquia integration doesn’t have to be named “acquia”, it can be named “upstream”. This is a great technique for [downloading a particular multisite](<https://stackoverflow.com/a/68553116/215713>).

## Provider Debugging

You can uncomment the `set -x` in each stanza to see more of what’s going on. It really helps. Watch it as you do a `ddev pull <whatever>`.

Although the various commands could be executed on the host or in other containers if configured that way, most commands are executed in the web container. So the best thing to do is to [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) and manually execute each command you want to use. When you have it right, use it in the YAML file.

# Lagoon Integration

DDEV provides integration with [Lagoon](<https://lagoon.sh/>), allowing users to quickly sync the files and database from a Lagoon environment to the local DDEV project.

## Lagoon Per-Project Configuration

1. Check out the Lagoon project and configure it by running [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). You’ll want to run [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and make sure the basic functionality is working.
2. Add `LAGOON_PROJECT` and `LAGOON_ENVIRONMENT` variables to your project using `'web_environment'` in its YAML configuration or a `.ddev/.env` file. For example:

   ```
   web_environment:
       - LAGOON_PROJECT=your-project
       - LAGOON_ENVIRONMENT=main
   ```

   You can also do this with:

   ```
   ddev config --web-environment-add="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main"
   ```
3. Syncing is done via [`lagoon-sync`](<https://github.com/uselagoon/lagoon-sync>) which must be configured in your `.lagoon.yml` or `.lagoon-sync.yml`, see the [DDEV example `.lagoon.yml`](<https://github.com/ddev/test-amazeeio-lagoon/blob/main/.lagoon.yml#L27-L37>).
4. Configure an [SSH key](<https://docs.lagoon.sh/using-lagoon-advanced/ssh/>) for your Lagoon user.
5. Run `ddev auth ssh` to make your SSH key available in the project’s web container.
6. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
7. Run `ddev pull lagoon`. After you agree to the prompt, the current upstream databases and files will be downloaded.
8. Optionally use `ddev push lagoon` to push local files and database to Lagoon. The [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) command must be done with great care if you’re pushing to a production environment, but is great for pushing to branch environments.

## Usage

- [`ddev pull lagoon`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to the Lagoon environment to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull lagoon --environment="LAGOON_ENVIRONMENT=main"
  ```

  You can combine multiple variables:

  ```
  ddev pull lagoon --environment="LAGOON_PROJECT=your-project,LAGOON_ENVIRONMENT=main"
  ```
- If you need to change the `lagoon.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.

# Pantheon Integration

DDEV provides configurable integration with the [Pantheon Website Management Platform](<https://pantheon.io/>), which allows Pantheon users to quickly download and provision a project from Pantheon in a local DDEV-managed environment.

DDEV’s Pantheon integration pulls an existing backup from an existing Pantheon site/environment into your local system. That means you must already have a Pantheon site with a backup in order to use it.

## Pantheon Quickstart

If you have DDEV installed, and have an active Pantheon account with an active site, you can follow this guide to spin up a Pantheon project locally.

> [!TIP]
>
> **`ddev pull pantheon` fails due to Terminus version mismatch**
>
> See [How to Downgrade Terminus in DDEV’s Web Container and Customize Other Bundled Tools](<https://ddev.com/blog/ddev-bundled-tools-using-custom-versions/>).

1. Get your Pantheon machine token:

   1. Log in to your Pantheon Dashboard and [Generate a Machine Token](<https://pantheon.io/docs/machine-tokens/>) for DDEV to use.
   2. Add the API token to the `web_environment` section in your global DDEV configuration at `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)).

      ```
      web_environment:
          - TERMINUS_MACHINE_TOKEN=abcdeyourtoken
      ```

   > **What if I have more than one API token?**
   >
   > To use multiple API tokens for different projects, add them to your per-project configuration using the [`.ddev/config.local.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) file instead. This file is gitignored by default.
   >
   > ```
   > web_environment:
   >     - TERMINUS_MACHINE_TOKEN=abcdeyourtoken
   > ```
2. Choose a Pantheon site and environment you want to use with DDEV. You can usually use the site name, but in some environments you may need the site ID, which is the long third component of your site dashboard URL. So if the site dashboard is at `https://dashboard.pantheon.io/sites/009a2cda-2c22-4eee-8f9d-96f017321555#dev/`, the site ID is `009a2cda-2c22-4eee-8f9d-96f017321555`.
3. For `ddev push pantheon` make sure your public SSH key is configured in Pantheon under *Account* → *SSH Keys*.
4. Check out the project codebase from Pantheon. Enable the “Git Connection Mode” and use `git clone` to check out the code locally.
5. Configure the local checkout for DDEV using [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>).
6. Add `DDEV_PANTHEON_SITE` and `DDEV_PANTHEON_ENVIRONMENT` variables to your project `.ddev/config.yaml`:

   ```
   web_environment:
       - DDEV_PANTHEON_SITE=your-project
       - DDEV_PANTHEON_ENVIRONMENT=dev
   ```

   You can also do this with `ddev config --web-environment-add="DDEV_PANTHEON_SITE=your-project,DDEV_PANTHEON_ENVIRONMENT=dev"`.

   You can usually use the site name, but in some environments you may need the site ID, which is the long third component of your site dashboard URL. So if the site dashboard is at `https://dashboard.pantheon.io/sites/009a2cda-2c22-4eee-8f9d-96f017321555#dev/`, the site ID is `009a2cda-2c22-4eee-8f9d-96f017321555`.

   > **Legacy Variable Names**
   >
   > The old `PANTHEON_SITE` and `PANTHEON_ENVIRONMENT` variable names are still supported for backward compatibility but are deprecated. These names conflict with Pantheon’s own environment variables, which can cause applications to misidentify their runtime environment. Using `DDEV_PANTHEON_SITE` and `DDEV_PANTHEON_ENVIRONMENT` is strongly recommended.
7. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
8. Run `ddev pull pantheon`. DDEV will download the Pantheon database and files and bring them into the local DDEV environment. You should now be able to access the project locally.
9. Optionally use `ddev push pantheon` to push local files and database to Pantheon. The [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) command can potentially damage your production site, so we don’t recommend using it.

## Using Existing Backups vs Fresh Database Dumps

By default, `ddev pull pantheon` generates a fresh database dump, which ensures you get the most current data but can take several minutes. For faster pulls, you can use existing Pantheon backups instead.

To use existing backups, set `DDEV_USE_PANTHEON_BACKUP=true`:

```
# In .ddev/config.yaml
web_environment:
    - DDEV_USE_PANTHEON_BACKUP=true
```

Or use it for a one-time pull:

```
ddev pull pantheon --environment=DDEV_USE_PANTHEON_BACKUP=true
```

> [!TIP]
>
> **When to use existing backups**
>
> - During development when you need to refresh your local environment frequently
> - When the backup is recent enough for your needs
> - When you want faster pull times

> [!WARNING]
>
> **Backup freshness**
>
> Existing backups may not include the very latest data. Check your Pantheon dashboard to see when the last backup was created. Fresh dumps are generated on-demand and reflect the current state of your database.

## Usage

- [`ddev pull pantheon`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to Pantheon to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull pantheon --environment="DDEV_PANTHEON_ENVIRONMENT=dev"
  ```

  You can combine multiple variables:

  ```
  ddev pull pantheon --environment="DDEV_PANTHEON_SITE=your-project,DDEV_PANTHEON_ENVIRONMENT=dev,DDEV_USE_PANTHEON_BACKUP=true,TERMINUS_MACHINE_TOKEN=abcdeyourtoken"
  ```
- If you need to change the `pantheon.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.

# Upsun Fixed (Platform.sh) Integration

DDEV provides integration with the [Upsun “Fixed” Website Management Platform (formerly Platform.sh)](<https://fixed.docs.upsun.com/>), which allows Upsun Fixed users to quickly download and provision a project from Upsun in a local DDEV-managed environment.

> [!TIP]
>
> Consider using `ddev add-on get ddev/ddev-upsun` ([ddev-upsun](<https://github.com/ddev/ddev-upsun>)) for more complete Upsun Fixed integration.

DDEV’s Upsun Fixed integration pulls databases and files from an existing Upsun/Platform.sh-style site/environment into your local system so you can develop locally.

## Upsun Fixed (Platform.sh) Global Configuration

You need to obtain and configure an API token first. This is only needed once.

1. Login to the Upsun Dashboard and go to *Account* → *API Tokens*. Create an API token DDEV can use.
2. Add the API token to the `web_environment` section in your global DDEV configuration at `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)):

   ```
   web_environment:
       - PLATFORMSH_CLI_TOKEN=abcdeyourtoken
   ```

   You can also do this with:

   ```
   ddev config global --web-environment-add="PLATFORMSH_CLI_TOKEN=abcdeyourtoken"`
   ```

   > **What if I have more than one API token?**
   >
   > To use multiple API tokens for different projects, add them to your per-project configuration using the [`.ddev/config.local.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) file instead. This file is gitignored by default.
   >
   > ```
   > web_environment:
   >     - PLATFORMSH_CLI_TOKEN=abcdeyourtoken
   > ```

## Upsun Fixed/Platform.sh Per-Project Configuration

1. Check out the site and configure it with [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). You’ll want to use [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and make sure the basic functionality is working.
2. You can optionally add `PLATFORM_PROJECT` and `PLATFORM_ENVIRONMENT` variables to your project, or rely on automatic derivation when possible.

   - Automatic derivation (no action required):

     - If your repository contains `.platform/local/project.yaml` with an `id:` key, DDEV will derive `PLATFORM_PROJECT` from that file.
     - If your local Git branch name corresponds to the Platform.sh environment name, DDEV will derive `PLATFORM_ENVIRONMENT` from the current Git branch.
     - In typical setups where both `.platform/local/project.yaml` and a matching Git branch exist, you do not need to set `PLATFORM_PROJECT` or `PLATFORM_ENVIRONMENT` manually.
   - Manual configuration (only if automatic derivation is not suitable):

     - Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

       ```
       web_environment:
           - PLATFORM_PROJECT=abc12def34567
           - PLATFORM_ENVIRONMENT=main
       ```
     - Or with a command from your terminal:

       ```
       ddev config --web-environment-add="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main"
       ```

   For more information about how to set environment variables for containers and services see [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>).
3. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
4. Run `ddev pull platform`. After you agree to the prompt, the current upstream databases and files will be downloaded.
5. Optionally use `ddev push platform` to push local files and database to Upsun Fixed. The [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) command can potentially damage your production site, so we don’t recommend using it.

### Managing Multiple Apps

If your environment contains more than one app, add `PLATFORM_APP` variable to your project:

- Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

  ```
  web_environment:
      - ...
      - PLATFORM_APP=app
  ```
- Or with a command from your terminal:

  ```
  ddev config --web-environment-add="PLATFORM_APP=app"
  ```

### Managing Multiple Databases

If your project has only one database, it will automatically be pulled into and pushed from DDEV’s `db` database.

If your project has multiple databases, they’ll all be pulled into DDEV with their respective remote names. You can optionally designate a *primary* to use DDEV’s default `db` database, which may be useful in some cases—particularly if you’ve been using the default solo-database behavior and happened to add another one to your project.

You can designate the primary database using the `PLATFORM_PRIMARY_RELATIONSHIP` environment variable:

```
ddev config --web-environment-add="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

You can also do the same thing by running `ddev pull platform` and using the `--environment` flag:

```
ddev pull platform --environment="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

## Usage

- [`ddev pull platform`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to Upsun Fixed to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull platform --environment="PLATFORM_ENVIRONMENT=main"
  ```

  You can combine multiple variables:

  ```
  ddev pull platform --environment="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main,PLATFORM_APP=app,PLATFORM_PRIMARY_RELATIONSHIP=main,PLATFORMSH_CLI_TOKEN=abcdeyourtoken"
  ```
- If you need to change the `platform.yaml` recipe, you can change it or copy it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.

# Upsun Integration

DDEV provides integration with the [Upsun by Platform](<https://upsun.com/>) hosting system, allowing Upsun users to easily download database and files from Upsun to a local DDEV-managed environment.

> [!TIP]
>
> Consider using `ddev add-on get ddev/ddev-upsun` ([ddev-upsun](<https://github.com/ddev/ddev-upsun>)) for more complete Upsun integration.

DDEV’s Upsun integration pulls databases and files from an existing Upsun site/environment into your local system so you can develop locally.

## Upsun Global Configuration

You need to obtain and configure an API token first. This only needs to be done once.

1. Login to the Upsun Dashboard and go to *My Profile* → *API Tokens*. Create an API token DDEV can use.
2. Add the API token to the `web_environment` section in your global DDEV configuration at `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)):

   ```
   web_environment:
       - UPSUN_CLI_TOKEN=abcdeyourtoken
   ```

   You can also do this with:

   ```
   ddev config global --web-environment-add="UPSUN_CLI_TOKEN=abcdeyourtoken"
   ```

   > **What if I have more than one API token?**
   >
   > To use multiple API tokens for different projects, add them to your per-project configuration using the [`.ddev/config.local.yaml`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#environmental-overrides>) file instead. This file is gitignored by default.
   >
   > ```
   > web_environment:
   >     - UPSUN_CLI_TOKEN=abcdeyourtoken
   > ```

## Upsun Per-Project Configuration

1. Check out the Upsun site and configure it with [`ddev config`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#config>). You’ll want to use [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) and make sure the basic functionality is working.
2. Add `PLATFORM_PROJECT` and `PLATFORM_ENVIRONMENT` variables to your project, or rely on automatic derivation when possible.

   - Automatic derivation (no action required):

     - If your repository contains `.upsun/local/project.yaml` with an `id:` key, DDEV will derive `PLATFORM_PROJECT` from that file.
     - If your local Git branch name corresponds to the Upsun environment name, DDEV will derive `PLATFORM_ENVIRONMENT` from the current Git branch.
     - In typical setups where both `.upsun/local/project.yaml` and a matching Git branch exist, you do not need to set `PLATFORM_PROJECT` or `PLATFORM_ENVIRONMENT` manually.
   - Manual configuration (only if automatic derivation is not suitable):

     - Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

       ```
       web_environment:
           - PLATFORM_PROJECT=abc12def34567
           - PLATFORM_ENVIRONMENT=main
       ```
     - Or with a command from your terminal:

       ```
       ddev config --web-environment-add="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main"
       ```

   For more information about how to set environment variables for containers and services see [Environment Variables](<https://ddev.github.io/ddev/en/stable/users/configuration/environment-variables/index.md>).
3. Run [`ddev restart`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#restart>).
4. Run `ddev pull upsun`. After you agree to the prompt, the current upstream databases and files will be downloaded.
5. Optionally use `ddev push upsun` to push local files and database to Upsun. The [`ddev push`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#push>) command can potentially damage your production site, so we don’t recommend using it.

### Managing Multiple Apps

If your environment contains more than one app, add `PLATFORM_APP` variable to your project:

- Either in `.ddev/config.yaml` or a `.ddev/config.*.yaml` file:

  ```
  web_environment:
      - ...
      - PLATFORM_APP=app
  ```
- Or with a command from your terminal:

  ```
  ddev config --web-environment-add="PLATFORM_APP=app"
  ```

### Managing Multiple Databases

If your project has only one database, it will automatically be pulled into and pushed from DDEV’s `db` database.

If your project has multiple databases, they’ll all be pulled into DDEV with their respective remote names. You can optionally designate a *primary* to use DDEV’s default `db` database, which may be useful in some cases—particularly if you’ve been using the default solo-database behavior and happened to add another one to your project.

You can designate the primary database using the `PLATFORM_PRIMARY_RELATIONSHIP` environment variable:

```
ddev config --web-environment-add="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

You can also do the same thing by running `ddev pull upsun` and using the `--environment` flag:

```
ddev pull upsun --environment="PLATFORM_PRIMARY_RELATIONSHIP=main"
```

## Usage

- [`ddev pull upsun`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#pull>) will connect to Upsun to download database and files. To skip downloading and importing either file or database assets, use the `--skip-files` and `--skip-db` flags.
- To pull from a specific environment without permanently changing your project config, pass environment variables using `--environment`:

  ```
  ddev pull upsun --environment="PLATFORM_ENVIRONMENT=main"
  ```

  You can combine multiple variables:

  ```
  ddev pull upsun --environment="PLATFORM_PROJECT=abc12def34567,PLATFORM_ENVIRONMENT=main,PLATFORM_APP=app,PLATFORM_PRIMARY_RELATIONSHIP=main,UPSUN_CLI_TOKEN=abcdeyourtoken"
  ```
- If you need to change the `upsun.yaml` recipe, you can change it to suit your needs, but remember to remove the `#ddev-generated` line from the top of the file.

# Development

# Brand Guide

## Logos

| Logo | Preview |
| --- | --- |
| Figurative Mark | ![Figurative Mark](<https://ddev.github.io/ddev/en/stable/developers/logos/SVG/Logo.svg>) |
| Word/Figurative Mark<br>for light backgrounds | ![Word/Figurative Mark (Light)](<https://ddev.github.io/ddev/en/stable/developers/logos/SVG/Logo_w_text.svg>) |
| Word/Figurative Mark<br>for dark backgrounds | ![Word/Figurative Mark (Dark)](<https://ddev.github.io/ddev/en/stable/developers/logos/SVG/Logo_w_text_dark.svg>) |
| Word/Figurative Mark<br>auto (system preference) | ![Word/Figurative Mark (Auto)](<https://ddev.github.io/ddev/en/stable/developers/logos/SVG/Logo_w_text_auto.svg>) |

You can find a set of DDEV logos on [GitHub](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos>).

If possible, use the [SVG version](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos/SVG>) of the logo, as a vector graphic is independent of the resolution and gives the best results regardless of the pixel density of the display.

If the SVG format is not supported, you can use the exported PNG versions of the logo. Use [@2x](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos/2x>), [@3x](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos/3x>), and [@4x](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos/4x>) for high pixel density displays. Many applications support [@2x](<https://github.com/ddev/ddev/tree/main/docs/content/developers/logos/2x>) annotations in the image path and automatically choose the correct image for the display in use.

PNG variants are generated using this script executed from the `ddev/ddev` repository root:

```
# brew install --cask inkscape
# brew install oxipng
svg_dir="docs/content/developers/logos/SVG"
output_dirs=("1x" "2x" "3x" "4x")
dpis=(96 192 288 384)
for file in "$svg_dir"/*.svg; do
  base_name=$(basename "${file%.svg}")
  for i in "${!dpis[@]}"; do
    dpi="${dpis[$i]}"
    output_dir="${svg_dir}/../${output_dirs[$i]}"
    mkdir -p "$output_dir"
    if [[ "${dpi}" == "96" ]]; then
      # No @1x for 1x resolution
      output_filename="$output_dir/${base_name}.png"
    else
      output_filename="$output_dir/${base_name}@${output_dirs[$i]}.png"
    fi
    # Export PNG at the specified DPI
    inkscape "$file" --export-dpi "$dpi" --export-filename "$output_filename"
    # Optimize the PNG file (lossless)
    oxipng -o max --strip safe --alpha "$output_filename"
  done
done
```

## Color Plate

| DDEV Blue | DDEV Black | DDEV White |
| --- | --- | --- |
| `#02a8e2` | `#1e2127` | `#e1ded8` |

## Use of the Word Mark DDEV

The product DDEV is always referenced in capital letters.

When referring to the binary `ddev`, lowercase letters are preferred.

# Building, Testing, and Contributing

## Testing Latest Commits on HEAD

There are several ways to use DDEV’s latest-committed HEAD version:

- **[`ddev utility download-ddev`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-download-ddev>)**: Run `ddev utility download-ddev --head` to download the latest `main` build into `~/tmp/ddev-download-ddev/main`. It prints how to use the new binary in your current shell.
- **Download** the latest `main` branch artifacts from [nightly.link](<https://nightly.link/ddev/ddev/workflows/main-build/main>). Each of these is built by the CI system, signed, and notarized. Get the one you need and place it in your `$PATH`.
- **Homebrew install HEAD**: On macOS and Linux, run `brew unlink ddev && brew install ddev/ddev/ddev --HEAD --fetch-HEAD` to get the latest DDEV commit, even if it’s unreleased.
- **Install via script**: You can download and run the [install\_ddev\_head.sh](<https://raw.githubusercontent.com/ddev/ddev/main/scripts/install_ddev_head.sh>) script, or run it automatically:

  ```
  # Download and run the install script
  curl -fsSL https://raw.githubusercontent.com/ddev/ddev/main/scripts/install_ddev_head.sh | bash
  ```
- **Build manually**: If you have normal build tools like `make` and `go` installed, you can check out the code and run `make`.

## Testing a PR

Each [PR build](<https://github.com/ddev/ddev/actions/workflows/pr-build.yml>) creates GitHub artifacts you can use for testing. The easiest way is [`ddev utility download-ddev`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-download-ddev>), described first below; you can also download the artifact you need from the PR page manually and install it yourself.

> [!TIP]
>
> **You can also [downgrade to an older version of DDEV](<https://ddev.github.io/ddev/en/stable/users/usage/faq/#how-can-i-install-a-specific-version-of-ddev>) (perform a rollback).**

### Downloading a build with `ddev utility download-ddev`

[`ddev utility download-ddev`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#utility-download-ddev>) downloads the `ddev` and `ddev-hostname` binaries for a build and prints how to use them in your current shell:

```
# Download this PR's build for your current OS and architecture into ~/tmp/ddev-download-ddev/pr-<PR_NUMBER>
ddev utility download-ddev --pr <PR_NUMBER>
# See the help for more options:
ddev utility download-ddev --help
```

It can also fetch builds by branch, commit, release tag, or `main` HEAD, and cross-download other platforms.

### Downloading a build manually

Normally, you can put any executable in your path, and it takes precedence, so you don’t need to remove or disable an already installed DDEV instance, which we will use here. This example uses `~/bin`. Since not every OS has `$HOME/bin` in `$PATH`, you can create the folder and add it to your path by updating `~/.bashrc`, `~/.zshrc`, or another relevant shell configuration file with these commands:

```
mkdir ~/bin
echo 'export PATH="$HOME/bin:$PATH"' >>~/.bashrc
source ~/.bashrc
# Verify that `$HOME/bin` is the first entry in your `$PATH`
echo $PATH
```

Download a ZIP file for your OS and architecture by clicking the link (the result is something like `ddev-macos-arm64.zip`) or using `wget`, `curl`, `dl` and unzip it, make it executable, and move it to the `~/bin` folder:

```
# Example for macOS Apple Silicon:
unzip ddev-macos-arm64.zip
chmod +x ddev && mv ddev ~/bin/ddev
rm -f ddev-macos-arm64.zip
```

```
# Example for macOS Intel:
unzip ddev-macos-amd64.zip
chmod +x ddev && mv ddev ~/bin/ddev
rm -f ddev-macos-amd64.zip
```

```
# Example for Linux and WSL2:
unzip ddev-linux-amd64.zip
chmod +x ddev && mv ddev ~/bin/ddev
rm -f ddev-linux-amd64.zip
```

```
# Example for Linux and WSL2 ARM64:
unzip ddev-linux-arm64.zip
chmod +x ddev && mv ddev ~/bin/ddev
rm -f ddev-linux-arm64.zip
```

![Github Action PR Comment ZIP files](<https://ddev.github.io/ddev/en/stable/images/github-action-pr-comment.png>)

Tip: If you need a zip-file to try out the “Testing a PR” process, see the [nightly builds](<https://nightly.link/ddev/ddev/workflows/main-build/main>).

> [!WARNING]
>
> **macOS and Unsigned Binaries (click me)**
>
> macOS doesn’t like these downloaded binaries, so you’ll need to bypass the automatic quarantine to use them:
>
> ```
> xattr -r -d com.apple.quarantine ~/bin/ddev
> ```
>
> (The binaries on the `main` branch and the final release binaries *are* signed.)

Verify the replacement worked by running `ddev -v`. The output should be something like `ddev version v1.23.5-98-g3c93ae87e`, instead of the regular `ddev version v1.23.5`. Valuable commands for debugging are `which -a ddev` and `echo $PATH`.

When DDEV detects a version change, it recommends [powering down](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#poweroff>) all running containers. Then, it will download the new images, if required.

After you’re done testing, you can delete your downloaded executable, restart your terminal, and again use the standard DDEV:

```
rm ~/bin/ddev
```

## Making Changes to DDEV Images

If you need to make a change to one of the DDEV images, just edit the files under that image’s directory (for example `containers/ddev-webserver/Dockerfile`), then build from the repository root:

```
make
```

`make` detects that the image’s own content changed, builds it locally for your host architecture, and automatically rewrites the matching tag (like `WebTag`) in `pkg/versionconstants/versionconstants.go` — there’s no tag to invent and no file to hand-edit. If nothing under `containers/` changed, `make` does nothing extra: no Docker calls, no network access.

This also applies after a rebase or merge — if a base image or shared file changed upstream, `make` detects the mismatch and rebuilds the affected image the same way, even if you didn’t edit anything yourself.

External package repositories are not part of an image’s content hash. To rebuild `ddev-webserver` against updated external dependencies, bump `EXTERNAL_DEPENDENCIES_REFRESH` in its `Dockerfile`, then run `make`. This invalidates the base package-install layer and gives the rebuilt image a new tag.

`ddev version` should show you that you are using the freshly built tag, and [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>) will use the local image without pulling.

Run `make print-image-tags` at any time to see the tag each image would currently use, whether or not it’s actually been built yet — this is the value to use with the GitHub Actions push workflows described below if you need the image pushed to the registry.

`containers/ddev-dbserver` is a special case: one tag (`BaseDBTag`) covers many db type/version combinations, so `make` only builds the default variant (currently `mariadb_11.8`) locally. To build a different db type/version after changing `containers/ddev-dbserver`, build it manually using the tag `make print-image-tags` reports:

```
cd containers/ddev-dbserver
make mysql_8.0_amd64 VERSION=<tag-from-print-image-tags>
```

## Docker Image Changes

Running `make` at the repository root (above) already builds a changed image locally and updates `pkg/versionconstants/versionconstants.go` for you. To make that same build available to CI or other developers, it also needs to be pushed to the registry:

- Get the exact tag `make` used, with `make print-image-tags` (or read it straight out of `pkg/versionconstants/versionconstants.go` after running `make`).
- Push an image with that tag by navigating to the image directory (like `containers/ddev-webserver`), and running `make push DOCKER_REPO=youruser/yourimage VERSION=<tag>`.
- Multi-arch images require you to have a Buildx builder, so `docker buildx use multi-arch-builder || docker buildx create --name multi-arch-builder --use`.
- You can’t push until you `docker login`.
- Push a container to hub.docker.com with that same tag. Push to `<yourorg>/ddev-webserver` repository with `make push DOCKER_ORG=<yourorg> VERSION=<tag>` **in the container directory**. You might have to use other techniques to push to another repository.

### Local Builds and Pushes

To use `buildx` successfully you have to have the [`buildx` Docker plugin](<https://docs.docker.com/buildx/working-with-buildx/>), which is in many environments by default.

To build multi-platform images you must `docker buildx use multi-arch-builder || docker buildx create --name multi-arch-builder --use` as a one-time initialization.

- Running `make` from the repository root already does a quick local build of any changed image for your host architecture (see [Making Changes to DDEV Images](<#making-changes-to-ddev-images>) above). To build a specific image or db type/version directly instead, you can still:

  - `cd containers/<image>` then `make VERSION=<version>`
  - for `ddev-dbserver`: `make mariadb_10.3 VERSION=<version>` etc.
- To push manually:

```
cd containers/ddev-webserver
make push VERSION=<tag>
```

If you’re pushing to a repository other than the one wired into the Makefile (like `ddev/ddev-webserver`):

```
cd containers/ddev-webserver
make push VERSION=<tag> DOCKER_REPO=your/dockerrepo
```

### Pushes Using GitHub Actions

Normally the [Image build](<https://github.com/ddev/ddev/actions/workflows/image-build-push.yml>) workflow (see [Automatic Image Build and Push](<#automatic-image-build-and-push>)) handles pushing a changed image automatically for any pull request, including forks. The workflows below are for manually pushing a specific tag — a re-push, or one of the `ddev-dbserver` variants other than the default `mariadb_11.8` that `make` auto-builds.

To manually push using GitHub Actions,

#### For Most Images

- Visit [Actions → Push tagged image](<https://github.com/ddev/ddev/actions/workflows/push-tagged-image.yml>)
- Click “Run workflow” in the blue band near the top.
- Choose the branch, usually `main` and then the image to be pushed, `ddev-webserver`, `ddev-dbserver`, etc.

#### For `ddev-dbserver`

- Visit [Actions → Push tagged db image](<https://github.com/ddev/ddev/actions/workflows/push-tagged-dbimage.yml>)
- Click “Run workflow” in the blue band near the top.
- Choose the branch, usually `main`. Include a tag for the pushed image and GitHub will do all the work.

## Instrumentation

The [instrumentation](<https://ddev.github.io/ddev/en/stable/users/usage/diagnostics/index.md>) implementation is generated using the [Ampli Codegen](<https://www.docs.developers.amplitude.com/data/sdks/go/ampli/>).

To synchronize the implementation with the latest changes at Amplitude, the CLI tool has to be installed locally:

```
npm install -g @amplitude/ampli
```

Make changes to the event definition using the GUI at [https://data.amplitude.com/ddev/DDEV](<https://data.amplitude.com/ddev/DDEV>):

- create a new branch
- create or change events and properties
- save changes to the new branch
- update the implementation with `ampli checkout <branch name>`
- make changes to the code

Once finished, save the changes to publish a new version of the definitions.

Afterwards the changes can be imported running the following command in the project root:

```
ampli pull
```

Once the changes are ready to be merged, merge the changes made in the new branch to the `main` branch in the Amplitude backend (the `Merge` button is on the `Activity` tab on the left) and switch back to the `main` branch:

```
ampli checkout main
```

Make sure the API keys are not included to the sources; they are linked during compilation using a GitHub secret.

### Environments

There are two environments defined, `DDEV - Production` and `DDEV - Development`. Master builds will deliver the data to production, PR builds to development.

When working on Amplitude, please always make sure the correct environment is selected or you won’t see any data. Selection is possible on most pages.

### User and event data

The first step is always to identify the device, this includes data like OS, architecture, DDEV version, Docker, etc., details are visible in the *User Properties*. The devices are called *Users* in the Amplitude backend. So every user represents an unique device on which DDEV is installed.

The second step is to collect data about the command which was called by the user and is delivered by a dedicated `Command` event.

The `Project` event finally collects data about the loaded project(s) which includes important configuration details like PHP version, database, etc.

### Debugging

Information about data debugging can be found at [https://www.docs.developers.amplitude.com/data/debugger/](<https://www.docs.developers.amplitude.com/data/debugger/>). *Ingestion debugger* or via *User lookup* are the most useful options for DDEV.

Don’t forget to select the matching environment while debugging.

### Examining data on Amplitude.com

First, local `ddev` binaries have to be built with `AmplitudeAPIKey` set. Visit `https://app.amplitude.com/data/ddev/DDEV/sources/production` and select either “Production” or “Development”, then click the “Go SDK” line to get the API key. Then set `export AmplitudeAPIKey=<key>` and build the binaries with `make`.

Then run `ddev` commands as usual, and the data will be sent to Amplitude.

- You can examine data on the local side with `export DDEV_VERBOSE=true` but it’s awkward. However, the actual data is always marked with `AMPLITUDE:` and the `EventType` will be `Command`, `Project`, or `$identify` (User data). For example, DDEV\_VERBOSE=true ddev start 2\>&amp;1 | grep AMPLITUDE\`
- To see the data show up on Amplitude, you’ll need to `ddev utility instrumentation flush`.
- To make it easier to find your data, use the “Development” key and set your `instrumentation_user` to a familiar value in `$HOME/.ddev/global_config.yaml`. For example, `instrumentation_user: rfay` would make it so you can find the user `rfay`.
- To inspect data, visit “User Lookup”, (`https://app.amplitude.com/analytics/ddev/activity`) and choose the correct source in the upper left (“DDEV Production” or “DDEV Development”). Then use “Search users” in the upper right to find the user you are studying. If you’ve used an `instrumentation_user` it will be searchable as “User”. (Advanced-\>where: “User” = “rfay”. for example). You’ll then have a page devoted to the events of that user.

## Building

- You’ll want both your fork/branch and the upstream as remotes in Git, so that tags can be determined. For example, the upstream Git remote can be `https://github.com/ddev/ddev` and your fork’s remote can be `git@github.com:<yourgithubuser>/ddev`. Without the upstream, Git may not know about tags that it needs for tests to work.
- To run tests, you’ll want `~/tmp` to be allowed in Docker. This is not normally an issue as the home directory is available by default in most Docker providers.

Build the project with `make` and your resulting executable will end up in `.gotmp/bin/linux_amd64/ddev` or `.gotmp/bin/linux_arm64/ddev` (for Linux) or `.gotmp/bin/windows_amd64/ddev.exe` or `.gotmp/bin/windows_arm64/ddev.exe` (for Windows) or `.gotmp/bin/darwin_amd64/ddev` or `.gotmp/bin/darwin_arm64/ddev` (for macOS).

You can add additional `go build` args with `make BUILDARGS=<something>`, for example, `make BUILDARGS=-race`.

Build/test/check static analysis with:

```
make # Builds on current os/architecture
make BUILDARGS=-race
make linux_amd64
make linux_arm64
make darwin_amd64
make darwin_arm64
make windows_amd64
make windows_arm64
make test
make clean
make staticrequired
```

## Testing

Normal test invocation is `make test`. Run a single test with an invocation like `go test -v -run TestDevAddSites ./pkg/...` or `make test TESTARGS="-run TestDevAddSites"`. The easiest way to run tests is from inside the excellent Go IDE [GoLand](<https://www.jetbrains.com/go/>). Click the arrowhead to the left of the test name. This is also easy to do in Visual Studio Code.

To test with race detection, `make test TESTARGS="-race"` for example.

To see which DDEV commands the tests are executing, set the environment variable `DDEV_DEBUG=true`.

Use `GOTEST_SHORT=true` to run one CMS in each test, or `GOTEST_SHORT=<integer>` to run exactly one project type from the list of project types in the [TestSites array](<https://github.com/ddev/ddev/blob/main/pkg/ddevapp/ddevapp_test.go#L43>). For example, `GOTEST_SHORT=5 make test TESTARGS="-run TestDdevFullSiteSetup"` will run only `TestDdevFullSiteSetup` against TYPO3.

To run a test (in the `cmd` package) against a individually-compiled DDEV binary, set the `DDEV_BINARY_FULLPATH` environment variable, for example `DDEV_BINARY_FULLPATH=$PWD/.gotmp/bin/linux_amd64/ddev make testcmd`.

To run all tests in a specific package, use `make testonepkg TESTPKG=./pkg/dockerutil`. Combine with `TESTARGS` to filter further, for example `make testonepkg TESTPKG=./pkg/dockerutil TESTARGS="-run TestDockerUtils"`.

To run all tests defined in a single `_test.go` file, use `make testonefile TESTFILE=./cmd/ddev/cmd/utility-tls-diagnose_test.go`. This automatically extracts the test function names from the file and builds the `-run` pattern.

When triggering a custom Buildkite or GitHub Actions run, the same targets are available via environment variables: set `MAKE_TARGET=testonepkg` with `TESTPKG=./pkg/dockerutil`, or `MAKE_TARGET=testonefile` with `TESTFILE=./cmd/ddev/cmd/utility-tls-diagnose_test.go`.

The easiest way to run tests is using GoLand (or VS Code) with their built-in test runners and debuggers. You can step through a specific test; you can stop at the point before the failure and experiment with the site that the test has set up.

## Automated Testing

Anybody can view the CircleCI automated tests, and they usually show up any problems that are not OS-specific. Click through on the testing section of the PR to see them.

The Buildkite automated tests require special access, which we typically grant to any PR contributor that asks for it.

## Docker Image Development

The Docker images that DDEV uses are included in the `containers/` directory:

- `containers/ddev-webserver` provides the web servers for per-project `web` containers.
- `containers/ddev-dbserver` provides the `db` container for per-project databases.
- `containers/ddev-ssh-agent` provides a single in-Docker-network SSH agent so projects can use your SSH keys.
- `containers/ddev-traefik-router` is the current Traefik-based router image.
- `containers/ddev-xhgui` provides a web interface to analyze performance profiles generated by xhprof.

When you change an image, running `make` from the repository root builds it locally and computes/updates its tag in `pkg/versionconstants/versionconstants.go` automatically — no manual tag-inventing or file-editing needed, and this works for any contributor, including from a fork. If you’d rather leave the build to CI, `make retag-images` writes the same tags without running Docker at all; the tags it writes then name images that exist nowhere until the pull request’s push completes, so `ddev start` won’t work until then. Once you push that commit as a pull request, the [Image build](<https://github.com/ddev/ddev/actions/workflows/image-build-push.yml>) workflow detects the changed image and builds and pushes it to the registry automatically — no maintainer needs to run anything by hand. See [Automatic Image Build and Push](<#automatic-image-build-and-push>) below for when that requires a maintainer’s approval and when it doesn’t.

### Automatic Image Build and Push

An image’s tag is the bare content hash of the files it’s built from — `ddev/ddev-webserver:36bceca65e`, with no branch prefix. The same content therefore resolves to the same tag no matter which branch, fork, or Docker Hub organization published it, which is what lets `make`, the CI detector, and every test runner agree without coordinating. `versionconstants.go` records the branch alongside it, both as a trailing comment and as a `WebTagBranch`-style variable that `ddev version` shows, and each push also publishes a readable `<branch>-<hash>` alias pointing at the same manifest.

Opening a pull request that touches `containers/` triggers the [Image build](<https://github.com/ddev/ddev/actions/workflows/image-build-push.yml>) workflow. A `detect` job always runs first: it recomputes each image’s content hash and checks whether that tag is already in the registry. If it is, there’s nothing to build — so a pull request that touches `containers/` without changing an image costs one registry lookup per image and no build.

The same resolution drives `containers/wait-for-images.sh`, which every test runner calls before pulling anything: it waits only for tags this commit will pull, and doesn’t wait at all for an image whose content changed, since `make` builds that one locally on the runner.

Changing `containers/ddev-dbserver` is the one case where `make` alone isn’t enough. Every database variant shares a single `BaseDBTag`, so a dbserver change moves the tag for all 20 of them at once, while `make` only builds the default `mariadb_11.8` locally — the other 19 can only come from the registry. CI builds and pushes the whole matrix (36 jobs, from `containers/ddev-dbserver/variants.txt`), so **run `make` and commit the `versionconstants.go` change**; `wait-for-images.sh` stops the test run with that instruction if you don’t.

What happens next depends on whether the PR is from a fork:

- **Fork PRs** (security boundary — the PR could contain an arbitrary Dockerfile/build script) **from someone without push access**: as soon as `detect` finds an image to build, an `approve` job asks a maintainer to sign off on the `image-push` environment, before anything is built. Once approved, a `build` job builds the image(s) per architecture with no registry credentials at all — nothing in that job can reach `docker.io`, so there’s nothing to gain by gating it after the fact instead of before. A separate, trusted `image-push.yml` workflow — which never checks out or runs the pull request’s code — then loads what `build` produced and pushes it, re-validating both the tag and every repository name first (`containers/validate-image-tag.sh`, `containers/validate-image-repo.sh`) so the earlier approval can only ever publish a hash-shaped tag under a known DDEV repository. A comment is posted on the PR once the push completes. If `detect` found nothing to build, no approval is requested at all.
- **Fork PRs from a maintainer’s own fork** (`author_association` is `OWNER`, `MEMBER`, or `COLLABORATOR`): the same fork-safe `build` / `image-push.yml` split runs, but the `approve` job is skipped — they already have push access, so there’s nothing to ask permission for.
- **Everything else** (a push to `main`, or a pull request from a branch in the same repository — no fork content is ever involved): `build-and-push` builds and pushes directly in one step, with no approval gate at all — the same trust level `main-build.yml` already runs at unguarded. A `create-manifests` job then assembles the multi-arch manifest and comments on the PR, if there is one.

So a maintainer only ever needs to click **Approve** once — as soon as a fork PR without push access changes a container image — and only that once; everything else is fully automatic.

### Cleaning Up Unused Image Tags

Every image change pushes new tags to Docker Hub, and most are only useful until the release that follows. `containers/image-tag-cleanup.sh` finds the tags nothing uses any more and, only when told to with `--execute`, deletes them. The [Image tag cleanup](<https://github.com/ddev/ddev/actions/workflows/image-tag-cleanup.yml>) workflow runs the same script.

#### What counts as unused

A tag is a candidate for deletion only when all of these hold:

- It has a shape that CI or a branch build produces: a bare hash, a `<branch>-<hash>` alias, a date-prefixed branch tag like `20250612_stasadev_rebuild_images`, or a leftover `-amd64`/`-arm64` tag. Release tags, `latest`, and anything unrecognized are never candidates.
- It isn’t named in a version file (`pkg/versionconstants/versionconstants.go`, or `pkg/version/version.go` for older releases) at any `v*` release tag, at the head of any open pull request, or on the main branch within the last 90 days (`--keep-main-branch-days`).
- It was pushed more than 90 days ago (`--older-than-days`) and hasn’t been pulled in the last 30 days (`--not-pulled-for-days`).
- No kept tag points at the same manifest.

A deleted tag that a pull request later needs is pushed again by that pull request’s next image build, so the worst case is one rebuild.

#### From the command line

Run these from a checkout of ddev/ddev with the release tags fetched (`git fetch upstream --tags`) and [`gh`](<https://cli.github.com/>) logged in. The default run deletes nothing and lists what it would:

```
containers/image-tag-cleanup.sh
```

To include tags that were pulled recently, or only recently pushed ones, change the two rules:

```
containers/image-tag-cleanup.sh --older-than-days 10 --not-pulled-for-days 0
```

To see why each tag was kept or listed, write the decisions to a file:

```
containers/image-tag-cleanup.sh --decisions ~/tmp/decisions.tsv
```

To delete, set the credentials and add `--execute`. It asks before deleting. `--limit` deletes only the first few candidates, which is the way to try it on a small batch first:

```
export DOCKERHUB_USERNAME=<user> DOCKERHUB_TOKEN=<token>
containers/image-tag-cleanup.sh --limit 5 --execute
```

Every flag can be written `--flag value` or `--flag=value`, and `--help` lists them all. `--max-delete` refuses lists longer than its value (default 1000), and `--docker-org` chooses the Docker Hub organization (default `ddev`). The three steps also run alone, each with its own `--help`: `image-tag-keep-set.sh` lists the tags to keep, `image-tag-cleanup-candidates.sh` lists the tags that can go, and `delete-image-tags.sh` deletes the tags it is given, after checking that each is still a candidate.

#### From GitHub

The workflow has two jobs. `report` runs every Monday, and on demand with no inputs. It needs no credentials and only lists candidates: the run summary shows the counts and the list, and the `image-tag-cleanup-report` artifact holds every tag’s decision in `decisions.tsv`.

`delete` runs only when started by hand from `main` with `tags` or `report_run_id`. The `image-tag-cleanup` environment must approve it, and it deletes only if `execute` is checked, so an unchecked run is a dry run:

1. Run the workflow with every input empty, and read the report.
2. Run it with `report_run_id` set to that run’s ID, `execute` unchecked, and approve. The log shows `would delete …` for each tag.
3. Run it again with the same `report_run_id` and `execute` checked, and approve. To delete only some tags, set `tags` to a list of `<org>/<repo>:<tag>` entries instead.

Before deleting, the job recomputes the candidates, and if any requested tag is no longer a candidate, it deletes nothing. The repository variables `CLEANUP_OLDER_THAN_DAYS` and `CLEANUP_NOT_PULLED_FOR_DAYS` change the two rules for the workflow, and `DOCKER_ORG` chooses the Docker Hub organization (ddev-test uses `ddevhq` on its own).

## Pull Requests

To contribute your fixes or improvements to DDEV, make a pull request on GitHub. If you’re undertaking a large change, create an issue first so it can be discussed before you invest a lot of time. When you’re ready, create a pull request, and a discussion will start around your proposed changes. Other contributors and users may chime in, but ultimately the decision is made by the maintainer(s). You may be asked to make some changes to your pull request. If so, add more commits to your branch and push them. They’ll automatically go into the existing pull request.

If your pull request is merged, great! If not, no sweat; it may not be what the project maintainer had in mind, or they were already working on it. This happens, so our recommendation is to take any feedback you’ve received and go forth and pull request again. Or create your own open source project.

### Preparing a pull request

- **[Fork](<https://docs.github.com/en/get-started/quickstart/contributing-to-projects>) the repository** and clone it locally. Connect your local to the original ‘upstream’ repository by adding it as a remote, and pull upstream changes often so you stay up to date and reduce the likelihood of conflicts when you submit your pull request. See more detailed instructions on [GitHub](<https://help.github.com/articles/syncing-a-fork>).
- **Create a [branch](<https://docs.github.com/en/get-started/quickstart/github-flow>)** for your edits. See below for DDEV’s conventions for branch names.
- **Be clear** about the problem and how someone can recreate it, or why your feature will help. Be equally clear about the steps you took to make your changes.
- **It’s best to test**. Run your changes against any existing tests and create new tests when needed. Whether tests exist or not, make sure your changes don’t break the existing project.

### Feature branch name

When preparing your pull request, please use a branch name like `YYYYMMDD_<your_username>_short_description` (like `20230901_rfay_short_description`) so it’s easy to identify you as the author.

### Pull Request Title Guidelines

We have very precise rules over how our PR titles (and thus main-branch commits) are to be formatted. This leads to **more readable messages** that are easy to follow when looking through the **project history**. But also, we use the main-branch Git commit messages to **generate the changelog** for the releases.

The pull request title must follow this convention which is based on the [Conventional Commits](<https://www.conventionalcommits.org/en/v1.0.0/>) specification:

```
<type>[optional scope][optional !]: <description>[, fixes #<issue>][, for #<issue>]
```

#### Examples

- `build: update Makefile logic`
- `chore(deps): bump mutagen to 0.18.1`
- `ci(pr): enforce commit message convention, fixes #5037`
- `docs: change code refs of Mac M1 to Apple Silicon`
- `feat: allow multiple upload dirs, fixes #4190, fixes #4796`
- `feat(pantheon): use environment variables`
- `fix: create upload_dir if it doesn't exist in ddev composer create-project, fixes #5031`
- `fix(auth): resolve password reset bug, for #1234`
- `refactor: add new Amplitude Property DDEV-Environment`
- `perf(image-pull): use docker-compose for parallel downloads`
- `style(readme): improve formatting`
- `test: optimize caching of downloaded assets`

#### Type

Must be one of the following:

- **build**: Changes that affect the build or external dependencies
- **chore**: Maintenance tasks, dependency updates, or other changes that don’t modify src or test files
- **ci**: Changes to our CI configuration files and scripts
- **docs**: Documentation only changes
- **feat**: A new feature
- **fix**: A bugfix
- **perf**: A code change that improves performance
- **refactor**: A code change that neither fixes a bug nor adds a feature
- **style**: Changes that do not affect the meaning of the code (whitespace, formatting, missing semi-colons, etc)
- **test**: Adding missing tests or correcting existing tests

Regarding SemVer, all types above except `feat` increase the patch version, `feat` increases the minor version.

#### Scope

An optional scope may be provided to add contextual information and is contained within parentheses, e.g., `feat(pantheon): add file uploads`. The scope should be a noun describing a section of the codebase surrounded by parentheses.

#### Breaking Changes

Breaking changes must have a `!` appended after type/scope.

Regarding SemVer, breaking changes increase the major version.

#### Subject / Description

The subject contains a succinct description of the change:

- use the imperative, present tense: “change” not “changed” nor “changes”
- don’t capitalize the first letter
- no dot (.) at the end

If an issue exists for the change, `, fixes #<issue number>` must be appended to the subject.

#### Revert

If the commit reverts a previous commit, it should begin with `revert:`, followed by the header of the reverted commit. In the body it should say: `This reverts commit <hash>.`, where the hash is the SHA of the commit being reverted.

## Coding Style

Unless explicitly stated, we follow all coding guidelines from the Go community. While some of these standards may seem arbitrary, they somehow seem to result in a solid, consistent codebase.

It is possible that the codebase does not currently comply with these guidelines. We are not looking for a massive PR that fixes this since that goes against the spirit of the guidelines. All new contributions should make a best effort to clean up and make the codebase better than they left it. Obviously, apply your best judgment. Remember, the goal here is to make the codebase easier for humans to navigate and understand. Always keep that in mind when nudging others to comply.

Use `make staticrequired` to ensure that your code can pass the required static analysis tests.

The rules:

1. All code should be formatted with `gofmt -s`.
2. All code should pass the default levels of [`golint`](<https://github.com/golang/lint>).
3. All code should follow the guidelines covered in [Effective Go](<http://golang.org/doc/effective_go.html>) and [Go Code Review Comments](<https://github.com/golang/go/wiki/CodeReviewComments>).
4. Comment the code. Tell us the why, the history and the context.
5. Document *all* declarations and methods, even private ones. Declare expectations, caveats and anything else that may be important. If a type gets exported, having the comments already there will ensure it’s ready.
6. Variable name length should be proportional to its context and no longer. `noCommaALongVariableNameLikeThisIsNotMoreClearWhenASimpleCommentWouldDo`. In practice, short methods will have short variable names and globals will have longer names.
7. No underscores in package names. If you need a compound name, step back, and re-examine why you need a compound name. If you still think you need a compound name, lose the underscore.
8. All tests should run with `go test` and outside tooling should not be required. No, we don’t need another unit testing framework. Assertion packages are acceptable if they provide *real* incremental value.
9. Even though we call these “rules” above, they are guidelines. Since you’ve read all the rules, you now know that.

If you are having trouble getting into the mood of idiomatic Go, we recommend reading through [Effective Go](<https://golang.org/doc/effective_go.html>). The [Go Blog](<https://blog.golang.org>) is also a great resource. Drinking the kool-aid is a lot easier than going thirsty.

## Contributor Live Training

We’re actively trying to increase the DDEV community of contributors and maintainers. To do that, we regularly do contributor training, and we’d love to have you come. The trainings are recorded for everybody’s benefit. The recordings and upcoming session dates can be found here: [DDEV Contributor Live Training](<https://ddev.com/blog/contributor-training/>).

# Buildkite Test Agent Setup

We are using [Buildkite](<https://buildkite.com/ddev>) for Windows and macOS testing. The build machines and `buildkite-agent` must be set up before use.

## Git Mirrors (all platforms)

Set `git-mirrors-path` in `buildkite-agent.cfg` on every agent. Buildkite keeps a local bare mirror of the repository there, so a wiped or first-time build directory does an incremental fetch from the mirror instead of a fresh clone against GitHub — this avoids the exposure to transient network failures that a full clone has. See [Buildkite’s Git mirrors docs](<https://buildkite.com/docs/agent/self-hosted/configure/git-mirrors>).

`buildkite-agent.cfg` doesn’t expand `$HOME`-style variables, only a leading `~`. Point `git-mirrors-path` at a sibling of that agent’s own `build-path`, matching whichever form (`~` or absolute) `build-path` already uses. To check or fix an existing agent, run the matching one-liner below (idempotent — safe to run again) and restart the agent afterward:

- macOS/Pi, `build-path="~/tmp/buildkite-agent/builds"`:

  ```
  CFG=/usr/local/etc/buildkite-agent/buildkite-agent.cfg; [ -f "$CFG" ] || CFG=/opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg
  grep -q '^git-mirrors-path=' "$CFG" || echo 'git-mirrors-path="~/tmp/buildkite-agent/git-mirrors"' | sudo tee -a "$CFG"
  brew services restart buildkite-agent@4
  ```
- Linux/WSL2 package default, `build-path="/var/lib/buildkite-agent/builds"`:

  ```
  grep -q '^git-mirrors-path=' /etc/buildkite-agent/buildkite-agent.cfg || echo 'git-mirrors-path="/var/lib/buildkite-agent/git-mirrors"' | sudo tee -a /etc/buildkite-agent/buildkite-agent.cfg
  sudo systemctl restart buildkite-agent
  ```
- Windows, `build-path=C:\Users\testbot\tmp\buildkite` (Git Bash):

  ```
  grep -q '^git-mirrors-path=' /c/buildkite-agent/buildkite-agent.cfg || echo 'git-mirrors-path="C:\Users\testbot\tmp\buildkite-git-mirrors"' >> /c/buildkite-agent/buildkite-agent.cfg
  nssm.exe restart buildkite-agent
  ```

Windows agents provisioned with the package default `build-path=C:\buildkite-agent\builds` instead use `git-mirrors-path="C:\buildkite-agent\git-mirrors"` — check `build-path` in the file first.

## Windows Test Agent Setup

1. Create the user “testbot” on the machine. Use the password for `ddevtestbot@gmail.com`, available in 1Password.
2. In admin PowerShell, `wsl --install`.
3. (WSL2/Docker Desktop and traditional Windows only): Install either [Docker Desktop for Windows](<https://docs.docker.com/desktop/release-notes/>) (from the release notes page, which is best maintained) or [Rancher Desktop](<https://rancherdesktop.io/>). With Rancher Desktop, turn off Kubernetes. (Rancher Desktop on Windows appears to be too unreliable to use at this point in its history.)
4. In admin PowerShell, `Set-ExecutionPolicy -Scope "CurrentUser" -ExecutionPolicy "Unrestricted"`.
5. In admin PowerShell, download and run [windows\_buildkite\_start.ps1](<https://ddev.github.io/ddev/en/stable/developers/scripts/windows_buildkite_start.ps1>) with `curl <url> -O windows_buildkite_start.ps1`.
6. Install items as needed with `winget` as the testbot user. Everything but `mkcert` is only required for a traditional Windows test machine, which also needs `nc.exe` (netcat) on the `PATH`; it has no `winget` package. Don’t use Chocolatey, which needs an administrator for upgrades that the unprivileged test jobs can’t do. Don’t install DDEV either: the test jobs build and use the DDEV under test.

   ```
   winget install -e --accept-package-agreements --accept-source-agreements Git.Git jqlang.jq Oracle.MySQL GoLang.Go ezwinports.make FiloSottile.mkcert GnuWin32.Zip OpenJS.NodeJS.LTS Ngrok.Ngrok
   ```
7. After restart, in **administrative** Git Bash window, `Rename-Computer <testbot-win10(home|pro)-<description>-1` and then `export BUILDKITE_AGENT_TOKEN=<token>`.
8. (Traditional Windows test runner only): Download and run [windows\_buildkite\_setup.sh](<https://ddev.github.io/ddev/en/stable/developers/scripts/windows_buildkite_setup.sh>).
9. If using Rancher Desktop, adjust the /c/buildkite-agent/buildkite-agent.cfg file to set `rancher-desktop=true` in the tags instead of `docker-desktop`. If using Docker Desktop, set `docker-desktop=true`. While editing that file, also add `git-mirrors-path` (see [Git Mirrors](<#git-mirrors-all-platforms>)): `echo 'git-mirrors-path="C:\buildkite-agent\git-mirrors"' >> /c/buildkite-agent/buildkite-agent.cfg`.
10. (Traditional Windows test runner only): Download and run [windows\_postinstall.sh](<https://ddev.github.io/ddev/en/stable/developers/scripts/windows_postinstall.sh>).
11. (Traditional Windows or Docker Desktop WSL2 Only) Launch Docker. It may require you to take further actions.

    - Check “Start Docker Desktop when you sign in” or the equivalent with Rancher Desktop.
    - Check “Add the \*.docker.internal names to the host’s /etc/hosts file”
    - Uncheck “SBOM Indexing”
    - Under “Resources” uncheck “Resource Saver” — **important**: Docker Desktop may re-enable this after a full restart. Verify it is unchecked after any Docker Desktop upgrade or manual restart. When Resource Saver is active, Docker Desktop pauses the Linux VM when no containers are running; `docker ps` and WSL2 integration fail until it is un-paused, causing spurious test failures.
12. After starting Docker Desktop or Rancher Desktop, set the correct Docker context in the Git Bash window with `docker context use desktop-linux` (Docker Desktop) or `docker context use default` (Rancher Desktop).
13. Log into Chrome with the user `ddevtestbot@gmail.com` and enable Chrome Remote Desktop.
14. (Traditional Windows test runner only): Enable `gd`, `fileinfo`, and `curl` extensions in `/c/tools/php*/php.ini`.
15. Set the “Sleep after time” setting in settings to never.
16. Install [winaero tweaker](<https://winaero.com/request.php?1796>) and “Enable user autologin checkbox”. Set up the machine to [automatically log in on boot](<https://www.cnet.com/how-to/automatically-log-in-to-your-windows-10-pc/>). Then run netplwiz, provide the password for the main user, uncheck “require a password to log in”.
17. (Traditional Windows test runner only): Set the `buildkite-agent` service to run as the testbot user and use delayed start: Choose “Automatic, delayed start” and on the “Log On” tab in the services widget it must be set up to log in as the testbot user, so it inherits environment variables and home directory (and has testbot Git config, etc).
18. (Traditional Windows test runner only): `git config --global --add safe.directory '*'`.
19. (Traditional Windows test runner only): Manually run `testbot_maintenance.sh`, `curl -sL -O https://raw.githubusercontent.com/ddev/ddev/main/.buildkite/testbot_maintenance.sh && bash testbot_maintenance.sh`.
20. (Traditional Windows test runner only): Run `.buildkite/sanetestbot.sh` to check your work.
21. (Traditional Windows test runner only): Reboot the machine and do a test run. (On Windows, the machine name only takes effect on reboot.)
22. (Traditional Windows test runner only): Verify that `go`, `git-bash`, and `%USERPROFILE%\go\bin` are in the path.
23. In “Advanced Windows Update Settings” enable “Receive updates for other Microsoft products” to make sure you get WSL2 kernel upgrades. Make sure to run Windows Update to get the latest kernel.
24. Turn off the settings that cause the “windows experience” prompts after new upgrades: ![disable\_windows\_experience](<https://ddev.github.io/ddev/en/stable/images/disable_windows_experience.png>)
25. In PowerShell: `wsl.exe --update`. Watch for the elevation to complete, it may require elevation.

## Both Docker Desktop/WSL2 and Docker-ce/WSL2

1. The Ubuntu distro should be set up with the user `buildkite-agent` and the password used for `ddevtestbot@gmail.com`.
2. Stop Docker Desktop if it is running.
3. Log into Chrome with the user `ddevtestbot@gmail.com` and enable Chrome Remote Desktop.
4. Windows Terminal should be installed. Set “Ubuntu” (or this distro) as the default and have it start on Windows startup. Enable “copy on select” in behaviors.
5. `nc.exe -L -p 9003` on Windows to trigger and allow Windows Defender.
6. For a docker-ce/WSL2 runner (`BUILDKITE_DOCKER_TYPE=wsl2` below), Mirrored Mode is normal: edit `~/.wslconfig` on Windows to add the WSL2 settings below. A Docker Desktop runner (`BUILDKITE_DOCKER_TYPE=dockerforwindows`) keeps the default NAT networking instead, so skip this step for it.

   ```
   [wsl2]
   networkingMode=Mirrored
   [experimental]
   hostAddressLoopback=true
   ```
7. **Before running the setup script**, configure mkcert CAROOT on Windows (PowerShell as the testbot user). This must happen first so that `mkcert -install` in WSL2 installs the Windows CA (not a separate Linux-local one) into the Linux trust store:

   ```
   winget install -e FiloSottile.mkcert   # if not already installed
   mkcert -install
   setx CAROOT (mkcert -CAROOT)
   setx WSLENV "CAROOT/up"
   wsl --terminate Ubuntu    # restart distro so WSLENV takes effect
   ```
8. In the Ubuntu distro:

   1. `export BUILDKITE_AGENT_TOKEN=<token>` with the token from 1Password `BUILDKITE_AGENT_TOKEN`.
   2. `export BUILDKITE_DOCKER_TYPE=dockerforwindows` or `export BUILDKITE_DOCKER_TYPE=wsl2` — this also picks the `os=` agent tag the setup script writes: `wsl2-mirrored` for `wsl2` (docker-ce), plain `wsl2` for `dockerforwindows`, matching step 6 above.
   3. Optionally `export NGROK_TOKEN=<token>` with the `NGROK_TOKEN` from 1Password ngrok.com `nopaid` account.
   4. Run the script [wsl2-test-runner-setup.sh](<https://ddev.github.io/ddev/en/stable/developers/scripts/wsl2-test-runner-setup.sh>) in the Ubuntu distro. This script reads `CAROOT` from the Windows registry via `powershell.exe`, exports it before calling `mkcert -install`, and then creates `/etc/buildkite-agent/hooks/environment` to repeat this for every buildkite-agent job (since systemd does not propagate `WSLENV`). It also sets `git-mirrors-path="/var/lib/buildkite-agent/git-mirrors"` in `/etc/buildkite-agent/buildkite-agent.cfg` (see [Git Mirrors](<#git-mirrors-all-platforms>)).
9. Restart the distro with `wsl.exe -t Ubuntu` and then restart it by opening the Ubuntu window.
10. If using Docker Desktop, start Docker Desktop.
11. In `~/workspace/ddev/.buildkite`, run `./testbot_maintenance.sh`.
12. In `~/workspace/ddev/.buildkite`, run `./sanetestbot.sh` to check your work.

## Windows Installer Test Distros

The Windows GUI installer tests run in their own dedicated Buildkite pipeline (`windows-installer`, driven by `.buildkite/windows-installer.yml` + `.buildkite/installer-test.sh`), separate from the traditional Windows suite. Each matrix case is a parallel job that installs DDEV into a dedicated WSL2 distro using a specific Docker provider.

These tests need a **Windows-native** (`os=windows`) `buildkite-agent` — the same kind of agent as the traditional Windows runner — because they drive `wsl.exe`, `reg.exe`, and the installer `.exe`. The matrix spreads its jobs across all available `os=windows` agents, so adding more such machines increases parallelism.

> [!WARNING]
>
> **One `os=windows` agent per machine**
>
> An installer run mutates global Windows state (registry `CAROOT`/`WSLENV` and the machine-wide `mkcert` CA root). Two installer jobs must never run on the same machine at the same time. A Buildkite agent runs one job at a time, so running exactly **one** `os=windows` agent per physical machine guarantees this; the jobs then only overlap across separate machines.

The test does **not** create distros — it resets and reuses them. Provision the six named instances **once per runner** (the normal install handles user creation; complete first-run with the `testbot` user, which is the default user the test harness expects):

```
wsl --install Ubuntu       --name ddev-test-ubuntu-ce
wsl --install Ubuntu       --name ddev-test-ubuntu-desktop
wsl --install Ubuntu-24.04 --name ddev-test-ubuntu2404-ce
wsl --install Ubuntu-24.04 --name ddev-test-ubuntu2404-desktop
wsl --install Debian       --name ddev-test-debian-ce
wsl --install Debian       --name ddev-test-debian-desktop
```

For the `*-desktop` instances only, enable Docker Desktop’s WSL integration for that instance (Docker Desktop → Settings → Resources → WSL integration). Otherwise the `docker-desktop` cases skip gracefully. The base distro names above (`Ubuntu`, `Ubuntu-24.04`, `Debian`) must be available in the WSL catalog; verify with `wsl -l -o`.

Remove `unattended-upgrades` from all test instances. Ubuntu 24.04 in particular runs it on boot and holds the dpkg lock while the installer is trying to run `apt-get`, causing intermittent failures. It serves no purpose in these short-lived test distros:

```
foreach ($d in @("ddev-test-ubuntu-ce","ddev-test-ubuntu-desktop","ddev-test-ubuntu2404-ce","ddev-test-ubuntu2404-desktop","ddev-test-debian-ce","ddev-test-debian-desktop")) {
    wsl -d $d -u root apt-get remove -y unattended-upgrades 2>$null
}
```

Install [wsl-fix-interop](<https://github.com/rfay/wsl-fix-interop>) in all test instances and configure it to run on every distro boot. WSL interop (binfmt\_misc) loses its `WSLInterop` entry whenever `docker-ce` is removed — the package’s post-remove scripts clear binfmt\_misc entries. Without it, any Windows `.exe` called from within WSL fails with “Exec format error”, causing `mkcert.exe` failures and TLS test failures.

First install the script and sudoers entry:

```
foreach ($d in @("ddev-test-ubuntu-ce","ddev-test-ubuntu-desktop","ddev-test-ubuntu2404-ce","ddev-test-ubuntu2404-desktop","ddev-test-debian-ce","ddev-test-debian-desktop")) {
    wsl -d $d -u root bash -c "cd /tmp && curl -fsSL https://raw.githubusercontent.com/rfay/wsl-fix-interop/main/wsl-fix-interop -o wsl-fix-interop && curl -fsSL https://raw.githubusercontent.com/rfay/wsl-fix-interop/main/install.sh -o install.sh && bash install.sh testbot"
}
```

Then wire it into `/etc/wsl.conf` in each distro so it re-registers automatically on every distro boot (including after `docker-ce` removal clears binfmt\_misc):

```
foreach ($d in @("ddev-test-ubuntu-ce","ddev-test-ubuntu-desktop","ddev-test-ubuntu2404-ce","ddev-test-ubuntu2404-desktop","ddev-test-debian-ce","ddev-test-debian-desktop")) {
    wsl -d $d -u root bash -c "grep -q 'wsl-fix-interop' /etc/wsl.conf 2>/dev/null || printf '\n[boot]\ncommand = /usr/local/sbin/wsl-fix-interop\n' >> /etc/wsl.conf"
}
```

To run a single case manually (e.g. for debugging), select it by instance name, which is also the Go subtest name:

```
make testwininstaller TESTARGS="-run TestWindowsInstallerWSL2/ddev-test-debian-ce"
```

### WSL2 install-script tests

The `ddev-windows-installer` pipeline also tests the manual WSL2 install PowerShell scripts (`scripts/install_ddev_wsl2_docker_inside.ps1` and `scripts/install_ddev_wsl2_docker_desktop.ps1`) against current Ubuntu, as the `ps1-docker-inside` and `ps1-docker-desktop` matrix cases. These run only when a ps1 script (or its test/plumbing) changes, plus on `main` and manual builds.

They **reuse the two Ubuntu instances** above — no extra provisioning. The scripts now accept a `-Distro` parameter so the test passes the distro name directly without changing the system default:

- `ps1-docker-inside` → `ddev-test-ubuntu-ce`, which must have Docker Desktop WSL integration **disabled** (the script aborts if `/mnt/wsl/docker-desktop` exists). This is the same state the docker-ce installer case wants.
- `ps1-docker-desktop` → `ddev-test-ubuntu-desktop`, which must have Docker Desktop running with WSL integration **enabled**.
- `mkcert.exe` must be on the Windows PATH (already installed with `winget` above).

Run one manually with:

```
make testwsl2scripts TESTARGS="-run TestWSL2InstallScripts/docker-inside"
```

## Icinga2 monitoring setup for WSL2 instances

1. Icinga Director web UI, configure the host on `monitor.ddev.com`, normally making a copy of an existing identical item.
2. Deploy the new host using Icinga Director.
3. `sudo icinga2 node wizard` to configure the agent, see [docs](<https://icinga.com/docs/icinga-2/latest/doc/06-distributed-monitoring/#agentsatellite-setup-on-linux>).

   ```
   buildkite-agent@tb-wsldd-16:~$ sudo icinga2 node wizard
   Welcome to the Icinga 2 Setup Wizard!

   We will guide you through all required configuration details.

   Please specify if this is an agent/satellite setup ('n' installs a master setup) [Y/n]:

   Starting the Agent/Satellite setup routine...

   Please specify the common name (CN) [tb-wsldd-16.localdomain]: tb-wsldd-16

   Please specify the parent endpoint(s) (master or satellite) where this node should connect to:
   Master/Satellite Common Name (CN from your master/satellite node): monitor.ddev.com

   Do you want to establish a connection to the parent node from this node? [Y/n]: y
   Please specify the master/satellite connection information:
   Master/Satellite endpoint host (IP address or FQDN): monitor.ddev.com
   Master/Satellite endpoint port [5665]:

   Add more master/satellite endpoints? [y/N]:
   Parent certificate information:

   Version:             3
   Subject:             CN = monitor.ddev.com
   Issuer:              CN = Icinga CA
   Valid From:          Feb 22 22:34:09 2026 GMT
   Valid Until:         Mar 26 22:34:09 2027 GMT
   Serial:              02:0e:20:7e:a1:a9:f0:b4:8d:07:63:49:46:fb:d7:90:29:fd:c4:bc

   Signature Algorithm: sha256WithRSAEncryption
   Subject Alt Names:   monitor.ddev.com
   Fingerprint:         4A 99 90 F6 F4 F7 F9 20 1B DD 9D 51 EE 86 50 C7 BB 38 09 9B B0 40 4A E0 52 C9 52 2D A1 B8 72 D5

   Is this information correct? [y/N]: y

   Please specify the request ticket generated on your Icinga 2 master (optional).
   (Hint: # icinga2 pki ticket --cn 'tb-wsldd-16'): c5b9fa649792abcde3941862a664be0fe8d126
   Please specify the API bind host/port (optional):
   Bind Host []:
   Bind Port []:

   Accept config from parent node? [y/N]: y
   Accept commands from parent node? [y/N]: y

   Reconfiguring Icinga...

   Local zone name [tb-wsldd-16]:
   Parent zone name [master]:

   Default global zones: global-templates director-global
   Do you want to specify additional global zones? [y/N]:

   Do you want to disable the inclusion of the conf.d directory [Y/n]:
   Disabling the inclusion of the conf.d directory...

   Done.

   Now restart your Icinga 2 daemon to finish the installation!
   buildkite-agent@tb-wsldd-16:~$ sudo systemctl restart icinga2
   ```
4. Restart `sudo systemctl restart icinga2`
5. On `monitor.ddev.com` edit `/usr/local/bin/check_buildkite_agents.sh` to include the hostname of the new instance.

## macOS Docker Desktop Test Agent Setup (Apple Silicon)

1. Create the user “testbot” on the machine. Use the password for `ddevtestbot@gmail.com`, available in 1Password.
2. Change the name of the machine to something in keeping with current style, perhaps `testbot-macos-arm64-8`. This is done in **Settings** → **General** → **About** → **Name** and in **Sharing** → **Computer Name** and in **Sharing** → **Local Hostname**.
3. Download and install Chrome and log the browser into the account used for test runners. It will pick up the Chrome Remote Desktop setup as a result. Configure Chrome Remote Desktop to serve. When this is done, the machine will be available for remote access and most other tasks can be done using Chrome Remote Desktop.
4. The machine should be on the correct network and have a static IP handed out by DHCP. IP addresses are listed in /etc/hosts on `pi.ddev.site`, so this one should be added.
5. Power should be set up as in ![macos power settings](<https://ddev.github.io/ddev/en/stable/images/macos_power_settings.png>).
6. Auto login should be set up as in ![macos users and groups](<https://ddev.github.io/ddev/en/stable/images/macos_users_and_groups.png>), see [automatically log in on boot](<https://support.apple.com/en-us/HT201476>).
7. Remote login should be enabled as in ![macos remote login](<https://ddev.github.io/ddev/en/stable/images/macos_remote_login.png>).
8. Automatic updates should be set to mostly security only as in ![macos automatic\_updatees](<https://ddev.github.io/ddev/en/stable/images/macos_automatic_updates.png>).
9. Set the time zone to US MT (nearest city: Denver, Colorado).
10. `sudo mkdir -p /usr/local/bin && sudo chown -R testbot /usr/local/bin`
11. Install [Homebrew](<https://brew.sh/>) `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
12. After installing Homebrew follow the instructions it gives you at the end to add brew to your PATH.
13. Install everything you’ll need with `brew install buildkite/buildkite/buildkite-agent@4 bats-core composer git golang jq mysql-client@8.0 mkcert netcat p7zip  && brew install --cask docker iterm2 ngrok && brew link --force mysql-client`.
14. Run `ngrok authtoken <token>` with token for free account from 1Password.
15. Run `mkcert -install`.
16. If Docker Desktop will be deployed, run Docker manually and go through its configuration routine.
17. If OrbStack will be deployed, install it from [orbstack.dev](<https://orbstack.dev>).

    - Install with Docker only.
    - Click “Sign in” in the lower left to sign in with OrbStack credentials (normal test runner gmail address; it will receive an email with a login code).
    - Configure it to automatically start and download updates, see ![OrbStack configuration](<https://ddev.github.io/ddev/en/stable/images/orbstack_configuration.png>).
18. If Rancher Desktop will be deployed, install it.

    - Turn off kubernetes.
    - Set virtualization to VZ
    - Set mount type to VirtioFS
19. Run iTerm. You may need to allow full disk access permissions.
20. Run `mkdir ~/workspace && cd ~/workspace && git clone https://github.com/ddev/ddev`.
21. `git config --global --add safe.directory '*'`.
22. Edit `/usr/local/etc/buildkite-agent/buildkite-agent.cfg` or `/opt/homebrew/etc/buildkite-agent/buildkite-agent.cfg` to add

    - the agent `token` (from [agents tab](<https://buildkite.com/organizations/ddev/agents>), “Reveal Agent Token”).
    - the agent `name` (the name of the machine).
    - `tags`, like `"os=macos,architecture=arm64,osvariant=sonoma,dockertype=dockerformac,rancher-desktop=true,orbstack=true,docker-desktop=true"`
    - `build-path="~/tmp/buildkite-agent/builds"`
    - `git-mirrors-path="~/tmp/buildkite-agent/git-mirrors"` (see [Git Mirrors](<#git-mirrors-all-platforms>))
23. Run `brew services start buildkite-agent@4`.
24. Run `bash ~/workspace/ddev/.buildkite/testbot_maintenance.sh`.
25. Run `bash ~/workspace/ddev/.buildkite/sanetestbot.sh` to check your work.
26. The `testbot` user’s SSH account is used for monitoring, so `ssh-keygen` and then add the public key `id_testbot` from 1Password to `~/.ssh/authorized_keys` and `chmod 600 ~/.ssh/authorized_keys`.
27. Add the new machine to Icinga by copying an existing Icinga service to the new one. This is done in **Icinga Director** → **Services** → **Single Services** → **Select a Service** → **Clone** → **Deploy**. The new service has to have `by-ssh-address` set to the name of the test runner, and that address needs to be added to `pi.ddev.site`’s `/etc/hosts` file.
28. If `zsh` is the shell configured, add `/etc/zshenv` so that `/usr/local/bin/docker` will be picked up:

    ```
    PATH=$PATH:/usr/local/bin:/opt/homebrew/bin
    ```
29. In macOS Settings visit “full disk access” and grant access to `buildkite-agent`, `docker`, `iterm`, `orbstack`. This may prevent startup modal dialogs that prevent `buildkite-agent` or `docker` from continuing properly.

## Additional Colima macOS setup

1. `brew install colima`
2. `colima start vz --cpu 4 --memory 6 --disk 60 --vm-type=vz --mount-type=virtiofs --dns=1.1.1.1`
3. `colima stop vz`

Then the Buildkite agent must be configured with tags `colima_vz=true`.

## Additional Lima macOS setup

1. `limactl create --name=lima-vz --vm-type=vz --mount-type=virtiofs --mount-writable --mount="~/:w" --memory=6 --cpus=4 --disk=60 template:docker`
2. `limactl start lima-vz`
3. `docker context use lima-lima-vz`

Then the Buildkite agent must be configured with tags `lima=true`.

## Additional Podman Rootless macOS Setup

Podman rootless on macOS runs containers in a lightweight VM managed by `podman machine`.

1. Follow the instructions for [Podman on macOS](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/#macos-podman-rootless>) to install Podman and set up a rootless Podman machine with 6GB of memory. On a testbot whose machine was created with the 2GB default, resize it with `podman machine stop && podman machine set --memory 6144`.
2. Verify connectivity: `docker context use podman-rootless && docker ps` should return an empty container list.
3. Stop the machine when done with initial setup: `podman machine stop`

> [!NOTE]
>
> Rootless containers cannot bind to ports below 1024. `test.sh` handles this automatically by setting `DDEV_XDG_CONFIG_HOME` to an isolated config directory and configuring `router-http-port=8080` and `router-https-port=8443` via `ddev config global`.

Then configure the Buildkite agent with tag `podman-rootless=true` in addition to the standard macOS tags:

```
tags="os=macos,architecture=arm64,osvariant=sonoma,...,podman-rootless=true"
```

The `test.sh` script uses `podman machine start` and `docker context use podman-rootless` to activate the provider, then stops the machine in the cleanup trap on exit.

## Performance Benchmark Harness Prerequisites

The nightly performance benchmark harness (`perf/`, see `perf/README.md`) needs Node.js on every testbot, for the Puppeteer-driven Drupal install metric (`perf/metrics/03-drupal-install/`). On Linux, Puppeteer’s downloaded Chrome build also needs a handful of OS shared libraries a bare testbot image doesn’t ship with.

### WSL2 / Linux testbots (docker-ce or Docker Desktop’s WSL2 backend)

1. Install Node.js 22, matching the version `perf-linux.yml` uses:

   ```
   curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
   sudo apt-get install -y nodejs
   ```
2. Install Chrome’s runtime shared library dependencies. A bare Ubuntu 24.04 image is missing all of these; without them Puppeteer fails the first time it tries to launch Chrome, with an error like `error while loading shared    libraries: libatk-1.0.so.0` (or any of the others below, one at a time as each is fixed):

   ```
   sudo apt-get install -y \
     libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 libasound2t64 \
     libxkbcommon0 libgbm1 libx11-6 libxext6 libxcb1 libcairo2 \
     libpango-1.0-0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
     libatspi2.0-0
   ```

   The `t64` suffix on some of these is Ubuntu 24.04-specific: it renamed several packages during the 64-bit `time_t` ABI transition (`libatk1.0-0` → `libatk1.0-0t64`, etc.). Older or non-Ubuntu distros use the un-suffixed names. This list was derived by running `ldd` against the actual downloaded Chrome binary (`~/.cache/puppeteer/chrome/linux-*/chrome-linux64/chrome`); if a future Chrome version needs more, `ldd <path-to-chrome> | grep "not found"` shows what’s still missing.

### macOS testbots

Add `node` to the `brew install` list in step 13 of the macOS setup above.

### Traditional (native) Windows testbots

Install Node.js with `winget install -e OpenJS.NodeJS.LTS` (see step 6 of Windows Test Agent Setup above). Confirmed working, including headless Chrome launching from the NSSM-installed `buildkite-agent` service context.

## Running Targeted Builds on Specific Pipelines

To test a branch against only selected pipelines (e.g. WSL2 only) or to run a subset of tests without waiting for the full matrix:

1. Push your branch to upstream.
2. In the [Buildkite dashboard](<https://buildkite.com/ddev>), open the pipeline you want (e.g. “wsl2-mirrored”).
3. Click **New Build** and set the branch to your branch name.
4. Expand **Environment Variables** and add:

   ```
   TESTARGS=-run TestCheck -failfast
   ```

   Adjust the `-run` pattern to match the tests you want. Use a common prefix where possible. If you need `|` for alternation, wrap the regular expression in single quotes so the shell does not interpret the pipe as a pipeline operator:

   ```
   TESTARGS=-run 'TestCheckLiveConnectivity|TestCheckMkcertInstallation' -failfast
   ```

   `TESTARGS` defaults to `-failfast` when not set, so include `-failfast` explicitly if you want it.
5. Click **Create Build**.

Use `[skip ci]` in your commit message to prevent all pipelines from triggering automatically when you push, then manually trigger only the pipelines you need.

# GitHub Self-Hosted Agent Setup

We are using GitHub Self-Hosted Agents for Windows and macOS testing. The build machines and agents must be set up before use.

## Windows Agent Setup

1. Create the user “testbot” on the machine. Use the password for `ddevtestbot@gmail.com`, available in 1Password.
2. In admin PowerShell, `Set-ExecutionPolicy -Scope "CurrentUser" -ExecutionPolicy "RemoteSigned"`.
3. In admin PowerShell, download and run [windows\_buildkite\_start.ps1](<https://ddev.github.io/ddev/en/stable/developers/scripts/windows_buildkite_start.ps1>) with `curl <url> -O windows_buildkite_start.ps1`.
4. After restart, in administrative Git Bash window, `Rename-Computer <testbot-win10(home|pro)-<description>-1`.
5. Now download and run [windows\_github\_agent\_setup.sh](<https://ddev.github.io/ddev/en/stable/developers/scripts/windows_github_agent_setup.sh>).
6. Launch Docker. It may require you to take further actions.
7. Log into Chrome with the user `ddevtestbot` and enable Chrome Remote Desktop.
8. Enable `gd`, `fileinfo`, and `curl` extensions in `/c/tools/php*/php.ini`.
9. If a laptop, set the “lid closing” setting in settings to do nothing.
10. Set the “Sleep after time” setting in settings to never.
11. Install [`winaero tweaker`](<https://winaero.com/request.php?1796>) and “Enable user autologin checkbox”. Set up the machine to [automatically log in on boot](<https://www.cnet.com/how-to/automatically-log-in-to-your-windows-10-pc/>). Then run `netplwiz`, provide the password for the main user, uncheck the “require a password to log in”.
12. Add the path `C:\Program Files\git\bin` to the very front of the *system* environment variables. Otherwise Windows will try to use its own `bash.exe` or PowerShell.
13. Install the GitHub self-hosted runner software using the “Add New” instructions on [https://github.com/organizations/ddev/settings/actions](<https://github.com/organizations/ddev/settings/actions>). When it asks if you want it as a service: yes, you do.
14. Run `.buildkite/sanetestbot.sh` to check your work.
15. Reboot the machine and do a test run. (On Windows, the machine name only takes effect on reboot.)

# HTTP Proxy Test Environments

> [!TIP]
>
> **Related Testing**
>
> For testing SSL interception scenarios, see [Network Test Environments: Packet-Inspection VPN Simulation](<https://ddev.github.io/ddev/en/stable/developers/network-test-environments/index.md>).
>
> For testing network bandwidth constraints, see [Network Bandwidth Testing Environments](<https://ddev.github.io/ddev/en/stable/developers/network-bandwidth-testing/index.md>).

This guide demonstrates how to set up HTTP proxy environments for testing DDEV behavior with proxy servers. This is useful for testing corporate environments that route traffic through HTTP proxies, simulating real-world network configurations where all traffic must pass through proxy servers.

## Setup Overview

The setup involves:

- Running a SOCKS5 proxy (Tor or Cloudflare WARP)
- Converting SOCKS5 to HTTP using Privoxy
- Configuring Docker to use the HTTP proxy
- Testing Docker pulls and container network access

## Step-by-Step Instructions

### 1\. Install and Run SOCKS5 Proxy

> [!TIP]
>
> **Simple Testing Option**
>
> For basic HTTP proxy testing without SOCKS5 forwarding, you can skip this step and go directly to [Step 2](<#2-forward-socks5-to-http-with-privoxy>) to run Privoxy without any actual proxy behind it.

Choose one of the following options:

#### Option A: Using Tor

Install [Tor](<https://www.torproject.org/download/>):

```
# macOS
brew install tor

# Ubuntu/Debian
sudo apt-get install tor

# CentOS/RHEL/Fedora
sudo dnf install tor
```

Run Tor in the foreground:

```
sudo tor --SocksPort 127.0.0.1:9050
```

Verify Tor is running:

```
# Test SOCKS5 connection
curl --socks5 127.0.0.1:9050 https://httpbin.org/ip
```

#### Option B: Using Cloudflare WARP

Install [Cloudflare WARP](<https://developers.cloudflare.com/warp-client/get-started/>):

```
# macOS
brew install --cask cloudflare-warp

# Linux
# See https://pkg.cloudflareclient.com/
```

Configure for proxy mode:

**macOS/Windows (GUI):**

Configure proxy mode and port through the GUI interface.

**Linux (CLI):**

```
sudo systemctl enable --now warp-svc.service
warp-cli registration new
warp-cli mode proxy
warp-cli proxy port 9050
warp-cli connect

# Verify WARP is running
warp-cli status

# Test SOCKS5 connection
curl --socks5 127.0.0.1:9050 https://httpbin.org/ip

# When testing is done, disconnect
warp-cli disconnect
```

### 2\. Forward SOCKS5 to HTTP with Privoxy

Install [Privoxy](<https://www.privoxy.org/>):

```
# macOS
brew install privoxy

# Ubuntu/Debian
sudo apt-get install privoxy

# CentOS/RHEL/Fedora
sudo dnf install privoxy
```

Run Privoxy in the foreground:

> [!NOTE]
>
> **Direct HTTP Proxy Testing**
>
> For simple testing without SOCKS5 forwarding, you can run Privoxy without any actual proxy behind it:
>
> ```
> privoxy --no-daemon <(echo -e "listen-address 0.0.0.0:8118\ndebug 1\n")
> ```
>
> This creates an HTTP proxy at `0.0.0.0:8118` without forwarding to Tor/WARP, useful for testing Docker proxy configuration alone.

**With SOCKS5 forwarding (for full proxy chain):**

```
privoxy --no-daemon <(echo -e "listen-address 0.0.0.0:8118\nforward-socks5 / 127.0.0.1:9050 .\ndebug 1\n")
```

**Alternative - Using temporary config file:**

```
# Create temporary config
cat > /tmp/privoxy.conf << EOF
listen-address 0.0.0.0:8118
forward-socks5 / 127.0.0.1:9050 .
debug 1
EOF

# Run Privoxy
privoxy --no-daemon /tmp/privoxy.conf
```

This configures Privoxy to:

- Listen on all interfaces port `8118` for HTTP proxy requests
- Forward all traffic to the SOCKS5 proxy at `127.0.0.1:9050`
- Enable debug logging to monitor connections

### 3\. Configure Docker Daemon Proxy

Create or edit `/etc/docker/daemon.json` (requires sudo):

```
{
    "proxies": {
        "http-proxy": "http://127.0.0.1:8118",
        "https-proxy": "http://127.0.0.1:8118",
        "no-proxy": "localhost,127.0.0.0/8"
    }
}
```

Restart Docker daemon:

```
sudo systemctl restart docker
```

### 4\. Configure Docker Client Proxy

Create or edit `~/.docker/config.json` (user-level configuration):

```
{
    "proxies": {
        "default": {
            "httpProxy": "http://host.docker.internal:8118",
            "httpsProxy": "http://host.docker.internal:8118",
            "noProxy": "localhost,127.0.0.1/8,::1,*.ddev.site"
        }
    }
}
```

> [!NOTE]
>
> **Docker Network Access**
>
> Using `host.docker.internal:8118` allows containers to reach the proxy running on the host system.

### 5\. Test the Proxy Setup

> [!TIP]
>
> **Monitoring Connections**
>
> Keep the Privoxy terminal window visible to monitor proxy connections and debug any issues.

**Test Docker daemon proxy:**

```
# Test Docker registry access
docker pull ddev/ddev-utilities:latest

# Check Docker info for proxy configuration
docker info | grep -i proxy
```

**Test container proxy access:**

```
# Initialize and start a DDEV project if needed
# ddev config --auto
# ddev start

# Test container network access
ddev exec curl -v https://httpbin.org/ip

# Test package updates
ddev exec sudo apt-get update
```

**Verify proxy chain:**

You should see new connections appear in the Privoxy debug output, confirming that traffic is being routed through the proxy chain.

## Troubleshooting

### Connection Issues

If containers cannot reach the proxy:

**Verify Privoxy configuration:**

```
# Check if Privoxy is listening
netstat -an | grep 8118
# or
ss -tlnp | grep 8118
```

**Test host connectivity from container:**

```
# Check if host.docker.internal resolves
ddev exec nslookup host.docker.internal

# Test direct connection to proxy
ddev exec curl -v --connect-timeout 5 http://host.docker.internal:8118
```

**Check firewall and networking:**

- Ensure firewall rules allow traffic on port `8118`
- Verify Docker network configuration: `docker network inspect bridge`
- Check if SELinux/AppArmor is blocking connections

### Proxy Chain Issues

If the proxy chain is broken:

**Verify SOCKS5 proxy:**

```
# Check if SOCKS5 proxy is listening
netstat -an | grep 9050

# Test SOCKS5 proxy directly
curl --socks5 127.0.0.1:9050 https://httpbin.org/ip

# For WARP, check status
warp-cli status
```

**Debug Privoxy forwarding:**

```
# Test HTTP proxy directly
curl --proxy http://127.0.0.1:8118 https://httpbin.org/ip

# Check Privoxy logs for error messages
# Look for "forward-socks5" errors in the terminal output
```

**Common fixes:**

- Restart Privoxy with fresh configuration
- Verify SOCKS5 proxy port matches Privoxy forward configuration
- Check for conflicting proxy settings in environment variables

## Use Cases

This setup is valuable for testing:

- **Corporate proxy environments** - Simulate enterprise networks with mandatory proxy usage
- **Proxy authentication scenarios** - With additional Privoxy configuration for username/password auth

## Cleanup

When finished testing:

```
# Stop DDEV if running
ddev poweroff

# Remove Docker proxy configuration from
# /etc/docker/daemon.json
# ~/.docker/config.json

# Restart Docker
sudo systemctl restart docker

# Stop proxy services
# Ctrl+C in Privoxy terminal
# For WARP: warp-cli disconnect
# For Tor: Ctrl+C in Tor terminal
```

---

This HTTP proxy setup provides a realistic simulation of corporate network environments where all traffic must route through proxy servers, helping ensure DDEV works reliably in such configurations.

# Developing and Improving DDEV

This section is for folks making contributions to DDEV. It covers how to build and release Docker images, and contribute documentation.

# Maintainer Tasks, Privileges, Resources

## THANK YOU

We so appreciate our amazing maintainers. There are so many things to keep track of, including support, testing, test runners, improvements, and a thousand other things. This section attempts to document some of the things that maintainers need to know and do.

## Maintainer Responsibilities

Not all maintainers can do all these things at any given time, but these are the things that we hope get done in the DDEV project:

- **Support**: We try to give friendly, accurate, and timely responses to those who need help in:

  - [Issue queue](<https://github.com/ddev/ddev/issues>) (and discussions, etc). Please follow all in at least the ddev/ddev project. On the Watch/Unwatch button at the top of the repository, consider selecting “All Activity”. Also consider this on other projects in the `ddev` organization or other projects that are in your interest area.
  - Discord: Please read everything that happens in the [DDEV Discord](<https://ddev.com/s/discord>) and respond to questions that you can help with.
  - Often in [Drupal Slack](<https://www.drupal.org/join-slack>) \#ddev channel. We have tried and tried to get people over to Discord, but it’s still pretty active there.
  - Other add-on repositories or related repos where we can help.
- **Test Runner and Test System Maintenance**: The testing system is complex, and most tests are end-to-end tests, which can be fragile due to design, internet problems, changes upstream, etc. When something goes wrong, we want to figure out what it is and make it better. This can include debugging or rebooting Buildkite-runners, etc.
- **Test Maintenance**: Getting great tests that tell us what we need to know without taking forever and without being fragile is a never-ending battle. Improvements are always a goal. But it’s fundamental that we be able to pass tests before we add new PRs in.
- **Improve the DDEV codebase with fixes and features**: We try to listen to the community and improve based on their needs.
- **Security Best Practices**: Please make sure to remain current on all security best practices. Your GitHub login and 1Password access absolutely must be managed with 2FA. Be aware of the fact that someone who compromises your privileges could attack our entire user base. If you have any questions about best practices, let’s talk and make sure we all understand what’s going on.

## Appropriate Use of Privileges

- We prefer the forked-PR workflow for all code changes. There are a few cases where a branch-PR on `ddev/ddev`, but in general, to do a fix or a feature, do it on a branch on your fork, and submit it as a forked PR.
- Even though you may have privileges to do things like push directly to the default branch of a repository, it doesn’t mean you should use them. The vast majority of the time you’ll use the codebase the same as any other contributor. PRs make it clear both now and in the future why changes were made.
- Use clear PRs and write great issues even though you yourself may understand exactly what’s going on. Remember that you may need a refresher course in what you did in a month or a year, so write a great PR description and fill in the form.
- Remember to talk about configuration changes you make with other maintainers. Don’t waste their time by changing things they’ll then have to discover and debug.

## Maintainer Documentation Resources

- [DDEV Developer Documentation](<https://ddev.github.io/ddev/en/stable/developers/index.md>)
- [Maintainer Private Repository](<https://github.com/ddev/maintainer-info>). This has information that may be sensitive, with screencasts and tips.
- [DDEV Contributor Training](<https://ddev.com/blog/contributor-training/>), a series of training sessions that were recorded.
- [DDEV blog](<https://ddev.com/blog>)
- 1Password passwords and tokens: Maintainers should be added to the DDEV team in 1Password. This gives access to the DDEV team vault, which has tokens and passwords that are needed for various things. Please try to maintain things like tokens in there.

## Privileges Required for Maintainers

Most privileges should be granted per-developer as separate accounts. In general, we don’t want to share a common login. So for example, instead of sharing a login to [developer.apple.com](<https://developer.apple.com>) or [buildkite.com](<https://buildkite.com/ddev>) each maintainer should have their own login.

There are cases like access to hosting provider integrations that have essentially no value upstream where a shared login is acceptable. And of course, tokens listed in 1Password are a type of shared login. Our hosting integrations like Acquia, Upsun, etc. should never have any valuable things to attack anyway, so these should be very low risk. However, the bad guys are always trying new things…

- **GitHub**: Maintainers should usually be added to the [DDEV organization](<https://github.com/orgs/ddev/people>), usually was “owner”, but lesser privileges are possible, and some maintainers may want only access to the DDEV project, etc.
- **Buildkite**: Maintainers should be added to the [DDEV Buildkite organization](<https://buildkite.com/organizations/ddev/users>) with “maintainer” privileges. This gives access to the Buildkite pipelines and the ability to add new pipelines. Do not require “SSO” or people won’t be able to get in.
- **Google Workspace**: Maintainers should usually be added to the Admin Console, have their own email `@ddev.com`, and be added to various email groups.
- **YouTube**: Channel credentials are stored in 1Password.
- **Chrome Remote Desktop**: This is the test runner login (“DDEV buildkite test-runners - remotedesktop.google.com”) from 1Password, but it will need to be authorized via 2FA or a backup code from 1Password.
- **CircleCI**: Maintainers automatically have some access via their GitHub team membership, but should probably get more.
- **developer.apple.com**: Add to the DDEV team there so certificates can be managed.
- **hub.docker.com**: Add user to owners team in DDEV org.
- **AUR**: Add user to Co-maintainers (account should be created first) for `ddev-bin` and `ddev-edge-bin`.
- **Packagist**: Add user to Maintainers (login with GitHub) for `ddev/ddev-test-composer-create`.
- **Chocolatey**: Add user to [Manage maintainers](<https://community.chocolatey.org/packages/ddev/ManagePackageOwners>).
- **Read the Docs**: Add user to [Maintainers](<https://readthedocs.org/dashboard/ddev/users/>).
- **Icinga monitoring system**: This is documented in [maintainer-info](<https://github.com/ddev/maintainer-info>).
- **Discord**: Make admin in Discord.
- **LinkedIn**: Add to the DDEV Foundation company page.
- **Bluesky**: Posting is enabled by login in 1Password.
- **Mastodon**: Posting is enabled by login in 1Password.
- **Zoho Mail** is how `ddev.com` mail is routed; currently only Randy has an account, but we should consider adding others and making sure that more than one person can maintain it.
- **Zoho CRM** is how we track contacts and send monthly emails or announcements. People involved in marketing will want to have access to this, but it will cost for additional users.
- **[1Password](<https://1password.com/>)**. Maintainers should be added to the DDEV team in 1Password. This gives access to the DDEV team vault, which has tokens and passwords that are needed for various things. Please try to maintain things like tokens in there.
- Acquia Cloud test account
- Upsun test accounts
- Pantheon test account
- Lagoon test account
- [monitor.ddev.com](<https://monitor.ddev.com/icingaweb2/dashboard>) (Test runner monitoring).
- SSH (and sudo) access to `monitor.ddev.com`
- **[developer.apple.com](<https://developer.apple.com>)** - Maintainers should be added to the DDEV team in the Apple Developer program, so that they can create new certificates.
- **SSH access to monitor.ddev.com**.
- **Account on pi.ddev.site**.
- **Notifications from monitor.ddev.com**.
- **Web access to monitor.ddev.com**.
- **SSH access to behind-firewall monitoring proxy**.
- **Amplitude**: Invite new user at [team management](<https://analytics.amplitude.com/ddev/settings/team>).

## GitHub Notifications for Organization

To receive emails from the DDEV org to a specific email like `@ddev.com`, maintainers should add it in “Settings” -\> “Emails” in their GitHub account and set up routing for the organization and email in “Settings” -\> “Notifications” -\> “Custom routing”.

GitHub does not automatically subscribe you to notifications for all repositories in an organization. Maintainers should:

- Subscribe to each repository manually by opening the repository page, clicking the “Watch” button in the top right corner, and selecting “All Activity”.
- When new repositories are created or transferred, remember to subscribe to them as well.

## Watching Third-Party Repositories

Subscribe to repositories outside the organization by checking what colleagues have in their [Watched repositories](<https://github.com/watching>).

One important repository to watch is [`oerdnj/deb.sury.org`](<https://codeberg.org/oerdnj/deb.sury.org>).

It is not required to watch all activity in third-party repositories, but maintainers should consider watching the following for important updates (“Watch” -\> “Custom” -\> select “Releases”):

- [`abiosoft/colima`](<https://github.com/abiosoft/colima>)
- [`docker/compose`](<https://github.com/docker/compose>)
- [`goreleaser/goreleaser`](<https://github.com/goreleaser/goreleaser>)
- [`lima-vm/lima`](<https://github.com/lima-vm/lima>)
- [`MariaDB/server`](<https://github.com/MariaDB/server>)
- [`moby/moby`](<https://github.com/moby/moby>)
- [`rancher-sandbox/rancher-desktop`](<https://github.com/rancher-sandbox/rancher-desktop>)
- [`traefik/traefik`](<https://github.com/traefik/traefik>)
- [`xdebug/xdebug`](<https://github.com/xdebug/xdebug>)

Non-GitHub resources to monitor for important updates:

- [Docker Desktop Release Notes](<https://docs.docker.com/desktop/release-notes/>)
- [OrbStack Release Notes](<https://docs.orbstack.dev/release-notes>)

## GitHub Notifications for Scheduled Workflow Runs

From GitHub documentation:

> Notifications for scheduled workflows are sent to the user who initially created the workflow. If a different user updates the cron syntax in the workflow file, subsequent notifications will be sent to that user instead. If a scheduled workflow is disabled and then re-enabled, notifications will be sent to the user who re-enabled the workflow rather than the user who last modified the cron syntax.

DDEV has a separate user for such scheduled workflows named `ddevactions` (credentials are stored in 1Password), which has the `member` role with `All-repository write` access to be able to manage GitHub Actions. Notifications from this account are forwarded to the team via an email group in Google Workspace.

To make the user receive notifications about scheduled events:

1. Go to the Actions tab of the GitHub repository.
2. Filter by Event: select `schedule`. (If there are none, skip this repository.)
3. Go through all the workflows and turn them off and on if they have scheduled events.
4. Repeat the same with other repositories in the organization.

How to understand who receives notifications about scheduled events:

1. Go to the Actions tab of the GitHub repository.
2. Filter by Event: select `schedule`. (If there are none, skip this repository.)
3. Go through all the workflows and open the last workflow log for the job, it will show which user triggered the event.

## monitor.ddev.com Use and Maintenance

[monitor.ddev.com](<https://monitor.ddev.com>) is an Icinga instance that monitors our Buildkite test runners and a few other things like [ddev.com](<https://ddev.com>), etc. It also monitors some of Randy’s small sites, but those can be ignored.

Maintainers have a login to [the dashboard](<https://monitor.ddev.com/icingaweb2/dashboard>) and should receive emails when problems are discovered.

You can quickly check [the dashboard](<https://monitor.ddev.com/icingaweb2/dashboard>) to see the current status if you get an email notification. Sometimes the tests are flaky, and of course during power outages or internet outages there may be un-resolvable items.

## Test Runner Maintenance

- When you change things on a test runner, or you solve a problem, or reboot it, add a comment to [ddev/maintainer-info/issues/6](<https://github.com/ddev/maintainer-info/issues/6>) so others will know what’s going on.

## Managing Forks

When other maintainers merge PRs from your fork, your branch is not deleted automatically.

To automate this:

1. Enable the “Automatically delete head branches” option in the fork repository “Settings” -\> “General”.
2. Invite other maintainers as collaborators in the fork repository “Settings” -\> “Collaborators”.

## Skipping Tests

### Skipping Tests via Commit Message

Include these keywords in your commit message or pull request title to skip CI runs:

- `[skip buildkite]` - Skip Buildkite tests only
- `[skip github]` - Skip GitHub Actions tests only
- `[skip ci]` - Skip all tests

### Skipping Specific Tests via `public-variables` Branch

To skip specific tests globally (including for fork PRs), edit the files directly on the [`public-variables` branch](<https://github.com/ddev/ddev/tree/public-variables/.github/public-variables>) - no PR required. Each file holds one value per line, or values separated by `|`.

#### Go tests

Pass the full Go test function name. `DDEV_EMBARGO_TESTS` is forwarded to `go test -skip` by the Makefile, so any test whose name matches the pattern is skipped automatically — no per-test code needed.

```
# Skip one Go test
DDEV_EMBARGO_TESTS="TestLagoonPull" make testddevapp

# Skip multiple Go tests (pipe-separated, treated as a regex alternation by go test -skip)
DDEV_EMBARGO_TESTS="TestLagoonPull|TestAcquiaPull|TestPantheonPush" make testddevapp

# Run a single test file, skipping specific tests
DDEV_EMBARGO_TESTS="TestRandString|TestFormatBytes/Large_volume" make testonefile TESTFILE=./pkg/util/utils_test.go

# Run a single test package, skipping specific tests
DDEV_EMBARGO_TESTS="TestRandString|TestDownloadFile" make testonepkg TESTPKG=./pkg/util
```

#### Bats (quickstart) tests

Patterns are matched as **case-sensitive substrings** against:

1. The bats **filename** (without `.bats`), e.g. `sveltekit` for `sveltekit.bats`
2. The **`@test` description** string

```
# Run all bats tests, skipping drupal (matches drupal.bats by filename)
DDEV_EMBARGO_TESTS="drupal" make quickstart-test

# Skip only the Composer test inside symfony.bats (matches the description)
DDEV_EMBARGO_TESTS="Symfony Composer" bats docs/tests/symfony.bats

# Skip all drupal tests except "Drupal CMS" (list the descriptions to skip by name)
DDEV_EMBARGO_TESTS="Drupal 12|Drupal 11 quickstart|Drupal 10|Drupal 11 git" bats docs/tests/drupal.bats

# Mix Go and bats patterns — set in public-variables for CI; test locally with each runner separately
DDEV_EMBARGO_TESTS="TestLagoonPull|sveltekit|Symfony Composer" make testddevapp
DDEV_EMBARGO_TESTS="TestLagoonPull|sveltekit|Symfony Composer" bats docs/tests/sveltekit.bats docs/tests/symfony.bats
```

#### PHP version embargo

```
# Skip specific PHP versions in TestPHPConfig
DDEV_EMBARGO_PHP_VERSIONS="7.0|7.1" make testddevapp
```

#### Notes

- Manually triggered (`workflow_dispatch`) runs **skip loading the `public-variables` branch entirely** so you can verify a fix without first removing it from the embargo list. Scheduled and PR-triggered runs always load it.
- Include `[skip ci]` in the commit message when updating the embargo to avoid triggering test workflows.
- To clear an embargo, empty the file on the `public-variables` branch.
- See [`.github/public-variables/README.md`](<https://github.com/ddev/ddev/blob/main/.github/public-variables/README.md>) for full details.

# Network Bandwidth Testing Environments

> [!TIP]
>
> **Related Testing**
>
> For testing HTTP proxies, see [HTTP Proxy Test Environments](<https://ddev.github.io/ddev/en/stable/developers/http-proxy-test-environments/index.md>).
>
> For testing SSL interception scenarios, see [Network Test Environments: Packet-Inspection VPN Simulation](<https://ddev.github.io/ddev/en/stable/developers/network-test-environments/index.md>).

This guide demonstrates how to simulate slow network connections for testing DDEV behavior under bandwidth-constrained conditions. This is useful for testing how DDEV performs in environments with limited internet connectivity, such as rural areas, mobile connections, or congested networks.

The setup involves:

- Identifying your network interface
- Installing network bandwidth limiting tools
- Applying bandwidth restrictions
- Testing DDEV operations under constrained conditions
- Removing bandwidth limitations when testing is complete

## Identify Your Network Interface

First, you need to identify which network interface you want to limit:

```
# List all network interfaces
ip link show

# Or use the older ifconfig command (if installed)
ifconfig -a

# Look for interfaces like:
# - eth0, enp7s0f1 (Ethernet)
# - wlan0, wlp3s0 (Wi-Fi)
# - docker0 (Docker bridge - avoid limiting this)
```

Common interface naming patterns:

- **Ethernet**: `eth0`, `enp7s0f1`, `eno1`
- **Wi-Fi**: `wlan0`, `wlp3s0`, `wlo1`
- **USB/Mobile**: `usb0`, `wwan0`

## Install Bandwidth Limiting Tools

### Wondershaper Installation

[Wondershaper](<https://github.com/magnific0/wondershaper>) is a simple bandwidth limiting tool that’s easy to use on Linux:

```
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install wondershaper

# CentOS/RHEL/Fedora
sudo dnf install wondershaper

# Arch Linux
yay -S wondershaper-git
```

## Apply Bandwidth Limitations

### Wondershaper Limits

Apply download and upload limits (values in kilobits per second):

```
# Basic usage: wondershaper -a <interface> -d <download_kbps> -u <upload_kbps>

# Simulate very slow connection (1 Mbps download)
sudo wondershaper -a enp7s0f1 -d 1024

# Simulate slow broadband (5 Mbps download)
sudo wondershaper -a enp7s0f1 -d 5120

# Simulate mobile connection (10 Mbps download)
sudo wondershaper -a enp7s0f1 -d 10240

# Remove all limitations
sudo wondershaper -a enp7s0f1 -c
```

Replace `enp7s0f1` with your actual network interface name from step 1.

> [!WARNING]
>
> **Remember to Remove Limits**
>
> Remember to remove bandwidth limitations after testing with `sudo wondershaper -a <interface> -c` to restore normal network performance.

## Test DDEV Operations

With bandwidth limitations in place, test various DDEV operations:

```
# Cleanup before testing
ddev poweroff
ddev delete --omit-snapshot
docker builder prune
docker volume rm ddev-global-cache

# Test fresh DDEV startup
ddev config --webimage-extra-packages=htop --nodejs-version=18
DDEV_VERBOSE=true ddev start
# Open the logs to watch in another terminal:
ddev logs -f

# Force download of docker-compose binary
rm -f $HOME/.ddev/bin/docker-compose && DDEV_DEBUG=true ddev version

# Test composer operations
ddev composer install
```

# Network Test Environments: Packet-Inspection VPN Simulation

> [!TIP]
>
> **Related Testing**
>
> For testing HTTP proxies, see [HTTP Proxy Test Environments](<https://ddev.github.io/ddev/en/stable/developers/http-proxy-test-environments/index.md>).
>
> For testing network bandwidth constraints, see [Network Bandwidth Testing Environments](<https://ddev.github.io/ddev/en/stable/developers/network-bandwidth-testing/index.md>).

> [!TIP]
>
> **Basic HTTP Proxy Testing**
>
> For simpler HTTP proxy testing without SSL interception, see [HTTP Proxy Test Environments](<https://ddev.github.io/ddev/en/stable/developers/http-proxy-test-environments/index.md>). Start there for basic proxy scenarios before moving to SSL interception testing.

## Simulating SSL Interception with Squid (Simplified via `HTTPS_PROXY`)

A straightforward way to simulate a packet-inspecting VPN is by using **Squid** with SSL bumping and configuring your environment to use it via `HTTPS_PROXY`. While it’s less transparent than a full MITM router setup, it closely replicates the behavior of Zscaler and similar tools from the perspective of apps like Docker and `curl`.

## Setup Overview

- Squid listens on port 3128.
- HTTPS traffic routed via the proxy is intercepted and re-signed with a custom CA.
- Clients that trust this CA will succeed; others will fail SSL validation.
- You simulate VPN-like interception by exporting `HTTPS_PROXY=http://localhost:3128`.

## Step-by-Step Instructions

These instructions are for Debian/Ubuntu but can be adapted for container-based setup or for another environment.

1. **Install Squid**

   ```
   sudo apt-get install squid-openssl ssl-cert
   ```
2. **Generate a Root CA for Signing** This `mitm.crt` is the CA certificate used by Squid to re-sign intercepted traffic, and it must be trusted by any client interacting through the proxy (e.g., Docker, cURL, system-wide tools).

   ```
   sudo openssl req -new -newkey rsa:2048 -days 365 -nodes -x509 \
     -keyout /etc/squid/mitm.key \
     -out /etc/squid/mitm.crt \
     -subj "/CN=SquidMITMTest"
   ```
3. **Configure Squid for SSL Bumping**

   Edit `/etc/squid/squid.conf`, replacing or appending the following:

   ```
   http_port 3128 ssl-bump cert=/etc/squid/mitm.crt key=/etc/squid/mitm.key generate-host-certificates=on dynamic_cert_mem_cache_size=4MB

   sslcrtd_program /usr/lib/squid/security_file_certgen -s /var/lib/ssl_db -M 4MB
   sslcrtd_children 5

   ssl_bump server-first all

   http_access allow all
   ```
4. **Initialize Squid’s SSL Certificate Store**

   ```
   sudo /usr/lib/squid/security_file_certgen -c -s /var/lib/ssl_db -M 4MB
   sudo chown -R proxy: /var/lib/ssl_db
   ```
5. **Restart Squid**

   ```
   sudo systemctl restart squid
   ```
6. **Export HTTPS Proxy for Testing**

   ```
   export HTTPS_PROXY=http://squid.host-only:3128
   ```

---

## Testing Proxy Behavior

Once the proxy is running and your environment is configured, test both Docker registry access and in-container HTTPS access.

### Test Docker Pull

```
export HTTPS_PROXY=http://squid.host-only:3128
docker pull alpine
```

- If Docker trusts the Squid CA, the pull will succeed.
- If not, you’ll see x509 or certificate verification errors.

## Trusting the CA for Docker Pulls

Docker does not use the system trust store. To allow `docker pull` to work when HTTPS is intercepted by Squid, you must explicitly trust the Squid CA by placing it in Docker’s certificate directory:

```
sudo mkdir -p /etc/docker/certs.d/
sudo cp /etc/squid/mitm.crt /etc/docker/certs.d/
sudo systemctl restart docker
```

You can confirm Docker is using the proxy by watching the Squid logs while pulling:

```
docker pull alpine
```

```
sudo tail -f /var/log/squid/access.log | grep docker
```

This setup is sufficient for testing purposes. Docker will then trust any server certificates signed by the Squid CA.

### Test with OpenSSL (Raw Certificate Check)

```
openssl s_client -connect www.google.com:443 -proxy squid.host-only:3128 -CAfile /etc/squid/mitm.crt
```

### Test from Another Host (Linux or macOS)

You can verify Squid’s behavior from a different host using `curl`. These examples test HTTPS interception and validate that your CA is trusted.

#### Option 1: Explicit Proxy with `curl`

```
curl -I https://www.google.com --proxy http://squid.host-only:3128
```

- Replace `squid.host-only` with the IP address or hostname of your Squid proxy host.
- You should receive a `200 OK` response if the CA is trusted. Otherwise, you’ll get a certificate error.

#### Option 2: Using `HTTPS_PROXY` Environment Variable

```
export HTTPS_PROXY=http://squid.host-only:3128
curl -I https://www.google.com
```

This has the same effect as `--proxy` but applies to all tools that honor `HTTPS_PROXY`.

---

## Trusting the CA Certificate

If you receive certificate errors, install the Squid CA (`mitm.crt`) on the client system:

### On Linux

```
sudo cp mitm.crt /usr/local/share/ca-certificates/
sudo update-ca-certificates
```

### On macOS

1. Copy `mitm.crt` to your local system.
2. Open **Keychain Access**.
3. Select **System** in the sidebar.
4. Drag `mitm.crt` into the window.
5. Double-click the cert → expand **Trust** → set **“When using this certificate”** to **Always Trust**.
6. Close and enter your password when prompted.

### On WSL2

WSL2 behaves like native Linux. Use the same instructions as for Linux to trust the CA inside your WSL2 distro.

After installing the cert, re-run the `curl` test — you should no longer see SSL errors.

### Converting Exported PEM or CER Files to CRT

When exporting a CA certificate from your browser or OS, it might have a `.pem` or `.cer` extension. These formats are usually identical to `.crt`. You can rename them safely:

```
mv my-cert.pem my-cert.crt
mv my-cert.cer my-cert.crt
```

Just ensure the file begins with:

```
-----BEGIN CERTIFICATE-----
```

If so, it can be used with `update-ca-certificates`, Docker, or as a trusted CA in testing.

---

## Optional: Verify CA Without Installing It

To test the Squid CA without installing it, you can use:

```
curl -I https://www.google.com --proxy http://squid.host-only:3128 --cacert /etc/squid/mitm.crt
```

This helps confirm that the proxy and CA work before trusting the cert system-wide.

---

### Quick Recap

| Environment | Where to install CA | Trust command or method |
| --- | --- | --- |
| Linux (host) | `/usr/local/share/ca-certificates` | `update-ca-certificates` |
| macOS | System Keychain | Keychain Access → “Always Trust” |
| Docker Engine | `/etc/docker/certs.d/ca.crt` | `systemctl restart docker` |
| Inside container | `/usr/local/share/ca-certificates` | `update-ca-certificates` inside container |
| WSL2 | Same as Linux | `update-ca-certificates` |

---

## Monitoring Squid Logs to Verify Traffic Path

You can monitor the Squid log in another terminal to confirm proxy use:

```
sudo tail -f /var/log/squid/access.log
```

or for example

```
sudo tail -f /var/log/squid/access.log | grep docker
```

---

This `HTTPS_PROXY`-based setup is simpler and provides a very effective way to simulate real-world TLS inspection without needing DNS or firewall redirection.

# Adding New Project Types

Adding and maintaining project types (like `typo3`, `magento2`, etc.) is not too hard. Please update and add to this doc when you find things that have been missed.

To add a new project type:

- Add the new type to the list in `nodeps/values.go`
- Add to `appTypeMatrix` in `apptypes.go`
- Add to `properties.type` in `ddevapp/schema.json`
- Add to `project_type` test loop in `ddev-webserver/test.sh`
- Add to `type` in `templates.go` comments
- Create a new go file for your project type, like `mytype.go`.
- Implement the functions that you think are needed for your project type and add references to them in your `appTypeMatrix` stanza. There are lots of examples that you can start with in places like `drupal.go` and `typo3.go`, `shopware6.go`, etc. The comments in the code in `apptypes.go` for the `appTypeFuncs` for each type of action tell what these are for, but here’s a quick summary.

  - `settingsCreator` is the function that will create a main settings file if none exists.
  - `uploadDir` returns the filepath of the user-uploaded files directory for the project type, like `sites/default/files` for Drupal or `media` for Magento 2.
  - `hookDefaultComments` adds comments to `config.yaml` about hooks with an example for that project type. It’s probably not useful at all.
  - `apptypeSettingsPaths` returns the paths for the main settings file and the extra settings file that DDEV may create (like `settings.ddev.php` for Drupal).
  - `appTypeDetect` is a function that determines whether the project is of the type you’re implementing.
  - `postImportDBAction` can do something after db import. I don’t see it implemented anywhere.
  - `configOverrideAction` can change default config for your project type. For example, your CMS may require `php8.3`, so a `configOverrideAction` can change the php version.
  - `postConfigAction` gives a chance to do something at the end of config, but it doesn’t seem to be used anywhere.
  - `postStartAction` adds actions at the end of [`ddev start`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#start>). You’ll see several implementations of this, for things like creating needed default directories, or setting permissions on files, etc.
  - `importFilesAction` defines how [`ddev import-files`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#import-files>) works for this project type.
  - `defaultWorkingDirMap` allows the project type to override the project’s [`working_dir`](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#working_dir>) (where [`ddev ssh`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#ssh>) and [`ddev exec`](<https://ddev.github.io/ddev/en/stable/users/usage/commands/#exec>) start by default). This is mostly not done anymore, as the `working_dir` is typically the project root.
  - `composerCreateAllowedPaths` specifies the paths that can exist in a directory when `ddev composer create-project` is being used.
- You’ll likely need templates for settings files, use the Drupal or TYPO3 templates as examples, for example `pkg/ddevapp/drupal` and `pkg/ddevapp/typo3`. Those templates have to be loaded at runtime as well.
- Implement `nginx-site-<project-type>.conf` in `webserver_config_assets`. You can use `webserver_config_assets/nginx-site-php.conf` as a pattern, or something from the upstream project.
- Upload the project detection file stubs to the `testdata/TestDetectAppType` folder.
- Add to `appTypes` test slice for `TestConfigOverrideAction` in `ddevapp/apptypes_test.go`.
- If the project type has a custom command, add it to `global_dotddev_assets/commands/web` folder.
- Once your project type starts working and behaving as you’d like, you’ll need to add test artifacts for it and try testing it (locally first).

  - Add your project to `TestSites` in `ddevapp_test.go`.
  - Create a DDEV project named `testpkg<projectype>` somewhere and get it going and working with a database and files you can export.
  - Export the database, files, and (optionally) code to tarballs or `.sql.gz`. Put them somewhere on the internet—they’ll end up in `ddev/test-<projectype>`. We will give you permissions on that if you like. The `magento2` project has descriptions explaining how each tarball gets created. Do that for yours as well.
  - Run the test and get it working. I usually use the trick of setting `GOTEST_SHORT=<element_in_TestSites>`, like `GOTEST_SHORT=7`. Then set that environment variable in the GoLand profile or your environment. `export GOTEST_SHORT=7 && make testpkg TEST_ARGS="-run TestDdevFullsiteSetup"`
- (We can assist you with this step if needed) Upload your project to GitHub or create an upstream fork ([example for Laravel](<https://github.com/ddev/test-laravel>)):

  - Create a `ddev-automated-test` branch, set it as the default.
  - Commit all vendor dependencies, but don’t commit the `.ddev` directory.
  - Update the `README.md` instructions.
  - Create a new release and attach the database and file artifacts.
  - Transfer the repository to DDEV, we will maintain your access. (Ask us to do this after opening the PR.)
- Update the documentation:

  - If it doesn’t pass our spell check, add the word to `.spellcheckwordlist.txt`
  - Add the new type to `users/configuration/config.md`
  - Update the `users/quickstart.md`
  - If there is a new command, add it to `users/usage/commands.md` and `users/usage/cli.md`

# Contributing a Quickstart Guide

A quickstart guide is a teaching tool that helps new users get started with a specific project type in DDEV. This document explains how to create and contribute a new quickstart guide.

Project Type quickstarts are pretty easy to add as just docs in [quickstarts](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>),

- We want to keep them consistent.
- To make them maintainable, we need automated tests.

## Before You Begin

- Review [existing quickstarts](<https://github.com/ddev/ddev/blob/main/docs/content/users/quickstart.md>) in the DDEV documentation for reference.
- Review [existing automated tests](<https://github.com/ddev/ddev/tree/main/docs/tests>) to see how the tests work.

## Creating a Quickstart

The quickstart can be based on one of the existing [quickstarts](<https://ddev.github.io/ddev/en/stable/users/quickstart/index.md>).

The general intention is that it should be a *teaching* tool. It will not cover all the complexities of the project type being discussed. Try for the most straightforward, repeatable, testable approach so that a naive person with no experience on the project type can walk through it. People with more experience with the project type should be able to adapt the provided instructions to meet their needs.

In general:

1. Add a link to the upstream installation or “Getting Started” web page, so people can know where the instructions are coming from.
2. Use `mkdir my-<projecttype>-site && cd my-<projecttype>-site` as the opener. (There are places like Magento 2 where the project name must be used later in the recipe, in those cases, use an environment variable, like `PROJECT_NAME=my-<projecttype>-site`.)
3. Composer-based recipes are preferable, unless the project does not use or prefer composer.
4. If your project type does not yet appear in the DDEV documentation, your PR should add the name to the [.spellcheckwordlist.txt](<https://github.com/ddev/ddev/blob/main/.spellcheckwordlist.txt>) so it can pass the spell check test.
5. If your project installation requires providing an administrative username and/or password, make sure to indicate clearly in the instructions what it is.
6. If your project type includes folders that accept public files (such as images), for example, `public/media`, make sure to add them to the [config](<https://ddev.github.io/ddev/en/stable/users/configuration/config/#upload_dirs>) command:

   ```
   ddev config ... --upload-dirs=public/media
   ```

## Automated Tests

1. Each new quickstart needs to have automated tests.
2. You can base your test on an example like the [Backdrop test](<https://github.com/ddev/ddev/blob/main/docs/tests/backdrop.bats>) and adapt to cover the steps in your quickstart.
3. You can run `bats` locally.

   - See [`bats-core` documentation](<https://bats-core.readthedocs.io/en/stable/>).
   - See [`bats-assert`, `bats-file`, and `bats-support` libraries documentation](<https://github.com/bats-core/homebrew-bats-core>).
   - If you install `bats` libraries manually (without package managers), make sure to set the `BATS_LIB_PATH` environment variable to the appropriate path. For example:

     ```
     export BATS_LIB_PATH=/path/to/bats
     ```
   - To run the docs tests, `cd docs && bats tests` or `bats tests/backdrop.bats` for example.

## Final Note

THANK YOU FOR CONTRIBUTING! ❤️

# Release Management &amp; Docker Images

## Release process and tools

- [GoReleaser Pro](<https://goreleaser.com/pro/>) is used to do the actual releasing using [.goreleaser.yml](<https://github.com/ddev/ddev/blob/main/.goreleaser.yml>). GoReleaser Pro is a licensed product that requires separate installation and a license key, which is in the GitHub Workflow configuration and is available in 1Password to DDEV maintainers who need it.
- The [Main Build/Release GitHub Action](<https://github.com/ddev/ddev/blob/main/.github/workflows/main-build.yml>) does the actual running of the GoReleaser actions and provides the needed secrets.

## GitHub Actions Required Secrets

### How to add new people to these accounts

- AUR is Arch Linux User Repository. `ddev-bin` is at `https://aur.archlinux.org/packages/ddev-bin`. The current maintainer of this is [@rfay](<https://github.com/rfay> "GitHub User: rfay"), who can add co-maintainers.
- The [chocolatey](<https://community.chocolatey.org/packages/ddev/>) package. Additional maintainers can be added at (login required) `https://community.chocolatey.org/packages/ddev/ManagePackageOwners`; they could then create tokens to push it.
- GitHub requires write access to this repository, either via permissions on the repository or on the org.
- Apple signing and notarization requires access to the DDEV Foundation group on `https://developer.apple.com`. It’s easy enough to add additional people.
- Windows signing is an awkward process that requires a dongle. When the current signing certificate expires we definitely want the simpler approach.
- Discord
- Docker

### Environment variables required

These are normally configured in the repository environment variables.

- `AUR_EDGE_GIT_URL`: The Git URL for AUR edge (normally `ddev-edge-bin`), for example `ssh://aur@aur.archlinux.org/ddev-edge-bin.git`.
- `AUR_PACKAGE_NAME`: The base name of the AUR package. Normally `ddev` for production, but `ddev-test` for testing repository.
- `AUR_STABLE_GIT_URL`: The Git URL for AUR stable (normally `ddev-bin`), for example `ssh://aur@aur.archlinux.org/ddev-bin.git`.
- `CLOUDSMITH_ORG`: The organization on [Cloudsmith](<https://cloudsmith.com>) that receives `apt`/`yum` package pushes.
- `CLOUDSMITH_REPO`: The repository within `CLOUDSMITH_ORG` that receives package pushes, so `ddev-test/ddev` can push to a separate test repository from `ddev/ddev`.
- `DDEV_IGNORE_EXPIRING_KEYS`: If the value is `"false"` then daily tests will fail if signing keys are expiring soon, default is `"false"` on `ddev/ddev`
- `DDEV_MAX_DAYS_BEFORE_CERT_EXPIRATION`: Number of days before expiration to warn about expiring signing keys, default is `90` on `ddev/ddev`.
- `DDEV_WINDOWS_SIGN`: If the value is `"true"` then `make` will attempt to sign the Windows executables, which requires building on our self-hosted Windows runner.
- `DISABLE_NOTARIZATION`: If the value is `"true"` then notarization of macOS apps will be skipped, otherwise notarization is attempted.
- `DOCKERHUB_USERNAME`: Username for pushing to `hub.docker.com` or updating image descriptions. Usually `ddevmachinepush`.
- `DOCKER_ORG`: The organization on `hub.docker.org` to push to. Currently `ddev` on `ddev/ddev` and `ddevhq` on `ddev-test/ddev`.
- `FURY_ACCOUNT`: [Gemfury](<https://gemfury.com>) account that receives package pushes. `drud` on `ddev/ddev` for historical reasons, and `rfay` on `ddev-test/ddev` because that’s a spare account there.
- `HOMEBREW_EDGE_REPOSITORY`: Like `ddev/homebrew-ddev-edge` but might be another repository like be `ddev-test/homebrew-ddev-edge`.
- `HOMEBREW_STABLE_REPOSITORY`: Like `ddev/homebrew-ddev` but might be another repository like `ddev-test/homebrew-ddev`.

### GitHub Actions Secrets Required

- `AMPLITUDE_API_KEY`: Key that enables Amplitude reporting. Environment variable for Make is `AmplitudeAPIKey`. Unfortunately, the `1password/load-secrets-action` does not work with Windows (see [issue](<https://github.com/1Password/load-secrets-action/issues/46>)).
- `AMPLITUDE_API_KEY_DEV`: Key that enables Amplitude reporting for development versions e.g. a PR build. Environment variable for Make is `AmplitudeAPIKey`.

### 1Password secrets required

The following “Repository secret” environment variables must be configured in 1Password:

- `AUR_SSH_PRIVATE_KEY`: Private SSH key for the `ddev-releaser` user. This must be processed into a single line, for example, `perl -p -e 's/\n/<SPLIT>/' ~/.ssh/id_rsa_ddev_releaser| pbcopy`.
- `CHOCOLATEY_API_KEY`: API key for Chocolatey.
- `DDEV_CLOUDSMITH_API_TOKEN`: API token for the `CLOUDSMITH_ORG`/`CLOUDSMITH_REPO` above.
- `DDEV_GITHUB_TOKEN`: GitHub personal token (`repo` scope, classic PAT) that gives access to create releases and push to the Homebrew repositories.
- `DDEV_MACOS_APP_PASSWORD`: Password used for notarization, see [signing\_tools](<https://github.com/ddev/signing_tools>).
- `DDEV_WINDOWS_SIGNING_PASSWORD`: Windows signing password.
- `DOCKERHUB_TOKEN`: Token for pushing to `hub.docker.com`. or updating image descriptions.
- `FURY_TOKEN`: Push token assigned to the above Gemfury account.
- `GORELEASER_KEY`: License key for GoReleaser Pro.

The macOS Developer ID certificate and its password are stored in the `ddev-signing` vault, not `push-secrets`. Configure the `DDEV_SIGNING_SERVICE_ACCOUNT_TOKEN` GitHub Actions secret with a dedicated, read-only service account that has access only to that vault. The macOS release job downloads the certificate to a temporary file and deletes it when the job exits.

## Creating a Release

> [!TIP]
>
> **This is completely automated now, so nothing needs to be done unless something goes wrong.**

### Prerelease Tasks

- Create and execute a test plan.
- Run `make release-prep TAG=vX.Y.Z` and open a pull request with the result, so every image is rebuilt, pushed and tested under the release. See [Preparing the image tags](<#preparing-the-image-tags-make-release-prep>) below.
- Merge that pull request into `main` before creating the release. `pkg/versionconstants/versionconstants.go`’s image tags are plain source constants, not `-ldflags`, so a release tagged before the merge builds a binary that still names the prerelease image tags, even though the registry already has `vX.Y.Z` images under the new ones.

### Preparing the image tags: `make release-prep`

`make release-prep TAG=v1.25.4` — or bare `make release-prep`, which asks for the tag — does the source-file half of a release:

- Stamps `# ddev-release-marker: v1.25.4` into every image’s `Dockerfile`, replacing any marker left by a previous release. A Dockerfile comment is stripped by the parser, so this moves the image’s content hash without changing a single layer of the image it produces, which is what makes CI rebuild all of them.
- Rewrites each tag in [`pkg/versionconstants/versionconstants.go`](<https://github.com/ddev/ddev/blob/main/pkg/versionconstants/versionconstants.go>) to the resulting hash, and each `<TagVar>Branch` to `v1.25.4` so `ddev version` names the release.

It builds nothing and commits nothing. Commit the result and open a pull request: the [Image build](<https://github.com/ddev/ddev/blob/main/.github/workflows/image-build-push.yml>) workflow builds every image, publishes it under its content hash *and* under `v1.25.4` and `latest`, and the test suites then run against those exact images, before the release is cut. Nothing has to be dispatched by hand.

Open that pull request from a branch in this repository, not from a fork. `create-manifests`, the job that adds the release names, doesn’t run for fork pull requests, so a release branch pushed to a fork would build every image and quietly leave `vX.Y.Z` and `latest` off. `detect` fails the run when it finds a release marker on a fork pull request, before anything is built.

`release-prep` also takes a prerelease tag (`v1.25.4-alpha1`, `-beta2`, `-rc1`), which follows exactly the same path except that `latest` is left pointing at the last stable release. No other suffix is accepted, so `git describe` output can’t be stamped as a release by accident.

For a stable release, `latest` moves when that pull request builds rather than when the GitHub release is created.

The trailing `// <branch>-<hash>` comment on each tag keeps naming the branch rather than the release, because that is the alias the push actually publishes; `containers/validate-image-tag.sh` rejects an alias whose prefix is release-shaped, so a `v1.25.4-<hash>` tag never exists.

### Actual Release Creation

1. Confirm the `release-prep` pull request above is merged to `main` — the release tag has to be cut from a commit that already has the new tags in `versionconstants.go`, not from a `main` that still points at the previous release’s images.
2. Create a [release](<https://github.com/ddev/ddev/releases>) for the new version using the GitHub UI. It should be “prerelease” if it’s an edge release.
3. Make sure you’re about to create the right release tag.
4. Use the “Auto-generate release notes” option to get the commit list, then edit to add all the other necessary info.

## Automatic Image Build and Push

Any pull request that changes `containers/` — including from a fork — is built and pushed automatically by the [Image build](<https://github.com/ddev/ddev/blob/main/.github/workflows/image-build-push.yml>) / [Image push](<https://github.com/ddev/ddev/blob/main/.github/workflows/image-push.yml>) workflow pair. See [Automatic Image Build and Push](<https://ddev.github.io/ddev/en/stable/developers/building-contributing/#automatic-image-build-and-push>) in the contributing guide for how the flow works and why it’s safe to run on fork-authored Dockerfiles.

A release no longer needs any of this. When `detect` sees a release marker in an image’s `Dockerfile`, `create-manifests` publishes `vX.Y.Z` and `latest` as further names on the manifest it is already creating — the same build the release pull request’s tests then run against, rather than a separate rebuild. It skips both if `vX.Y.Z` already exists in the registry, so the marker left behind after the release merges can’t move a released tag onto a later build.

The two workflows below (manual `workflow_dispatch`) remain for re-pushing a specific tag by hand. Their `tag` input is optional: leave it empty and the workflow uses the tag the checkout actually needs, which is safer than retyping a content hash.

When the tag is a content hash, these workflows also publish the `<branch>-<hash>` alias next to it — the same second name the automatic flow creates — so a manual push doesn’t leave a bare hash with nothing readable beside it in the registry. A `vX.Y.Z` tag is already readable and gets no alias.

A `containers/ddev-dbserver` change builds and pushes all 20 database variants (36 jobs), because they all share a single `BaseDBTag`. That variant matrix lives in `containers/ddev-dbserver/variants.txt` and is read by `variants.sh`, which also generates that directory’s make targets, the automatic flow’s image list, and `push-tagged-dbimage.yml`’s matrix — add a database version there and every consumer picks it up.

### One-time setup: the `image-push` GitHub Environment

Fork PRs from a contributor without push access go through a single approval, gated by the `image-push` GitHub Environment (Settings → Environments), *before* anything is built — as soon as `detect` finds an image that needs building:

1. Create the environment `image-push`.
2. Add required reviewers (the maintainers/dev team).
3. Leave `PUSH_SERVICE_ACCOUNT_TOKEN` as a repository secret. The environment gates the approval, not the secret: one job holds the approval and the build/push jobs run after it, so a run costs one approval rather than one per image, and those jobs read the repository secret — the same one the non-fork path has always used.

This approval only applies to fork PRs from a contributor without push access — checked via `author_association`. A fork PR from a maintainer’s own fork (`OWNER`/`MEMBER`/`COLLABORATOR`), a push to `main`, or a same-repo PR all build and push without any approval at all, using the repository-level `PUSH_SERVICE_ACCOUNT_TOKEN` secret directly (those paths never gate on `environment:`, so this environment’s protection rules don’t apply to them).

When testing this on `ddev-test/ddev`, do the same steps there first, and confirm `vars.DOCKER_ORG` on that repository points at the DockerHub org used for testing.

That org is not the one `versionconstants.go` names, so a binary built from `ddev-test/ddev` asks for `ddev/ddev-webserver:vX.Y.Z` while its images were published to `ddevhq`. Set `DDEV_DOCKER_ORG` to pull them from where they actually landed:

```
DDEV_DOCKER_ORG=ddevhq ddev start
```

It replaces the org on the web, db, router, ssh-agent, and xhgui images, leaving upstream images like `postgres` alone, and `ddev version` shows what it resolved to. Unset, it changes nothing.

Since a job referencing an environment that doesn’t exist yet gets auto-created with no protection rules (silently *not* gating), verify the environment actually has a `required_reviewers` rule before relying on it, e.g. `gh api repos/<owner>/<repo>/environments/image-push`.

## Pushing Docker Images with the GitHub Actions Workflow

The easiest way to push Docker images is to use the GitHub Actions workflow, especially if the code for the image is already in the [ddev/ddev](<https://github.com/ddev/ddev>) repository. For a normal container change on a pull request, you shouldn’t need this — see [Automatic Image Build and Push](<#automatic-image-build-and-push>) above.

### Actual release creation

1. Create a [release](<https://github.com/ddev/ddev/releases>) for the new version using the GitHub UI. It should be “prerelease” if it’s an edge release.
2. Use the “Auto-generate release notes” option to get the commit list, then edit to add all the other necessary info.
3. Verify that Homebrew (Linux and macOS) and Chocolatey and AUR are working correctly with the right versions.

You can push all images besides `ddev-dbserver` at [https://github.com/ddev/ddev/actions/workflows/push-tagged-image.yml](<https://github.com/ddev/ddev/actions/workflows/push-tagged-image.yml>)

You can push `ddev-dbserver` images at [https://github.com/ddev/ddev/actions/workflows/push-tagged-dbimage.yml](<https://github.com/ddev/ddev/actions/workflows/push-tagged-dbimage.yml>)

A forked PR that changes a container image no longer needs any of this — see [Automatic Image Build and Push](<#automatic-image-build-and-push>) above. The fork-your-own-secrets workaround described in earlier versions of this doc is superseded by that flow.

- Visit `https://github.com/ddev/ddev/actions/workflows/push-tagged-image.yml`.
- Click the “Push tagged image” workflow on the left side of the page.
- Click the “Run workflow” button in the blue section above the workflow runs.
- Choose the branch to build from (usually `main`).
- Enter the image (`ddev-webserver`, etc.).
- Enter the tag that will be used in `pkg/versionconstants/versionconstants.go`. For a normal (non-release) dev change, running `make` at the repository root already builds the image locally and computes/writes this tag automatically — run `make print-image-tags` to read the exact value to enter here.

## Pushing Docker Images Manually

While it’s more error-prone, images can be pushed from the command line:

1. `docker login` with a user that has push privileges.
2. `docker buildx use multi-arch-builder || docker buildx create --name multi-arch-builder --use`.
3. `cd containers/<image>`.
4. `make push VERSION=<release_version> DOCKER_ARGS=--no-cache` for most of the images. For `ddev-dbserver` it’s `make PUSH=true VERSION=<release_version> DOCKER_ARGS=--no-cache`. There’s a [push-all.sh](<https://github.com/ddev/ddev/blob/main/containers/push-all.sh>) script to update all of them, but it takes forever.
5. `ddev-dbserver` images can be pushed with `make PUSH=true VERSION=<release_version> DOCKER_ARGS=--no-cache` from the `containers/ddev-dbserver` directory.

## Maintaining `ddev-dbserver` MySQL 5.7 ARM64 Images

We don’t currently have a way to get `xtrabackup` for ARM64 Docker images for MySQL 5.7, so we have our own process to maintain [ddev/mysql-arm64-images](<https://github.com/ddev/mysql-arm64-images>), which uses Ubuntu 18.04 Docker images, where `xtrabackup` was available.

- `ddev/mysql:5.7` uses Ubuntu 18.04 as the base image, and Ubuntu 18.04 ARM64 has `mysql-server` 5.7 in it, so we can install.
- To build `ddev/mysql` (5.7) ARM64 images, follow the instructions on [ddev/mysql-arm64-images](<https://github.com/ddev/mysql-arm64-images>). After the files, you can push a new release and the proper images will be pushed. Since MySQL 5.7 (and Ubuntu 18.04) are EOL, it’s unlikely that there will be any new minor releases.

## Actual Release Docker Image Updates

We may not build every image for every point release. If there have been no changes to `ddev-traefik-router` or `ddev-ssh-agent`, for example, we may not push those and update `pkg/version/version.go` on major releases.

But here are the steps for building:

1. If you’re bumping `ddev-dbserver` 8.0 minor release, follow the upstream [Maintaining ddev-dbserver MySQL 5.7](<#maintaining-ddev-dbserver-mysql-57-arm64-images>) instructions.
2. Update `pkg/version/version.go` with the correct versions for the new images, and run all the tests.

## Manually Updating Homebrew Formulas

Homebrew formulas normally update with the release process, so nothing needs to be done.

If you have to temporarily update the Homebrew formulas, you can do that with a commit to [https://github.com/ddev/homebrew-ddev](<https://github.com/ddev/homebrew-ddev>) and [https://github.com/ddev/homebrew-ddev-edge](<https://github.com/ddev/homebrew-ddev-edge>). The bottles and checksums for macOS (High Sierra) and x86\_64\_linux are built and pushed to the release page automatically by the release build process (see [bump\_homebrew.sh](<https://github.com/ddev/ddev/blob/main/.ci-scripts/bump_homebrew.sh>)). Test `brew upgrade ddev` both on macOS and Linux and make sure DDEV is the right version and behaves well.

## Manually Updating Chocolatey

Normally the release process does okay with pushing to Chocolatey, but at times a failure can happen and it’s not worth doing the whole release process again.

Note that if an existing approved release is being updated you have to have a new version. So for example, if `v1.21.3` failed, you’ll need to work with `v1.21.3.1`, so `make chocolatey VERSION=v1.21.3.1` below.

- Open up GitHub Codespaces and

```
cd /workspace/ddev
git checkout <tag>
sudo apt-get update && sudo apt-get install -y nsis
sudo .ci-scripts/nsis_setup.sh /usr/share/nsis
```

- Edit the checksum in `tools/chocolateyinstall.ps1` to match the released checksum of the `ddev-windows-installer` in `checksums.txt` of the release that is being repaired, for example, for `v1.21.3` this would be the checksum for `ddev_windows_installer.v1.21.3.exe` in [v1.21.3 checksums.txt](<https://github.com/ddev/ddev/releases/download/v1.21.3/checksums.txt>).
- Edit `url64` in `tools/chocolateyinstall.ps1` to be the intended actual DDEV download version - edit the version where it appears and edit the GitHub org. For example, if the actual version of DDEV to be downloaded is `v1.21.3` then put that there.

```
make chocolatey VERSION=<tag>
export CHOCOLATEY_API_KEY=key33333
cd .gotmp/bin/windows_amd64/chocolatey
docker run --rm -v $PWD:/tmp/chocolatey -w /tmp/chocolatey linuturk/mono-choco push -s https://push.chocolatey.org/ --api-key "${CHOCOLATEY_API_KEY}"
```

## Manually Updating AUR Repository

The AUR repository normally updates with the release process, so nothing needs to be done.

However, you can manually publish the release to [the DDEV AUR repository](<https://aur.archlinux.org/packages/ddev-bin/>). The README.md in the AUR Git repository (`https://aur.archlinux.org/ddev-bin.git`) has instructions on how to update, including how to do it with a Docker container, so it doesn’t have to be done on an ArchLinux or Manjaro VM.

## Manually Signing the Windows Installer

> [!TIP]
>
> **This is done by the release process, but the manual process is documented here.**

This is done automatically by the release build on a dedicated Windows test runner (GitHub Actions runner) named `testbot-asus-win10pro`. You would need to do this process manually on that build machine or install the fob on another machine.

**After rebooting this machine, sometimes an automated reboot, the password for the security fob has to be re-entered or Windows signing will fail. We do this by opening up `tb-win11-06` using Chrome Remote Desktop (or manually physically opening it), opening Git Bash, and `cd ~/tmp && signtool sign gsudo.exe`. There happens to be a `gsudo.exe` there but it doesn’t matter what you sign—the idea is to pop up the GUI where you enter the password (which is in 1Password).**

### Basic Instructions

1. Install the suggested [Windows SDK](<https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/>). Only the signing component is required.
2. Add the path of the kit binaries to the Windows system PATH, `C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0/x64/`.
3. The keyfob and Safenet Authentication Client must be installed. The best documentation for the Safenet software is at [https://support.globalsign.com/digital-certificates/manage-safeNet-eToken/safenet-drivers](<https://support.globalsign.com/digital-certificates/manage-safeNet-eToken/safenet-drivers>). You must configure the advanced client settings to “Enable single logon” or it will require the password on each run.
4. After `make windows_amd64_install` the `ddev_windows_amd64_installer.exe` will be in `.ddev/bin/windows_amd64/ddev_windows_amd64_installer.exe` and you can sign it with `signtool sign ddev_windows_amd64_installer.exe`.
5. If you need to install the GitHub self-hosted Windows runner, do it with the instructions in project settings → Actions → Runners.
6. Currently the `actions/cache` runner does not work out of the box on Windows, so you have to install tar and zstd as described in [this issue](<https://github.com/actions/cache/issues/580#issuecomment-1165839728>).

> [!TIP]
>
> **We shouldn’t use this high-security keyfob approach to signing on the next go-around with the certs.**
>
> It’s way too difficult to manage, and the Safenet software is atrocious.

## APT and YUM/RPM Package Management

- The `nfpms` section of [.goreleaser.yml](<https://github.com/ddev/ddev/blob/main/.goreleaser.yml>) builds the actual `.deb`/`.rpm` packages; `furies` and `cloudsmiths` each push those same built packages to their respective repository.
- The primary location for APT/YUM packages is [Cloudsmith](<https://cloudsmith.com>), pushed via the `cloudsmiths` section of [.goreleaser.yml](<https://github.com/ddev/ddev/blob/main/.goreleaser.yml>), using the `CLOUDSMITH_ORG`/`CLOUDSMITH_REPO` variables and `DDEV_CLOUDSMITH_API_TOKEN` secret.
- We provided and uploaded a custom GPG signing key to the Cloudsmith repository (backed up as `DDEV_CLOUDSMITH_SIGNING_KEY` in 1Password). This is a one-time repository setting on Cloudsmith’s side, not part of the release process — Cloudsmith signs every pushed package with it automatically, and neither `.goreleaser.yml` nor the GitHub Actions workflow references it.
- Cloudsmith’s [custom domain](<https://help.cloudsmith.io/docs/custom-domains>) `packages.ddev.com` is live and serves the same content as `dl.cloudsmith.io/public/ddev/ddev/...` (drop the `ddev/ddev` organization/repository segment, keep `public`, e.g. `packages.ddev.com/public/deb/ubuntu`, `packages.ddev.com/public/rpm/any-distro/any-version`, `packages.ddev.com/public/gpg.key`).
- Linux `apt` and `yum`/`rpm` packages are also pushed in parallel to the historical Gemfury repository using the `furies` sections of the [.goreleaser.yml](<https://github.com/ddev/ddev/blob/main/.goreleaser.yml>) file. This will eventually be phased out.
- The Gemfury packages are served by [gemfury.com](<https://gemfury.com/>).
- The name of the organization in GemFury is `drud`, managed at `https://manage.fury.io/dashboard/drud`.
- [Randy Fay](<https://github.com/rfay>), [Matt Stein](<https://github.com/mattstein>), and [Simon Gillis](<https://github.com/gilbertsoft>) are authorized as owners on this dashboard.
- The `pkg.ddev.com` domain name has been used as a custom alias for the Gemfury package repositories; see `https://manage.fury.io/manage/drud/domains`. (Users do not see `drud` anywhere. Although we could have moved to a new organization for this, the existing repositories contain all the historical versions so it made sense to be less disruptive.)
- The `packages.ddev.com` and `pkg.ddev.com` `CNAME` records are managed in Cloudflare because `ddev.com` is managed there.
- The fury.io tokens are in DDEV’s shared 1Password account.

## Testing Release Creation

When significant changes are made to the `.goreleaser.yml` or related configuration, it’s important to be able to test without actually deploying to `ddev/ddev/releases` of course. We have two ways to test the configuration; we can run `goreleaser` manually for simpler tests, or run a full release on `ddev-test/ddev` where needed.

### Running `goreleaser` manually to create test packages and releases

This approach is great for seeing what artifacts get created, without deploying them.

Prerequisites:

- GoReleaser Pro must be installed, see [GoReleaser installation instructions](<https://goreleaser.com/install/>).
- `export GORELEASER_KEY=<key>` (not needed for simple snapshot)

You can test the GoReleaser configuration and package building locally without publishing:

First, build all artifacts, as GoReleaser uses them as `prebuilt`.

```
make linux_amd64 linux_arm64 darwin_amd64 darwin_arm64 windows_amd64 windows_arm64 wsl_amd64 wsl_arm64
```

Then, you can use `goreleaser` to check the configuration and build packages. You must have [GoReleaser Pro](<https://goreleaser.com/pro/>) installed, as DDEV uses it for configuration. If you don’t have it installed, see the [GoReleaser installation instructions](<https://goreleaser.com/install/>).

```
# Check configuration syntax
REPOSITORY_OWNER=ddev goreleaser check

# Build packages in snapshot mode (no publishing)
git tag <tagname> # Try to include context like PR number, for example v1.24.7-PR5824
REPOSITORY_OWNER=ddev goreleaser release --snapshot --clean
```

Built packages will appear in the `dist/` directory. You can examine package contents:

```
# List created packages
ls -la dist/*.{deb,rpm}

# Examine DEB package contents
dpkg-deb -c dist/ddev_*_linux_amd64.deb
dpkg-deb -c dist/ddev-wsl2_*_linux_amd64.deb  # WSL2 package

# Examine RPM package contents
rpm -qlp dist/ddev_*_linux_amd64.rpm
```

### Creating a test release on `ddev-test/ddev`

[ddev-test/ddev](<https://github.com/ddev-test/ddev>) is now set up for actual release testing. It has all or most of the environment variables set up already. It also acts against `ddev-test/homebrew-ddev` and `ddev-test/homebrew-ddev-edge` so you can test Homebrew publishing.

1. Create a branch on `ddev-test/ddev`.
2. Using the web UI, create a release using that branch as base. The release tag must start with `v1.`. Where possible, please use a release tag that includes context about the PR you are working against, like `v1.28.8-PR2022FixStuff`, and include in the release notes a link to the issue. The tag must be a valid Semantic Version tag, so don’t use underscores, etc.
3. Test out the resulting artifacts that get published or deployed.

# Remote Config

DDEV supports downloading a [`remote config`](<https://github.com/ddev/remote-config/blob/main/remote-config.jsonc>) from the [`ddev/remote-config`](<https://github.com/ddev/remote-config>) GitHub repository with messages that will be shown to the user as a “Tip of the Day”. This feature may be enhanced later with more information and filtering.

## Overview

DDEV’s remote configuration system provides a way to deliver dynamic content to users, including:

- **Ticker Messages**: Rotating “tip of the day” messages shown during various DDEV operations
- **Notifications**: Important announcements and warnings displayed to users
- **Sponsorship Data**: Information about DDEV’s financial sponsors (separate repository)

The system is designed to be:

- **Non-intrusive**: Users can disable or configure intervals
- **Version-aware**: Messages can target specific DDEV versions
- **Condition-based**: Messages can be shown based on user environment (Docker provider, OS, etc.)
- **Cached locally**: Configuration is cached to minimize network requests

## Data Types

### Remote Configuration

The main configuration includes:

- Update intervals for automatic refreshing
- Notification messages (info and warning types)
- Ticker messages with optional titles and conditions
- Version constraints for message targeting

### Sponsorship Information

Separate from the main config, DDEV downloads sponsorship data from a JSON endpoint including:

- Monthly and annual sponsor information
- Sponsor counts and income totals
- GitHub sponsorship details
- Update timestamps

## Storage Format

DDEV stores downloaded data locally using Go’s `gob` binary encoding format in the user’s [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>):

- `$HOME/.ddev/.remote-config`: Main remote configuration cache
- `$HOME/.ddev/.sponsorship-data`: Sponsorship information cache
- `$HOME/.ddev/.addon-data`: Add-on registry cache
- `$HOME/.ddev/.amplitude.cache`: Analytics event cache (if enabled)

## Debugging Tools

DDEV provides several debugging commands for working with remote configuration:

### View Cached Data

```
# Decode and view cached remote config
ddev utility gob-decode $HOME/.ddev/.remote-config

# Decode sponsorship data
ddev utility gob-decode $HOME/.ddev/.sponsorship-data

# Decode add-on registry cache
ddev utility gob-decode $HOME/.ddev/.addon-data

# Decode analytics cache
ddev utility gob-decode $HOME/.ddev/.amplitude.cache
```

### Download Fresh Data

```
# Download latest remote config (updates cache by default)
ddev utility remote-data --type=remote-config

# Download sponsorship data without updating cache
ddev utility remote-data --type=sponsorship-data --update-storage=false

# Download add-on registry data (updates cache by default)
ddev utility remote-data --type=addon-data
```

### View Available Conditions

```
# List all available message conditions
ddev utility message-conditions
```

## Messages

### Notifications

The defined messages are shown to the user every `interval` as long as not disabled (interval=-1). Supported message types are `infos` and `warnings` where `infos` are printed in a yellow box and `warnings` in a red box.

Messages will be shown as configured in the `remote-config` repository and the user cannot influence them.

### Infos

`infos` and `warnings` (yellow and red) can be specified like this:

```
{
  "messages": {
    "notifications": {
      "interval": 20,
      "infos": [
        {
          "message": "This is a message to users of DDEV before v1.22.7",
          "versions": "<=v1.22.6"
        }
      ],
      "warnings": []
    }
  }
}
```

### Ticker

Messages rotate, with one shown to the user every `interval` as long as it’s not disabled (interval=-1).

The user can disable the ticker or change the interval in the global config.

### Conditions and Versions

Every message can optionally include a condition and version constraint to limit the message to matching conditions and DDEV versions.

Each element in the `conditions` array may contain a condition listed by `ddev utility message-conditions`. It may be prefixed by a `!` to negate the condition. All conditions must be met in order for a message to be displayed. Unknown conditions are always met.

The field `versions` may contain a version constraint which must be met by the current version of DDEV. More information about the supported constraints can be found in the [Masterminds SemVer repository](<https://github.com/Masterminds/semver#readme>).

## Configuration

### Global Configuration

Users can configure remote config behavior in `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)):

```
remote_config:
  update_interval: 24  # Hours between updates
  remote_config_url: "https://raw.githubusercontent.com/ddev/remote-config/main/remote-config.jsonc"
  sponsorship_data_url: "https://ddev.com/s/sponsorship-data.json"
  addon_data_url: "https://addons.ddev.com/addons.json"
```

### Per-User Control

Users can disable features entirely:

```
# Disable ticker messages (set in messages section)
messages:
  ticker_interval: -1

# Disable notifications and remote config updates
remote_config:
  update_interval: -1
```

## Architecture

### File Structure

The remote configuration system consists of several Go packages:

- `pkg/config/remoteconfig/`: Main package with interfaces and logic
- `pkg/config/remoteconfig/types/`: Public type definitions
- `pkg/config/remoteconfig/storage/`: File storage implementations
- `pkg/config/remoteconfig/downloader/`: JSONC download functionality

### Key Components

- **RemoteConfig Interface**: Main interface for displaying messages
- **Storage Interfaces**: Abstract file storage
- **Message Processing**: Condition and version constraint evaluation
- **State Management**: Tracking update times and message rotations

## Testing and Development

### Testing Remote Config Changes

To test changes to remote configuration:

1. **Change the upstream configuration** in [ddev/remote-config](<https://github.com/ddev/remote-config>) or use a fork/branch.
2. **Set up test configuration** in `$HOME/.ddev/global_config.yaml` (see [global configuration directory](<https://ddev.github.io/ddev/en/stable/users/usage/architecture/#global-files>)):

```
remote_config:
  update_interval: 1  # Update every hour for testing
  remote_config_url: "https://raw.githubusercontent.com/your-username/remote-config/your-test-branch/remote-config.jsonc"
  sponsorship_data_url: "https://ddev.com/s/sponsorship-data.json"  # Or your test URL
  addon_data_url: "https://addons.ddev.com/addons.json"
```

1. **Clear or edit cached data**:

```
rm -f $HOME/.ddev/.state.yaml $HOME/.ddev/.remote-config
```

1. **Test with verbose output**:

```
DDEV_VERBOSE=true ddev start <project>
```

### Testing with Debug Commands

Use the debug commands to validate your configuration:

```
# Download and validate remote config (tests your configured URL from global config)
ddev utility remote-data --type=remote-config --update-storage=false

# View the current cached config
ddev utility gob-decode $HOME/.ddev/.remote-config

# Verify message conditions work
ddev utility message-conditions
```

# Secret Management

Most secrets used in our build process are managed via 1Password. The technique is documented in [developer.1password.com](<https://developer.1password.com/docs/ci-cd/github-actions/>).

## Pull and Push Secrets

Secrets for the TestPlatformPull, TestAcquiaPull, and similar tests are in the `test-secrets` vault in the DDEV 1Password instance. They can be rotated and otherwise managed there.

The `test-secrets` vault allows access to the service account [`tests`](<https://team-ddev.1password.com/developer-tools/infrastructure-secrets/serviceaccount/76URGQSBMVEUHPEWVHQRFJ4N3Q>) whose auth token is in “1Password Service Account Auth Token: Tests”

# Working on the Docs

This page is about working with the DDEV documentation. See the [Writing Style Guide](<https://ddev.github.io/ddev/en/stable/developers/writing-style-guide/index.md>) for stylistic guidance.

## Fix Docs Using Web Browser

The documentation is built and checked automatically with various [GitHub Actions workflows](<https://github.com/ddev/ddev/actions>). While it may help to [check your work locally](<#fork-or-clone-the-ddev-repository>) for more involved PRs, you can more quickly make suggestions using GitHub in a browser:

1. Click the pencil in the upper right. That will take you to the right page on GitHub.
2. Click the pencil button on GitHub and follow the instructions to create your change.
3. Save your changes and follow the prompts to create a PR.
4. In the checks on your PR, click the “details” link by `docs/readthedocs.org:ddev` to browse the docs build created by your PR.
5. Once the PR has run its checks, you’ll see an item labeled `docs/readthedocs.org:ddev`. Click “Details” to review a docs build that includes your changes: ![Documentation preview build link](<https://ddev.github.io/ddev/en/stable/images/docs-build-link.png>)
6. Take a look at the [“Check docs” action](<https://github.com/ddev/ddev/actions/workflows/docs-check.yml>) to make sure there were no linting or spelling errors.

## Fork or Clone the DDEV Repository

To start making changes you’ll need a local copy of the DDEV documentation, so [fork the DDEV repository](<https://github.com/ddev/ddev/fork>) which includes the documentation.

After forking the repository, you can clone it to your local machine.

## Make Changes

Now that you’ve got a local copy, you can make your changes.

| Action | Path |
| --- | --- |
| Documentation | `./docs/content/users/*`<br>`./docs/content/developers/*` |
| Zensical configuration | `./mkdocs.yml` |
| Front end | `./docs/content/assets/extra.css`<br>`./docs/content/assets/extra.js` |

## Development Tools Installation

For documentation development and testing, install the required tools once using:

```
scripts/install-dev-tools.sh
```

This installs `zensical`, `pyspelling`, `markdownlint`, `textlint`, `linkspector`, and `aspell` to `$HOME/.ddev-dev-tools/`.

The project’s `.envrc` automatically adds these tools to your PATH when you’re in the DDEV directory. If you want the tools available globally, add this to your shell profile (`.bashrc`, `.bash_profile`, or `.zshrc`):

```
export PATH="$HOME/.ddev-dev-tools/python/bin:$HOME/.ddev-dev-tools/node/bin:$PATH"
```

Alternatively, you can use the project-level `.envrc` installation method:

1. Install `direnv` with `brew install direnv` or `sudo apt-get update && sudo apt-get install -y direnv` or whatever technique is appropriate for your system.
2. Hook `direnv` into your shell, see [docs](<https://direnv.net/docs/hook.html>).
3. Create global configuration for `direnv` in `~/.config/direnv/direnv.toml` allowing it to be loaded without the `direnv allow` command, see [docs](<https://github.com/direnv/direnv/blob/master/man/direnv.toml.1.md>), adjusting for your project path:

```
[global]
strict_env = true
[whitelist]
exact = ["~/workspace/ddev/.envrc"]
```

**Recommended**: Use the unified installation script for better performance and fewer per-project installations.

## Preview Changes

Preview your changes locally by running `make zensical-serve`.

This will launch a web server on port 8000 and automatically refresh pages as they’re edited.

## Check Markdown for Errors

Run `make markdownlint` before you publish changes to quickly check your files for errors or inconsistencies.

> [!WARNING]
>
> **`markdownlint-cli` required!**
>
> The `make markdownlint` command requires you to have `markdownlint-cli` installed, which you can do by executing `npm install -g markdownlint-cli` or by using the `direnv` method above.

## Check for Spelling Errors

Run `make pyspelling` to check for spelling errors. Output will be brief if all goes well:

```
➜  make pyspelling
pyspelling:
Spelling check passed :)
```

If you’ve added a correctly-spelled word that gets flagged, like “Symfony” for example, you’ll need to add it to `.spellcheckwordlist.txt` in the [root of DDEV’s repository](<https://github.com/ddev/ddev/blob/main/.spellcheckwordlist.txt>).

> [!WARNING]
>
> **`pyspelling` and `aspell` required!**
>
> It’s probably best to install packages locally before attempting to run `make pyspelling`:
>
> ```
> sudo -H pip3 install pyspelling pymdown-extensions
> sudo apt-get install aspell
> ```

## Check for Link Errors

Check external links using `make linkspector`.

## Publish Changes

If all looks good, it’s time to commit your changes and make a pull request back into the official DDEV repository.

When you make a pull request, several tasks and test actions will be run. One of those is a task named `docs/readthedocs.org:ddev`, which builds a version of the docs containing all the changes from your pull request. You can use that to confirm the final result is exactly what you’d expect.

## Updating Stable Docs Without a Release

[ReadTheDocs](<https://readthedocs.org>) serves `/stable/` from a dedicated `stable` branch (not from the latest tag directly). On every non-prerelease GitHub release, the [`docs-stable` workflow](<https://github.com/ddev/ddev/actions/workflows/docs-stable.yml>) automatically resets that branch to the release tag.

To push a doc fix to the stable docs without cutting a new release, commit directly to the `stable` branch:

```
git fetch upstream
git checkout -b stable upstream/stable
# make your doc changes
git add docs/
git commit -m "docs: fix typo in install guide [skip ci]"
git push upstream stable
```

> [!NOTE]
>
> The `[skip ci]` in the commit message prevents GitHub Actions and Buildkite from running tests on the `stable` branch. ReadTheDocs will still rebuild `/stable/` automatically on the push.

# Writing Style Guide

This page formalizes the writing conventions we aspire to use in the documentation.  
It’s a living statement of intent and a reference for all contributors.

## Voice and Tone

In the spirit of the [Code of Conduct](<https://ddev.github.io/ddev/en/stable/users/code-of-conduct/index.md>), we want to be clear and encouraging for everyone that bothers to read DDEV’s documentation, rewarding the time and attention they choose to give to it.

### Beginner-Friendly, Expert-Compatible

Write so a DDEV beginner can follow your guidance and a DDEV veteran could use the same content as a reference.

| Write This 👍 | Not This ❌ |
| --- | --- |
| You can run `ddev restart` to apply changes you’ve made to your global `$HOME/.ddev/global_config.yaml` or per-project `.ddev/config.yaml`. | Just `ddev restart` to apply YAML config changes. |

### Be Efficient and Direct

Brevity makes for good documentation!

Few read the docs from start to finish like a book, and explanation can be a barrier to learning. Get to the point, avoiding parentheticals and mid-sentence notes that interrupt the main flow.

Omit extraneous explanation or decorative language that doesn’t help the reader. Instructions don’t need to include “please”. Provide some context for anchor links without overloading them to hinder flow.

| Write This 👍 | Not This ❌ |
| --- | --- |
| Run `ddev start` and launch the site in a browser. | Please run `ddev start`, then launch the site in a browser. |
| Learn more on the [Extending](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/index.md>) page. | (You can also learn more about this and related topics in [Providing Custom Environment Variables to a Container](<https://ddev.github.io/ddev/en/stable/users/extend/customization-extendibility/index.md>).) |

### Avoid “Just” and “Easy”

Try not to use language that [may talk down to the reader](<https://justsimply.dev/>). You may intend for “it’s easy” to be reassuring, but it’s a subjective judgment that can convince someone struggling that they’re doing it wrong. Things could instead be “straightforward” if they’re without nuance, “simple” if they don’t involve complex actions or concepts, or “quick” if they involve one or two steps that’d be fast even on someone’s worst day with the slowest-imaginable machine.

Similarly, “just do X” suggests that “X” should be easy or obvious. Most of the time “just” can be omitted and everyone wins.

If you’d like to reassure the reader something is easy, illustrate it with a demonstration and let them draw their own conclusion!

| Write This 👍 | Not This ❌ |
| --- | --- |
| Change your project’s PHP version by either editing `.ddev/config.yaml` to set `php_version: "8.2"`, or by running `ddev config --php-version=8.2`, followed by running `ddev restart`. | It’s easy to change your project’s PHP version! Just edit your project’s `.ddev/config.yaml` to set `php_version: "8.2"`, or run `ddev config --php-version=8.2`, followed by running `ddev restart`. |

## Writing Style

DDEV’s documentation should be consistent throughout, which benefits both the reader taking in information and the contributor looking for examples to follow.

> [!TIP]
>
> **Read It Aloud**
>
> If you get tripped up speaking your words out loud, someone else will get tripped up reading them, too.

### Use Correct Capitalization and Punctuation

Write with appropriate grammar and style for U.S. English, including capitalization and punctuation. Variations in spelling and writing style make the documentation harder to read, and we want to be respectful of the reader’s time and attention.

| Write This 👍 | Not This ❌ |
| --- | --- |
| Let’s not capitalize random words for emphasis. | Let’s not Capitalize random Words for emphasis. |
| That organization uses a lovely American color. | That organisation uses a lovely American colour. |
| We can use “curly quotes” now that we’re post-typewriter. | We can use “curly quotes” now that we’re post-typewriter. |

### “Run” Commands

We “run” commands. We don’t “do” them, and the command itself is not a verb. Whenever possible, reinforce that a given thing in backticks is intended as a console command by using the word “run” before it.

| Write This 👍 | Not This ❌ |
| --- | --- |
| Run `ddev config` to set up your project. | Do `ddev config` to set up your project.<br>You can `ddev config` to set up your project. |
| If you get stuck, run `ddev restart`. | If you get stuck, just `ddev restart`. |

### Use Active Third Person

Avoid impersonal language featuring unknown individuals or shadowy organizations.  
“It is recommended,” for example, could be a warmer “we recommend” or “Laravel users recommend”.

Write on behalf of the community and not yourself—use “we” and not “I”.

| Write This 👍 | Not This ❌ |
| --- | --- |
| We recommend Colima for the best performance. | It is recommended for performance that you use Colima. |
| Some prefer Redis for runtime caches. | I like using Redis for runtime caches. |

### Write Once and Link

Try to keep from repeating yourself in the documentation. Instead, write carefully and link to that well-crafted specimen, whether it’s across the page or off to another section. This has two benefits:

1. Easier maintenance with less chance of redundant information becoming stale.
2. Subtle reinforcement of documentation structure that helps the reader learn where to find answers, rather than answering the same thing in different places.

### Mind Your Context

It’s easy to get lost in documentation; don’t assume the reader is always following your words. Take care to bring the reader with you, especially if there are steps that involve different applications or distinct areas of concern.

| Write This 👍 | Not This ❌ |
| --- | --- |
| 1\. In Docker Desktop, go to *Resources* → *Advanced* and set “Memory” to 6GB.<br>2\. From your terminal, run `ddev restart`.<br>3\. In your text editor, open `.ddev/config.yaml` and set `php_version: "8.1"`. | 1\. Go to *Resources* → *Advanced* and set “Memory” to 6GB.<br>2\. Run `ddev restart`.<br>3\. Set `php_version: "8.1"`. |
| Once you’ve [installed a Docker provider](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>), you’re ready to install DDEV! | Docker or an alternative is required before anything will work with DDEV. This is pretty easy on most environments; see the [Docker Installation](<https://ddev.github.io/ddev/en/stable/users/install/docker-installation/index.md>) page to help sort out the details. |

### Avoid Starting with Asides

The beginning of a page or section should introduce what the rest of the content is about. Try to avoid starting with asides or reminders that get in the way of this initial statement of purpose.

Never tell the reader to “remember” something they may not have been introduced to yet.

### Use Tips

Avoid using “Note:” to signal an aside. Most sentences work fine without it, and for discreet notes we have `!!!note`, `!!!tip`, and `!!!warning` conventions.

Use one of these callouts for text that can stand on its own and be skipped, or for an urgent message that needs greater visual emphasis.

Summarize the callout’s contents with a succinct heading whenever you can, so anyone skimming can know whether to read the callout’s supporting text.

```
!!!note "This is a note."
    Use it for extraneous asides.

!!!tip "This is a tip."
    Use it for helpful asides.

!!!warning "This is a warning."
    Use it for asides that should have urgent emphasis.

!!!note
    This is a note without a heading, which should only be used with the author isn’t clever enough to come up with a succinct one. (The “Note” is added automatically.)
```

> [!NOTE]
>
> **This is a note.**
>
> Use it for extraneous asides.

> [!TIP]
>
> **This is a tip.**
>
> Use it for helpful asides.

> [!WARNING]
>
> **This is a warning.**
>
> Use it for asides that should have urgent emphasis.

> [!NOTE]
>
> This is a note without a heading, which should only be used with the author isn’t clever enough to come up with a succinct one. (The “Note” is automatically added.)

**Note:** we want to avoid callouts like this sentence, that should either be tips or flow naturally with their surrounding text. If any documentation *shouldn’t* be noted by the reader, get rid of it.

### Use Correct Proper Nouns

#### DDEV != `ddev`

DDEV is a product and `ddev` is a binary or console command. DDEV should always be uppercase, and `ddev` should always be in backticks. DDEV-Local and DDEV-Live are former product incarnations that shouldn’t be found in modern documentation.

| Write This 👍 | Not This ❌ |
| --- | --- |
| DDEV is wonderful! | Ddev is wonderful!<br>ddev is wonderful!<br>DDEV-Local is wonderful! |
| Run `ddev`. | Run ddev.<br>Run DDEV. |

#### Products, Organizations, and Protocols

When in doubt, honor whatever name a product or organization uses in its official materials.  
Use backticks to differentiate between a product and command, like DDEV vs. `ddev`.

| Write This 👍 | Not This ❌ |
| --- | --- |
| AMD64, ARM64, and Apple Silicon | amd64, arm64, M1 Macs |
| Apache | apache |
| Bash or `bash` | bash |
| Blackfire | blackfire, Blackfire.io |
| Chocolatey | chocolatey |
| Colima or `colima` | colima |
| Composer or `composer` | composer |
| Docker or `docker` | docker |
| Drush or `drush` | drush |
| Git | git |
| Git Bash | git bash |
| GitHub or `github` | Github |
| GoLand | Goland |
| Google | google |
| Homebrew | homebrew |
| HTTP, HTTPS, SSH, `http`, `https`, `ssh` | http, https, ssh |
| IPv4, IPv6 | IPV4, IPV6, ipv4, ipv6 |
| Linux | linux |
| nginx or `nginx` | Nginx, NGINX |
| Node.js or `node` | Node, node |
| Pantheon | pantheon, Pantheon.io |
| PHP or `php` | php |
| PhpStorm | PHPStorm, PHPstorm, Phpstorm |
| PHPUnit or `phpunit` | phpunit, PHPunit |
| PostgreSQL | Postgres |
| Terminus | terminus |
| Windows | windows |
| Xdebug | XDebug, xDebug |

### Quote Copied Text

If you’re quoting a human being or a message lifted verbatim from some other source (outside a fenced code block), make sure it ends up in a `<blockquote>` element:

```
> Error: your quote style should not always be in a fenced block.
```

> Error: your quote style should not always be in a fenced block.

### Other Recommendations

One-off tips that don’t fit nicely into any of the sections above:

- Pluralize “CMS” as “CMSes”, not “CMSs”.
- Use all-caps references for file *types* like JSON, YAML and CSS.
- Wrap file *extensions* in backticks like `.json`, `.yaml`, and `.css`.
- Wrap references to files, directories, images and commands in backticks.
- Use Title Case for headings wherever it makes sense.
- Link to related services and topics where convenient—usually first use on a given page.
- Use `<kbd>` elements for representing literal keystrokes.
- Use sequential numbers for numbered lists in the source Markdown, regardless of how they’re eventually rendered.
- Try to maintain parallel format for list items.

| Write This 👍 | Not This ❌ |
| --- | --- |
| web server | webserver |
| add-on | addon |
| JSON, YAML, CSS | json, Yaml, css |
| `.json`, `.yaml`, `.css`, `$HOME/.ddev` | .json, .yaml, .css, $HOME/.ddev |
| <kbd>CTRL</kbd> + <kbd>C</kbd> | control-c, control + c, ctrl+c |
| *Menu Item* → *Another Menu Item* → *Setting* | Menu Item\>Another Menu Item\>Setting<br>Menu Item -\> Another Menu Item -\> Setting |
| several CMSes | several CMSs, several CMS’s |
| How to Reticulate Splines | How to reticulate splines |
| 1\. Run `command`.<br>2\. Edit file.<br>3\. Restart computer. | 1\. `command`<br>2\. Edit file.<br>3\. Additionally, restart your computer. |