Set up a Drupal development environment with docker-compose.

Personally, I always love using docker-compose to set up local development environments. This is because you have the ability to check in your dev environment in your project’s git repo, and the only dependencies you need on your local pc are docker and docker-compose, 2 tools I hope to already find on every developer’s laptop! In this tutorial, we will set up a clean Drupal install backed by a MariaDB SQL database to provide data persistence.

First things first, if you don’t have docker and docker-compose installed, you need to install this! Detailed instructions on how to install docker on your system can be found on their getting started page. If for any reason you are not able to install docker (e.g. licensing), then Rancher Desktop provides a great drop-in replacement.

Creating your docker-compose file

In your project folder, you need to create a docker-compose.yml file with the following contents:

version: "3.9"
services:
volumes:
networks:

Add a database server

Now let’s add a database server to our docker-compose file. For this example, we are using MariaDB, an OSS fork of MySQL. This can be done by adding a DB service to the services YAML object.

...
services:
  db:
    image: mariadb:latest
    environment:
      MARIADB_USER: developer
      MARIADB_PASSWORD: dev123.
      MARIADB_ROOT_PASSWORD: dev123.
      MARIADB_DATABASE: devdb
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - backend
...

The above-snipped will add a MariaDB database with a table called devdb and a user with the name developer with a password set to dev123.. Notice that we also defined the usage of a volume, this is because we want our database to be persistent and not lose our data when we spin the docker container down. But before we can use it, we have to define this volume in our docker-compose file by adding:

...
volumes:
  db-data: {}

We also added a backend network to our database service, so that we can let our yet-to-be-created Drupal service communicate with the database. And just like the volume, we need to define this network in the docker-compose file by adding this:

...
networks:
  backend: {}

Add the Drupal server

With the database out of the way, we can focus on the Drupal service. But before adding a few lines of code to the docker-compose file, we need to create 3 new folders that will contain the custom themes and modules we will be developing, as well as the public files. So let’s create a modules, themes and public folder inside your project. And we also need to create a blank settings.php that will be used to persist the Drupal database config.

If you are running a Linux system, this can all be done by executing these commands:

$ mkdir modules
$ mkdir themes
$ mkdir public; chmod 777 public # Needs to be writable by the server
$ touch settings.php; chmod 777 settings.php # Needs to be writable by the server

Next, we need to add a few lines of code to our docker-compose file:

services:
...
  drupal:
    image: drupal:latest
    volumes:
      - ${PWD}/modules:/opt/drupal/web/modules/custom
      - ${PWD}/themes:/opt/drupal/web/themes/custom
      - ${PWD}/public:/opt/drupal/web/sites/default/files
      - ${PWD}/settings.php:/opt/drupal/web/sites/default/settings.php:rw
    ports:
      - '8081:80'
    networks:
      - backend
    depends_on:
      - db
...

You can see that the 2 folders get mounted inside the docker container under the volumes array. If you like to use another version of Drupal than the latest. Then you can change out the latest tag for a specific version that you can find on: https://hub.docker.com/_/drupal/tags.

Spin it all up

Now, with our docker-compose file ready, the only thing we need to do is execute it! Open a terminal window and cd to your project folder. Inside your project folder, execute:

$ docker-compose up

The first time you do this, it can take some time because docker has to download the images from a container registry. After a while, you will be greeted by some logging output from MariaDB and Drupal. Now open a browser and visit http://localhost:8081 and start setting up your fresh Drupal environment. Once we are done developing, we simply run:

$ docker-compose down

to turn our develop environment back off.

Bonus: add PhpMyAdmin to debug the database

Need an easy way to view your SQL database? That can be done by adding a phpMyAdmin container to your docker-compose file.

services:
...
  phpmyadmin:
    image: phpmyadmin:latest
    environment:
      PMA_ARBITRARY: 1
    ports:
      - '8080:80'
    networks:
      - backend
    profiles: ["debug"]
    depends_on:
      - db
...

Notice that we added a debug profile to this service. This allows us to only spin up the phpMyAdmin container if we need it.

$ docker-compose --profile=debug up