DDEV, a powerful platform to simplify the local development environment

11 June 2021 - by Olivier Brunau
Olivier Brunau

What is DDEV ?

DDEV is an open source PHP development tool based on docker.

It allows, in a few minutes, to set up an environment adapted to each project with all the necessary tools to be efficient without having to worry about managing Docker containers.

What are the pre-requisites?

The only prerequisite is the installation of Docker > 18.06 and Docker-compose > 1.21.0.

For MacOS and Linux, the recommended installation is with Homebrew/Linuxbrew.

For Windows 10, it is best to start by installing WSL2 (Windows subsystem for Linux).

All installation steps can be found in the DDEV documentation.

For which projects should it be used?

For the moment, DDEV is dedicated to PHP development and offers configurations adapted to the main CMS on the market: Backdrop, Drupal 6, Drupal 7, Drupal 8, Drupal 9, Laravel, Magento, Magento 2, PHP, Shopware 6, TYPO3, WordPress.

The docker images used are maintained by the open source community and updated regularly. They contain current development tools (Composer, Node.js, Xdebug, Blackfire).

Configuration of a new project

First of all, you need to create a folder for the new project, put yourself in it and run the ddev config command:

$ mkdir new-project
$ cd new-project/
$ ddev config
Creating a new ddev project config in the current directory (/home/olivier/sites/new-project)
Once completed, your configuration will be written to /home/olivier/sites/new-project/.ddev/config.yaml

Project name (new-project):

DDEV asks for the project name, docroot and project type. For this example, I have created a Drupal 9 project.

Docroot Location (current directory): web
Warning: the provided docroot at /home/olivier/sites/new-project/web does not currently exist.
Create docroot at /home/olivier/sites/new-project/web? [Y/n] (yes):
Created docroot at /home/olivier/sites/new-project/web.
Found a php codebase at /home/olivier/sites/new-project/web.
Project Type [backdrop, drupal6, drupal7, drupal8, drupal9, laravel, magento, magento2, php, shopware6, typo3, wordpress] (php): drupal9

Depending on the type of project chosen, DDEV can create additional files.

Ensuring write permissions for new-project
No settings.php file exists, creating one
Existing settings.php file includes settings.ddev.php
Configuration complete. You may now run 'ddev start'.

When the ddev start command is issued, DDEV creates the necessary Docker containers and automatically manages the permissions.

$ ddev start
Starting new-project...
Pushed mkcert rootca certs to ddev-global-cache/mkcert
Running   Command=ip address show dev docker0
Building db
Building web
Creating ddev-new-project-db ...
Creating ddev-new-project-db ... done
Creating ddev-new-project-web ...
Creating ddev-new-project-dba ...
Creating ddev-new-project-web ... done
Creating ddev-new-project-dba ... done
Creating ddev-router ...
Creating ddev-router ... done
Ensuring write permissions for new-project
Existing settings.php file includes settings.ddev.php
Ensuring write permissions for new-project
Successfully started new-project
Project can be reached at https://new-project.ddev.site

The next step is to install Drupal using Composer. The command is run in the container through DDEV.

$ ddev composer create "drupal/recommended-project"

It is also necessary to install Drush.

$ ddev composer require drush/drush

After that, you can finish the installation by accessing the site from a browser with the ddev launch command. The site launches in https with a domain name dedicated to the project: https://new-project.ddev.site/.

$ ddev launch

A flexible tool

Configuring a project is very easy using a config.yml file, no need to touch the docker-compose files.

This configuration file is located in the folder created at the root of the .ddev project.

name: new-project
type: drupal9
docroot: web
php_version: "7.4"
webserver_type: nginx-fpm
router_http_port: "80"
router_https_port: "443"
xdebug_enabled: false
additional_hostnames: []
additional_fqdns: []
mariadb_version: "10.3"
mysql_version: ""
use_dns_when_possible: true
composer_version: ""
web_environment: []

We can see here that it is very easy to change the versions of PHP, Composer, MariaDB, the type of web server (Apache or Nginx) or the ports used to access the site in http or https.

Once the file has been modified, simply issue the ddev start command to refresh the containers.

An extensible tool

To add a service such as Solr or ElasticSearch, simply add the corresponding docker-compose file offered by DDEV to the .ddev folder. Additional services proposed by the community are available here https://github.com/drud/ddev-contrib.

When the project is restarted, the additional service will be automatically integrated.

A customizable tool

DDEV offers many commands by default.

Create and maintain a local web development environment.
Docs: https://ddev.readthedocs.io
Support: https://ddev.readthedocs.io/en/stable/#support

  ddev [command]

Available Commands:
  auth             A collection of authentication commands
  blackfire        Enable or disable blackfire.io profiling (global shell web container command)
  composer         Executes a composer command within the web container
  config           Create or modify a ddev project configuration in the current directory
  debug            A collection of debugging commands
  delete           Remove all project information (including database) for an existing project
  describe         Get a detailed description of a running ddev project.
  drush            Run drush CLI inside the web container (global shell web container command)
  exec             Execute a shell command in the container for a service. Uses the web service by default.
  export-db        Dump a database to a file or to stdout
  help             Help about any command
  hostname         Manage your hostfile entries.
  import-db        Import a sql file into the project.
  import-files     Pull the uploaded files directory of an existing project to the default public upload directory of your project.
  launch           Launch a browser with the current site (shell host container command)
  list             List projects
  logs             Get the logs from your running services.
  mysql            run mysql client in db container (shell db container command)
  pause            uses 'docker stop' to pause/stop the containers belonging to a project.
  poweroff         Completely stop all projects and containers
  restart          Restart a project or several projects.
  share            Share project on the internet via ngrok.
  snapshot         Create a database snapshot for one or more projects.
  ssh              Starts a shell session in the container for a service. Uses web service by default.
  start            Start a ddev project.
  stop             Stop and remove the containers of a project. Does not lose or harm anything unless you add --remove-data.
  version          print ddev version and component versions
  xdebug           Enable or disable xdebug (shell web container command)

  -h, --help          help for ddev
  -j, --json-output   If true, user-oriented output will be in JSON format.
  -v, --version       version for ddev

Additional help topics:
  ddev pull             Pull files and database using a configured provider plugin.
  ddev push             push files and database using a configured provider plugin.

Use "ddev [command] --help" for more information about a command.

But it is also possible to add your own very easily to improve your workflow.

You just have to create a new script in bash in the directory corresponding to the service in which you want the command to be launched (.ddev/commands/SERVICE/).

For example, if I want to create a command to compile my sass and js with gulp in the web container, I create a file with the name of my command (e.g. compile-sass) in the .ddev/commands/web/ folder.


cd /var/www/html/themes/new-project/;
npx gulp sass-dev;
npx gulp js-dev;

I make the file executable with a simple chmod +x compile-sass and my command is accessible from my terminal.

$ ddev compile-sass
[08:22:41] Using gulpfile /var/www/html/themes/new-project/gulpfile.js
[08:22:41] Starting 'sass-dev'...
[08:22:41] Starting 'js-dev'...
[08:22:41] Finished 'js-dev' after 39 ms
[08:22:41] Starting '<anonymous>'...
[gulp] SASS compilation finished: 158 ms
[gulp] postCSS finished: 384 ms
[gulp] created sourcemap files: 384 ms
[08:22:42] Finished '<anonymous>' after 392 ms
[08:22:42] Finished 'sass-dev' after 433 ms
[08:22:42] Using gulpfile /var/www/html/themes/new-project/gulpfile.js
[08:22:42] Starting 'js-dev'...
[08:22:42] Finished 'js-dev' after 40 ms

We can quickly see that we can easily create all the commands necessary for a good optimization of the workflow for back or front development.

For most of our projects, we created commands for synchronizing files and database from the local environment with the staging environment, as well as commands for initializing the project (gulp install, symlink creation, etc.) or for updating locally (git pull, composer install, drush updb, drush cim, drush cr).


DDEV seems to check all the boxes of the perfect tool for a PHP development agency: compatible with all machines, easy to install, adaptable and extensible. Using DDEV should also reduce internal maintenance costs and accelerate the onboarding of new employees.

  • The platform has gained in popularity and its use is becoming more and more widespread. When a new employee joins us, there is a good chance that he or she has already used or tested this tool.
  • There are many tutorials online (blog posts, videos).
  • The official documentation is sufficiently rich and well structured to allow the neophyte to find the necessary information.
  • Docker images and documentation are maintained by the community.



Olivier Brunau
Olivier Brunau
Backend Developer

Olivier is experienced in both front-end and back-end development, always focusing on providing the best experience for end-users and editors.

Contact our experts and let's build your digital transformation together.