DDEV has become a popular tool for local web development, offering a streamlined approach to managing Docker-based environments. However, setting up and managing DDEV projects, particularly with the latest versions of Docker Desktop, can present challenges. This article guides you through resolving key issues, setting up Drupal, and managing multiple projects effectively.
Overcoming common DDEV setup issues
Problem: Port conflicts and router errors
One of the most common errors developers encounter when starting a DDEV project is related to port conflicts, particularly when DDEV attempts to bind ports 80 (HTTP) and 443 (HTTPS). Modern versions of Docker Desktop, especially on macOS with Apple Silicon (M1/M2), have shifted away from the older vmnetd networking system, leading to compatibility issues.
Symptoms
- Errors referencing /var/run/com.docker.vmnetd.sock missing.
- Messages indicating ports 80 or 443 are unavailable.
Solution
To resolve this issue, the following changes can be made to DDEV's global configuration file (~/.ddev/global_config.yaml):
router_http_port: "8080"
router_https_port: "8443"
omit_containers: []
router_bind_all_interfaces: trueWhat these changes do:
- Reassigns HTTP and HTTPS ports to 8080 and 8443 to avoid conflicts.
- Disables the default ddev-router container, which relies on problematic bindings.
- Allows DDEV to bind to all network interfaces for broader access flexibility.
Restart the environment after changes:
ddev poweroff
ddev startThese adjustments make DDEV more compatible with modern Docker setups, ensuring reliable performance without dependency on deprecated networking mechanisms.
Setting up Drupal in a DDEV environment
Step 1: Install DDEV and Docker Desktop
Ensure Docker Desktop is installed and running on your system. Install DDEV via Homebrew (macOS):
brew install drud/ddev/ddev
Step 2: Create a Drupal project
Navigate to your projects directory and create a new Drupal project using Composer:
composer create-project drupal/recommended-project my-drupal-site
cd my-drupal-site
Step 3: Configure DDEV for Drupal
Initialise DDEV for the project:
ddev config --project-type=drupal --docroot=web --php-version=8.3
Step 4: Start the project
Launch the DDEV environment:
ddev start
Step 5: Install Drupal
Access the site URL displayed by DDEV and follow the Drupal installation wizard. Provide the database credentials:
Database name: db
Username: db
Password: db
Host: dbOtherwise you can use Drush to install Drupal:
ddev drush site:install standard --account-name=admin --account-pass=admin
Managing multiple projects with DDEV
DDEV allows you to run multiple projects simultaneously, each with isolated configurations.
1. Create additional projects:
mkdir project-two
cd project-two
composer create-project drupal/recommended-projectConfigure DDEV for the new project:
ddev config --project-type=drupal --docroot=web --php-version=8.3Start the environment:
ddev start
2. Access multiple projects
By default, each project receives a unique local domain based on its folder name, e.g.,
- http://project-one.ddev.site
- http://project-two.ddev.site
Use the prompt ddev describe
┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Project: abc-10-dev ~/Sites/abc-10-dev http://abc-10-dev.ddev.site:8080 │
│ Docker platform: docker-desktop │
│ Router: traefik │
├──────────────┬──────┬──────────────────────────────────────────────────────────┬────────────────────┤
│ SERVICE │ STAT │ URL/PORT │ INFO │
├──────────────┼──────┼──────────────────────────────────────────────────────────┼────────────────────┤
│ web │ OK │ http://abc-10-dev.ddev.site:8080 │ drupal11 PHP8.3 │
│ │ │ InDocker -> Host: │ nginx-fpm │
│ │ │ - web:80 -> 127.0.0.1:50430 │ docroot:'web' │
│ │ │ - web:443 -> 127.0.0.1:50429 │ Perf mode: mutagen │
│ │ │ - web:8025 │ NodeJS:22 │
├──────────────┼──────┼──────────────────────────────────────────────────────────┼────────────────────┤
│ db │ OK │ InDocker -> Host: │ mariadb:10.11 │
│ │ │ - db:3306 -> 127.0.0.1:50431 │ User/Pass: 'db/db' │
│ │ │ │ or 'root/root' │
├──────────────┼──────┼──────────────────────────────────────────────────────────┼────────────────────┤
│ Mailpit │ │ Mailpit: http://abc-10-dev.ddev.site:8025 │ │
│ │ │ Launch: ddev mailpit │ │
├──────────────┼──────┼──────────────────────────────────────────────────────────┼────────────────────┤
│ Project URLs │ │ http://abc-10-dev.ddev.site:8080, │ │
│ │ │ http://127.0.0.1:50430 │ │
├──────────────┼──────┼──────────────────────────────────────────────────────────┼────────────────────┤
│ Network │ │ router-bind-all-interfaces ENABLED │ │
└──────────────┴──────┴──────────────────────────────────────────────────────────┴────────────────────┘
3. Custom domains for better organisation
To assign a custom domain:
additional_fqdns:
- project-one.local
- project-two.localRestart the projects:
ddev restart
Essential DDEV commands for maintenance
Starting and stopping projects:
ddev start
ddev stopViewing project details:
ddev describeClearing caches and rebuilding containers:
ddev restartManaging databases with phpMyAdmin:
ddev launch phpmyadminAccessing SSH in containers:
ddev sshExporting databases:
ddev export-db --file=db.sql.gz
The wrap
DDEV simplifies local web development but occasionally requires adjustments to work smoothly with modern Docker configurations. By updating ports, disabling problematic routers, and leveraging flexible project configurations, you can avoid common errors and support multiple active projects. Whether you are developing a single Drupal site or managing multiple projects, DDEV provides the scalability and flexibility needed for local development environments.