Dockerize Drupal with Ddev

If you haven’t heard of Docker yet, it’s high time you did some research. Basically, Docker can be used to establish and create a standard environment in which your website can be run. This prevents situations where the same code works on your laptop but doesn’t work on the server or someone else’s computer.

Ddev is an open source tool that makes it dead simple to get local PHP development environments up and running within minutes.

In this article, you’ll learn how to use ddev to easily dockerize your Drupal site without having to dig deep into the core concepts of Docker. You will also see how to use ddev for complex projects that need additional services and customizations.

Two Minute Version

• Install Ddev as per documentation.
• In your Drupal project root, run ddev config and complete the process.
• Config files should be generated in a .ddev directory.
  • Fine-tune the .ddev/config.yml as per requirements.
• Run ddev start to kick-off your project.
  • Your site should be available at PROJECT-NAME.ddev.site.
• Run drush commands like ddev exec drush --version.
• When you’re done working run ddev stop to stop the containers.

Getting started

Here are somethings you need in order to get started.

• Install Docker by referring to Docker docs.
• Install Ddev by referring to Ddev docs.
• Create a Drupal project first or choose an existing project.
  • This article assumes that you’re using Drupal 8.
  • However, not much should change if you’re using a different version.
• You’ll need some basic command-line skills as well.

Though this article is specifically about using Ddev with Drupal, making it work with other PHP applications should not be very difficult.

Configuring ddev

Make sure Ddev is installed properly by running ddev --version in a terminal. You should see the version of Ddev you’re running. Once done, do the following steps:

1. In your terminal window and cd into the root of your Drupal project.  This can be one of the 2 directories below:
   • Drupal’s docroot, i.e. the directory containing index.php.
   • The directory above Drupal’s docroot – this is more common these days.
2. If you’re using Git, I'd suggest making a commit at this point.
3. To configure Ddev, run the command ddev config. This will ask you a series of questions about your project which you should answer correctly:
   • Project name: The name of the project.
   • Docroot: The directory containing index.php.
   • Project type: The framework you’re using for your project, i.e.  drupal8, drupal9.

Doing this will generate a .ddev directory containing Ddev configuration files and one or more Drupal settings files in the sites directory. We’ll discuss these settings in the next section. You can fine-tune the config as needed, mainly the .ddev/config.yaml file.

Hostnames

By default Ddev makes your site available at PROJECT-NAME.ddev.site:PORT. You can configure additional hostnames in one of the following ways.

# Makes the site available at example.ddev.site:PORT
additional_hostnames:
  - example
# Makes the site available at example.dev:PORT
additional_fqdns:
  - example.dev

Personally, I configure my dev sites to have URLs like dev.example.com.

Ports

By default, Ddev configures websites to be available at port 80 (http) and port 443 (https). However, if you want to run multiple projects, you can configure the ports as follows.

router_http_port: 9980
router_https_port: 9943

I usually choose a port prefix for every project and prepend this prefix to the ports. For example, if the port prefix is 99, you can configure your site to work on ports 9980 (http) and 9943 (https). Having project-specific port prefixes prevents conflicts with other projects running on the same computer.

Configuring Drupal

During the Ddev configuration, it sets up some Docker containers for your application:

1. web: this contains your application’s code.
2. db: this contains your database server, usually MySQL.
3. dba: this runs a service that lets you access your database using a GUI, usually, PHPMyAdmin.

Now, for your local Drupal site to detect and use the MySQL server and other Ddev services, you need to add certain lines to your settings.php or settings.local.php file. Simply include the settings.ddev.php file generated by ddev config.

// Include settings for ddev services.
if (file_exists(__DIR__ . '/settings.ddev.php')) {
  include __DIR__ . '/settings.ddev.php';
}

This tells your Drupal site to use Ddev’s database server to store data. If you’re using additional services like Solr, you might need to add some lines to the settings.ddev.php file to configure those services.

Common commands

Here are some commonly used Ddev commands. These commands need to be executed from within a project for which you’ve configured Ddev.

• ddev help: displays a list of all commands with a brief help text.
• ddev start: starts project containers.
• ddev stop: stops project containers.
• ddev restart: restarts project containers.
• ddev delete: delete project containers and data.
• ddev ssh: SSH into a service. Defaults to the web service.
  • Run ddev auth ssh to enable your SSH keys within the containers.
• ddev exec: Executes a command within a container.
  • By default, the command runs on the web service.
  • Use the --service flag to run it on other services.

Using drush

There is no special configuration required to make drush work with Ddev. You can run drush commands like this:

ddev exec drush --version
ddev . drush --version # Short hand

However, for drush to know the URL of your local website, you can add the following lines to your  drush.local.yml file.

# File: sites/default/drush.local.yml
options:
  uri: "http://dev.example.com:PORT/"

You will also need to make sure that the above Drush config file is actually picked up by Drush. You can do this as follows:

# File: drush/drush.yml
drush:
  paths:
    config:
      - "web/sites/default/drush.local.yml"

This makes commands like drush uli use the correct URL for your dev website.

Customizing builds

For each important service in your project, ddev generates a directory named .ddev/SERVICE-build, for example, .ddev/web-build. Within these directories is a Dockerfile.example file. If you want to customize the build process for any of your service containers, you must:

1. Copy the Dockerfile.example as Dockerfile.
2. Add your custom build steps to the Dockerfile.
   • For example, RUN apt update && apt install -y vim.
3. Restart the project’s containers with ddev restart.

Refer to Docker docs to learn more about using a Dockerfile.

Additional services

Ddev-contrib offers a number of additional services that you can integrate into your project.  You can read more about adding additional services in the ddev documentation. This usually involves creating a docker-compose.SERVICE.yml file in the .ddev directory and some other steps depending on the service that you’re trying to add.

Conclusion

To conclude, Ddev is indeed an easy to use solution to dockerize your projects and its usage is not limited to Drupal (or PHP). Projects are very easy to set up and their tech support team is also very active. Personally, I’ve found that it is very light weight and it doesn’t get in the way when you’re working on a project. Also, Ddev reveals parts of docker-compose APIs which makes it easy to customize your builds if you have Docker knowledge.

Next steps

• See the sample code for using Drupal with Ddev.
• Read Ddev documentation.
• Read about adding additional services to Ddev.
• Read Docker documentation.
• Read Docker Compose documentation.