Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough

How to Simplify Setup of Complex Drupal Sites with Docker and Expresso PHP

Parent Feed: 

The ever increasing complexity and functionality of Drupal sites does not need to translate into increasingly steeper development costs.

In the past, Drupal sites were relatively homogeneous with the occasional multi-domain or multi-site implementation. Today, as sites become more complex, with features such as headless integration with non-Drupal software, the overhead of reproducing an environment locally can become very costly.  Docker was created to bridge the gap between a homogeneous Drupal implementation and a complex integration with non-Drupal software.  

Rather than running a full virtual machine locally, Docker emulates a given environment but still uses your operating system for better efficiency. This is done via "containers" for things like MySQL and PHP, enabling you to do things such as set a given PHP version for each site rather than system-wide. As a result, the process of increasing a site’s complexity has less of an impact on onboarding time.

To build on the benefits of Docker, Expresso PHP was created. Expresso PHP is an open-source Docker setup geared toward PHP development, including Drupal. To illustrate the benefits of Docker and Expresso PHP, let’s walk through setting up a local Drupal environment in Drupal 8 using macOS Mojave.

Software Versions Used

  • macOS Mojave 10.14.4
  • Drupal 8.6.14
  • Docker 18.09.3
  • Docker Compose 1.24.0-rc1
  • Expresso PHP v1.1.0

Setting up Drupal using Expresso PHP

1.

The first step is cloning the Expresso PHP Git repo and doing some initial setup.  This installation assumes you are installing docker sites in a "docker" directory within your local environment's home directly.  In the directions for this example,  the site in question is called "my-site."

cd ~/docker
git clone https://github.com/expresso-php/expresso-php.git my-site
cd my-site
git checkout nginx-php

2.

After cloning the repo, specify the desired PHP version here:

~/docker/my-site/docker/php/Dockerfile

The first line will look something like this:

FROM php:7.2-fpm

3.

Next, clone the Drupal site's Git repo or otherwise add the site.  This example assumes the repo will be cloned within a directory called "my-site", so its location would be

~/docker/my-site/my-site

4.

Replace the existing "web" directory with a symlink to the document root:

rm -rf ~/docker/my-site/web
cd ~/docker/my-site
ln -s my-site/docroot web

This example assumes the document root is "docroot" but it could be "www" or something else.

5.

Copy the settings.php file from default.settings.php

cd ~/docker/my-site/my-site/docroot
cp sites/default/default.settings.php sites/default/settings.php
cd sites/default

6.

Edit settings.php and replace

$databases = array();

with the following

$databases['default']['default'] = [
  'database' => 'expresso-php',
  'username' => 'expresso-php',
  'password' => 'expresso-php',
  'host' => 'db',
  'port' => '3306',
  'driver' => 'mysql',
  'prefix' => '',
  'collation' => 'utf8mb4_general_ci',
];

7.

Edit settings.php and replace

$settings['hash_salt'] = '';

with

$settings['hash_salt'] = 'expresso-php';

8.

A local domain can be used to update the host’s file..  You will need to use sudo to edit /etc/hosts and add the following:

0.0.0.0 my-site.test

9.

Optionally, create a directory for a copy of the site's database and place a *.sql of the database into this directory:

cd ~/docker/my-site
mkdir ref_db
cd ref_db


This is only needed if a Makefile or build script will be used, which is recommended; otherwise, DB import could be done via drush.

Note - The designated location for the reference database may be different for a given Makefile or build script.

10.

Add the Drupal files directory here and modify permissions if needed:

cd ~/docker/my-site/my-site/docroot/sites/default

11.

Build the Docker containers; this is only needed during setup:

cd ~/docker/my-site
docker-compose up -d

12.

The next step is importing the Drupal database.  Ideally this would be done via a Makefile or build script.

Alternatively, the DB import can be done via drush:

cd ~/docker/my-site/docroot
docker-compose exec -T php_nginx drush sql-cli < ../ref_db/ecoDB.sql

13.

Once the DB is imported, check the port needed to access the site:

docker-compose ps

It will use the port associated with my-site_nginx_1; for example 32768.

14.

Access the local website to confirm it works; for example, if the IP is 32768 then the site's URL would be:

http://my-site.test:32768
 

Commonly used Commands

To use Drush:

docker-compose exec php_nginx drush cr

To SSH in to the nginx container:

docker-compose exec php_nginx /bin/bash

To restart services:

docker-compose restart
docker-compose ps

"docker-compose ps" is included here since restarting services resets the port used to access the site.

To uninstall the site:

cd ~/docker/my-site/my-site/docroot

docker-compose down -v
cd ~/docker
rm -fr ~/docker/my-site

That's all there is to it.  When a build script or Makefile is used, a new environment can be set up in a matter of minutes. The main, limiting factor is time needed to copy in the Drupal files/ directory and import the database.
    
Expresso PHP and Docker are excellent tools that enable you to maintain a straightforward setup process, even as complexity increases -- serving as another clear indicator of the inherent agility of Drupal.

Looking for further insights on leveraging Drupal to achieve specific outcomes? Contact us today.

Author: 
Original Post: 

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web