DDEV

Published 10 months ago.
Last updated September 27th, 2024

DDEV is an open source tool for launching local web development environments in minutes. It supports PHP, Node.js, and Python. It is built on top of Docker, but you do not need to know how to use Docker to run DDEV.

Installation

Install Docker

The first step is to install Docker on your system. Installing Docker Desktop is the best solution as it installs the Docker command-line client, but the Desktop UI offers a nice interface into the Dcoker containers, logs, shells and other tools you would otherwise need to type lenghty docker commands to access.

• Download and install Docker Desktop.
• Start-up Docker Desktop and just leave it running.

Install DDEV

• DDEV Docs

Install ddev with Homebrew:

brew install ddev/ddev/ddev

After Homebrew installs DDEV, run mkcert (which came packaged with DDEV) to install a root CA on your system. The root CA allows your local dev environments to run under secure HTTPS.

mkcert -install

Using DDEV

Start a new Project

• Put your project code into a directory on your system. Navigate to that directory and run:

ddev config

Follow the instructions and answer all the questions.

Project Configurations

DDEV configuration is stored in YAML files that come in two flavors:

• Project: .ddev/config.yaml settings, with optional environmental override variants.
• Global: $HOME/.ddev/global_config.yaml settings that can apply to all projects.

You will probably not need to edit the global YAML file. Project-specifi settings should be managed in the projects local DDEV YAML file .ddev/config.yaml.

After editing the YAML file you will need to run ddev restart for the new settings to take effects.

Apache vs NginX

To change a project from the default Nginx to use an Apache server, open the projects .ddev/config.yaml file and change the webserver_type field to apache-fpm:

webserver_type: apache-fpm

Apache Rewite Rules

To persist Apache changes, put all module settings in a .htaccess file placed in the the web root directory of the project, i.e htdocs/.htaccess:

Example .htaccess file with mod_rewrite settings:

<IfModule mod_rewrite.c>

  Options -Indexes +FollowSymLinks
  Require all granted
  RewriteEngine On

  # Enforce a trailing slash on requests that are not for files.
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteRule ^(.*[^/])$ /$1/ [L,R]

  # If a request does not match a real file or directory, route it to `/index.php`.
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule . /index.php [L]

</IfModule>

PHP Version

To change the version of PHP used in the project, open the projects .ddev/config.yaml file and change the php_version field to the PHP version you need 7.1:

php_version: 7.1

Run a Project

ddev start

Stop a Running Project

ddev stop

Restart a Running Project

ddev restart

Turn DDEV Off Completely

ddev poweroff

Web Host

Web Host Shell

SSH into the current project’s web host container:

ddev ssh

SSH into the docroot of the current project’s web host container:

ddev ssh -d /var/www/html

Databases

Database connections from within a DDEV local web app (running inside the local container) should use these credentials:

{
    "host":       "db",
    "username":   "root",
    "password":   "root",
}

Database connections from outside the container need to use use these credentials:

{
    "host":       "127.0.0.1",
    "username":   "root",
    "password":   "root",
    "port":       "62005",
}

NOTE: The DB port number will change every time the project is restarted. Run ddev describe to get the current DB port number.

Database Shell

The esiest way to access the DB shell is through the Docker Desktop app, but you can also use the command line.

On the command line you can ssh into the ddev database container with:

ddev ssh -s db

Login to MySQL just by typing mysql, no user or password needed.

mysql

The SQL config dir:

cd /etc/mysql/conf.d/

Capture Email

DDEV comes with MailPit already built-in, so you can test your email locally with ease. Mailpit is a mail catcher that’s configured to capture and display emails sent by PHP in the development environment.

Launch the MailPit web interface with:

ddev mailpit

The try sending an email from your app and then look in MailPit to check if it works.

Mailpit will not intercept emails if your application is configured to use SMTP or a third-party ESP integration.
Make sure you don't have any SMTP transport settings configured in your config.php.

Logs

ddev logs can be used to see combined log files for the running instance. There are in fact a couple of logs in the web container that don't get spit out to that, so it may be worth ddev ssh and review the logs in /var/logs and /var/logs/nginx, where you can tail them if necessary.

PHP logs:

ddev logs -f

MySQL logs:

ddev logs -s db -f

Useful DDEV commands:

launch

Run ddev launch to open the project in your default browser.

ddev launch

sequelace

Launch SequelAce and uatomatically connect to the local DDEV DB:

ddev sequelace

NOTE: You must maually install SequelAce on your system before you can run this command.

mailpit

Launch MailPit to read emails sent by the project.

ddev mailpit

describe

Run ddev describe to get a readout of your projects current settings:

┌───────────────────────────────────────────────────────────────────────────────────────┐
│ Project: portal ~/Projects/app_portal https://portal.ddev.site                        │
│ Docker platform: docker-desktop                                                       │
│ Router: traefik                                                                       │
├──────────┬──────┬────────────────────────────────────────────────┬────────────────────┤
│ SERVICE  │ STAT │ URL/PORT                                       │ INFO               │
├──────────┼──────┼────────────────────────────────────────────────┼────────────────────┤
│ web      │ OK   │ https://portal.ddev.site                       │ php PHP7.1         │
│          │      │ InDocker: web:443,80,8025                      │ apache-fpm         │
│          │      │ Host: 127.0.0.1:62006,62007                    │ docroot:'htdocs'   │
│          │      │                                                │ Perf mode: mutagen │
│          │      │                                                │ NodeJS:18          │
├──────────┼──────┼────────────────────────────────────────────────┼────────────────────┤
│ db       │ OK   │ InDocker: db:3306                              │ mariadb:10.4       │
│          │      │ Host: 127.0.0.1:62005                          │ User/Pass: 'db/db' │
│          │      │                                                │ or 'root/root'     │
├──────────┼──────┼────────────────────────────────────────────────┼────────────────────┤
│ Mailpit  │      │ Mailpit: https://portal.ddev.site:8026         │                    │
│          │      │ `ddev mailpit`                                 │                    │
├──────────┼──────┼────────────────────────────────────────────────┼────────────────────┤
│ All URLs │      │ https://portal.ddev.site,                      │                    │
│          │      │ https://127.0.0.1:62006,                       │                    │
│          │      │ http://portal.ddev.site,                       │                    │
│          │      │ http://127.0.0.1:62007                         │                    │
└──────────┴──────┴────────────────────────────────────────────────┴────────────────────┘