By james, 14 December, 2023
Door 14 containing the DDEV logo.

It’s day 14, and we’re wrapping up the second week with a big topic. Ryan Price (liberatr) joins us to talk about DDEV, the local development environment.

When you first boot up your computer and start working on a local copy of your site, what does that look like? Is it easy? Is it a chore? (please tell me you’re working locally if you’re doing any theme or module development)

If you got a new laptop tomorrow, would you know how to get your local copies of your sites running on that machine? The idea of setting up a new machine for development used to scare me. Now that I use docker-based tools like DDEV, this is much less stressful and I recommend it to everyone.

Let me introduce you to DDEV, and then tell you about some situations when you should consider switching to (arguably) the most popular Drupal development tool after Drush.

In order to complete the examples in this article, you should install DDEV according to the instructions based on your operating system.

Since DDEV is a new tool, let’s start with a brand new Drupal site. Open your command line to a good working directory and type:

mkdir advent
cd advent
ddev config

DDEV will direct you to make a few choices and set up some sensible defaults for your new project:

ddev config
Creating a new DDEV project config in the current directory (/home/rprice/Sites/advent)
Once completed, your configuration will be written to /home/rprice/Sites/advent/.ddev/config.yaml

Project name (advent): advent

The docroot is the directory from which your site is served.
This is a relative path from your project root at /home/rprice/Sites/advent
You may leave this value blank if your site files are in the project root
Docroot Location (current directory): web
Warning: the provided docroot at /home/rprice/Sites/advent3/web does not currently exist.
Create docroot at /home/rprice/Sites/advent3/web? [Y/n] (yes): Y
Created docroot at /home/rprice/Sites/advent3/web.
Found a php codebase at /home/rprice/Sites/advent3/web.
Project Type [backdrop, craftcms, django4, drupal10, drupal6, drupal7, drupal8, drupal9, laravel, magento, magento2, php, python, shopware6, silverstripe, typo3, wordpress] (drupal10): drupal10
No settings.php file exists, creating one
Configuration complete. You may now run 'ddev start'.

Here’s what just happened:

  1. I chose my project name to be `advent`. The local domain name for this project will now be 
  2. I chose to locate my project in the `web` folder. 
  3. I chose to use the `drupal10` template. That’s enough to get started.

The next step is to start DDEV for the first time. On this first run it will install some necessary files, and set up your local web server, database, domain name and file system. When this is done we’ll initialize Drupal using composer and drush.

ddev start

Starting advent...
 Container ddev-ssh-agent  Recreate
 Container ddev-ssh-agent  Recreated
 Container ddev-ssh-agent  Started
ssh-agent container is running: If you want to add authentication to the ssh-agent container, run 'ddev auth ssh' to enable your keys.
 Network ddev-advent_default  Created
 Container ddev-advent-web  Created
 Container ddev-advent-db  Created
 Container ddev-advent-db  Started
 Container ddev-advent-web  Started
 Container ddev-router  Created
 Container ddev-router  Started
Successfully started advent
Project can be reached at

Almost ready. Now set up a new Drupal composer project:

ddev composer create drupal/recommended-project
Warning: MOST EXISTING CONTENT in the Composer root (/home/rprice/Sites/advent) will be deleted by the composer create-project operation. Only .ddev, .git and .tarballs will be preserved.
Would you like to continue? [Y/n] (yes): yes
Removing any existing files in Composer root
Executing Composer command: [composer create-project drupal/recommended-project --no-install /tmp/nPqPeu]
 Container ddev-advent3-db  Stopped
 Container ddev-advent3-web  Stopped
 Container ddev-advent3-web  Stopped
 Container ddev-advent3-db  Stopped
 Container ddev-advent3-db  Removed
 Container ddev-advent3-web  Removed
 Network ddev-advent3_default  Removed
 Network ddev-advent3_default  Created
 Container ddev-advent3-db  Created
 Container ddev-advent3-web  Created
 Container ddev-advent3-db  Started
 Container ddev-advent3-web  Started
 Container ddev-router  Running
No settings.php file exists, creating one

When that is finished, you will see a folder structure like this:

ls -1a

Most of this structure is provided by drupal/recommended-project - DDEV adds a small folder for storing its configuration, some defaults, and sets up your settings.php file with some local-dev magic.

Next you can type ddev launch and your browser should open to 

If you want to use composer or drush, you can now run them on the DDEV Docker container by typing:

ddev composer require drush/drush
ddev drush si
ddev composer require 'drupal/advent_calendar:^1.0@beta'
ddev drush -y en advent_calendar_quickstart
ddev drush cex -y

You can read more about the Advent Calendar module on the project page.

There are several other commands available. To see a full list, type:

ddev help

You can also create custom commands. A good example is something like:

ddev runallmytests

Creating a custom command requires a little knowledge of shell scripting and a little YAML, but it doesn’t take too long to build up a library of these special commands you’ll be repurposing on each new project.

If you are not the kind of person who likes to jump on the bandwagon, you may already be using a different local dev tool. I have personally used Cygwin, MAMP, HomeBrew, VirtualBox, Docksal, Lando, or just PHP and MySQL executables directly on my machine. Right now DDEV is my weapon of choice. However you are working locally now, if it works for you, it is probably fine. 

There are, however, a few reasons why you should consider DDEV or a similar solution:

  1. Do you work on more than one project in a day? In a week?
  2. Do you work with a team of two or more people?
  3. Do you have to onboard new people to your team? Are they using the same operating system (and same version of the OS) as you?
  4. Have you ever had to move your projects to a new computer?
  5. Do you have to perform a long list of steps to get your database, files and code from your hosting provider to your local machine? 
  6. Do you have another set of steps to build your CSS, Javascript, and dependencies?
  7. Do you have to perform a long list of steps to get new code and configs from your local machine to a dev environment for testing?
  8. Do you run tests on your code (e.g. PHPStan, PHPUnit, Behat, Cypress)? …and want to make sure all the dependencies are available? …and have a good way to run those tests in an automated way?

DDEV can provide a good structure and toolset for these problems and many more. I recommend some of the following resources:

Photo of Ryan PriceRyan Price has been part of the Drupal community since Drupal 4.6 - when we used to install CCK and Views from Contrib! His very first Drupal tutorial was about using shell scripts to download Drupal modules, and the first commenter said “haven’t you heard of Drush?” He is a founding member of the DrupalEasy Podcast and Florida DrupalCamp, and sometimes host of the Portland Drupal User Group. Most recently, he was the lead mentor of the 2023 cohort of Discover Drupal, by the Drupal Association. Ryan is starting a new adventure this month building Drupal sites for the US Government.


Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.