Colorfield logo


Published on

Drupal 8 with Docker CE and Docksal on macOS

Docker with Drupal

We will cover here two options to get started with Docker for Drupal: the Docker Community Edition, then a more straightforward way with Docksal.

Let's have a look at the underlying stack by starting with the bare minimum Docker setup to have a Drupal 8 site running before switching to Docksal.

Option 1: Docker Community Edition (CE)


Install Docker

Get Docker CE for MacOSX, it will run the Docker daemon.

Docker MacOSX

Then check if everything went right.

docker version
docker version

Get Drupal 8.x with PostgreSQL

Create a drupal-docker directory and put it this stack.yml file taken from the official Drupal repository on Docker hub.

cd in this directory then

docker swarm init
docker-compose -f stack.yml up

You can then list the running containers

docker ps
Docker Drupal ps

Install Drupal

Open http://localhost:8080 in your browser

Complete the database credentials with what is defined in the stack.yml file:

  • Database type: PostgreSQL
  • Database name: postgres
  • Database username: postgres
  • Database password: example
  • Under advanced options, replace localhost by postgres
Docker Drupal Postgresql install

Basic Docker commands

List Docker stacks

docker stack ls

Remove a stack

docker stack rm <stack name>

Get a container IP

# get the container id with ps
docker ps
# then inspect the container
docker inspect <container ID>

SSH into a container

docker exec -it <container id e.g. apache> bash

List all containers, even the ones that are not running

docker ps --all

Other Docker basic commands

We will not go on with Docker here, just check the documentation on for a more complete setup with PHPStorm.


Option 2: Docksal


Docksal uses Docker to create fully containerized environments. It also uses Virtual Box to support MacOS and Windows. Its main feature is the inclusion of a command-line tool, called fin, that simplifies the management of all components.

Docksal comes preloaded with common Drupal development tools like Drush and Drupal Console, as well as php tools like Composer, PHP Code Sniffer, and php-cli. It also comes with node, npm, ruby, bundler, and python.

Install Docksal

# Get or update Virtualbox then install Docksal
curl -fsSL | sh
# Create and start the VM
fin vm start

The default directory for your Docksal projects will be ~/Projects

If you are using MacOSX High Sierra, there is a bug with NFS.

Docksal High Sierra

Here is how to fix this, this documentation also explains how to switch back to Virtualbox. If you have followed the first installation of Docker CE, just add DOCKER_NATIVE=1 to ~/.docksal/docksal.env, make sure that the Docker daemon is running (start Docker CE) then

fin reset system

If you do not apply this fix, it will cause the following issue while installing Drupal on the next step.

Drupal\Core\Config\UnmetDependenciesException: Configuration objects provided by standard have unmet dependencies

Create a Drupal 8 project

Note that you will have the choice to create a Drupal 7, Drupal 8, Wordpress, Magento or static project.

fin project create

This command will clone the sample Drupal 8 project so it is equivalent to

cd ~/Projects
git clone
fin init

Docksal create project

Open http://drupal8.docksal in your browser after the setup.

Running docker ps will show the containers behind this setup.

docker ps Docksal

fin commands, to be runned in your project directory

Drupal Console and Drush

fin drupal
fin drush

Database import and dump

fin db import ~/dump.sql
fin db dump ~/dump.sql

List project services

fin status

Recreate project services and containers

fin restart

Stop project services and remove their containers

fin rm

Other fin commands