How To Set Up Drupal 7 Docker Containers for Migration Projects

Anthony Lopez-Vito — Mon, 09 Sep 2024 13:25:15 GMT

Docker is a valuable tool for Drupal 7 end of life migrations. In this post, I'll give a step-by-step guide to setting up a Drupal 7 container for your migration project. Instructions for the migration itself are out of scope for this article but you will have a running Drupal installation that can be used with a migration tool of your choice.

1. Introduction

After several deadline extensions, the Drupal Association has confirmed that Drupal 7 will officially reach end of life (EOL) on 5 January 2025. For site owners, agencies, and freelancers who've postponed making a decision, the time has come to make a choice. Do you upgrade to a newer version of Drupal, or migrate to an entirely different platform? Neither option is straightforward.

I sympathise with the "if it ain't broken, don't fix it" approach to most things, especially for something like a business-critical website. It's hard to justify disrupting a system that's running without any apparent problems. However, a Drupal 7 site migration is now unavoidable. Drupal Core will no longer be supported after EOL and hiring developers to keep it maintained, while a possibility, will not be feasible in the long term.

2. Upgrade Drupal 7 or Migrate?

It's important to understand that moving from Drupal 7 to a newer version of Drupal isn't a straightforward upgrade. Most Drupal developers already know this but it's worth pointing out early on. Unlike typical software updates, upgrading to Drupal 8 or higher involves a complete rebuild of the site.

In other words, whether you plan to upgrade or migrate to a different content management platform like WordPress, the work involved is fundamentally going to be a migration project. For this reason, throughout this article, I'll use the terms 'migration' and 'upgrade' interchangeably. Both scenarios involve similar planning, testing, and execution requirements, as well as the need for a temporary development environment.

3. Hassles with Setting up the Migration Environment

Unfortunately, site migrations are notoriously intricate, requiring careful planning and execution. Even getting set up for a migration can feel like an uphill battle. In 2012, when we first started specialising in Drupal to WordPress migrations, local web development involved making sure the whole application stack was configured properly for each project. This meant setting up a virtual host on the development machine web server, as well as getting the database and PHP configurations right. Virtualisation tools like VirtualBox existed, but they often performed poorly, freezing frequently and proving unreliable for sustained work.

The release of Docker in 2013 introduced a better way to manage development environments. As an open-source containerisation platform, it solved many of the problems developers faced when setting up for new migration projects. By isolating environments within lightweight containers, Docker streamlined workflows and eliminated many of the common compatibility headaches. By around 2018, it had become a standard tool for development teams worldwide, replacing clunky and expensive solutions like virtual machines.

In this guide, we'll outline how to set up a Docker container tailored for Drupal 7 migrations. We'll also explain how Docker simplifies the migration process while providing the flexibility required for more complex scenarios.

4. An Introduction to Docker

I'll start off with some basics for readers who aren't familiar with Docker. Feel free to skip to the setup steps if you don't need the introduction.

What is Docker?

Here's a quick overview if you're unfamiliar with the technology. Docker is a containerisation platform that lets you bundle applications and their dependencies into isolated units called containers. You can think of a container as a self-contained environment where everything your project needs, such as applications, libraries, and other dependencies, are bundled together. This approach ensures that the software runs consistently, regardless of the underlying system.

Unlike the old virtual machines, which emulate an entire operating system, Docker containers share the host system's kernel. This makes them lightweight, fast, and resource-efficient. Portability is central to Docker's appeal. A container built on a developer's laptop will work the same way on a production server. Combined with tools like Docker Compose, which orchestrates multi-container setups, you can recreate entire environments with just a few commands.

Why Use Docker for Migrations

Setting up a migration project used to require a huge amount of effort, especially for a Drupal 7 to WordPress conversion. It was a nightmare juggling multiple client projects on a single development machine. You would need to set up Apache virtual hosts for the new project sites and sometimes tweak system-wide PHP versions or database settings. If there was a risk of introducing a breaking change for another project, I would have to dig out and set up a spare physical machine.

Docker helps streamline the project setup tasks by offering isolated containers for each client, reducing the time spent building the environment and troubleshooting compatibility issues. For example, a Drupal 7 site may need PHP 5.6, while a new WordPress installation might require PHP 8. With Docker, you can run both versions in separate containers, avoiding annoying conflicts.

Docker volumes ensure data persistence for databases and installation files, even if a container is removed. Starting over from a botched migration simply means rebuilding the container from a pristine state—a process that usually takes minutes.

Key Advantages and Limitations of Docker

Docker is lightweight compared to traditional virtual machines. It shares the system kernel, allowing you to run multiple containers without overloading your system. This makes it particularly useful for testing different configurations or managing multiple projects.

However, it's important to note some limitations. Building Docker images for the first time can be time-consuming, and unused containers or images can quickly consume disk space if not managed regularly. Also, keeping a clean and efficient environment requires periodic maintenance. This can be annoying when you're knee-deep in a complex migration and you find your development machine running out of disk space.

Docker is not a complete solution for all problems, but thankfully, known issues like security concerns, networking challenges, and resource management apply to production sites rather than temporary migration environments.

Essential Docker Concepts

I'll go over some important basics before delving into the steps for setting up Docker Containers for Drupal 7 Migration Projects. You might get a little lost without an understanding of these concepts so be sure to at least skim through them if you're new to Docker. You can find information over on the dockerdocs.

Containers: Containers are lightweight, portable units that package your application and its dependencies. They run isolated from each other and the host system, ensuring consistency across development, staging, and production environments.
Images: A Docker image is a pre-configured snapshot that defines what is inside a container. Images include your application, libraries, runtime, and any dependencies.
Dockerfile: A Dockerfile is a text file with instructions for creating a Docker image. It defines the base image, environment variables, software installations, and configuration commands.
Volumes: Volumes are used to persist data generated by a container. They're essential for making sure changes to the Drupal database or files aren't lost when the container stops or is removed.
Networks: Docker's networking features allow containers to communicate with each other or with external services. For example, you could use the network to send data from Drupal container to a WordPress container, or a container that holds your migration utilities.
Docker Compose: Docker Compose is a tool that allows you to define and run multi-container Docker applications using a docker-compose.yml file. It simplifies the management of environments with multiple interconnected services (e.g., a Drupal site with a PHP container, a database container, and a reverse proxy).
Registry and Docker Hub: Docker Hub is a public registry where developers can find and share Docker images. Knowing how to pull official images from trusted sources and push your custom images to private or public registries is an important skill.
Commands and CLI Basics: Familiarity with Docker CLI commands like docker build, docker ps, and docker compose up -d --build will allow you to manage and troubleshoot containers effectively. See the command-line interfaces documentation for more about the commands.

5. How to Set Up Docker Containers for Drupal 7 Migrations

By now you should have a good understanding of what Docker is, how it can help with a migration project, and some basic concepts. Let's get on with actually setting it up. Here we'll create a container to install Drupal 7.103, released on 4 December 2024, with a full stack including web server, database and Drush.

1. Install Docker

First, ensure Docker is installed on your system. You can follow Docker's official installation guide for your operating system. I find the most convenient method is to install Docker Desktop which includes all the Docker tools and is available for Linux, Mac and Windows.

2. Create Your Project Structure

Create a folder structure for your migration project. At Another Cup of Coffee, we use a variation of following project structure.

project/
├── .env                    # Secrets and environment variables
├── backups                 # Local backups directory
├── docker-compose.yml
├── docker/
│   ├── drupal-[version]/
│   │   └── Dockerfile
│   └── phpmyadmin/
│       └── Dockerfile
├── logs                    # Log files
├── src/                    # Your local Drupal installation files
└── utils/                  # Your migration utilities

File and Database Persistence

File Changes: Drupal core/theme/module changes will persist on host through a mapping to the ./src directory.
Database Changes: the database will be stored in a named volume managed by Docker. The data will persist across container restarts/rebuilds unless the volume is manually deleted.

3. Download the Drupal Installation Files

We will use Drupal 7.103 for our container. (Note: This is the newest version, released on 4 December 2024, as of the last update for this article.) Download it from the Drupal website and extract the files into your ./src directory.

The container will create a bind mount to map the ./src directory on the host machine to /var/www/html inside the container. This means that any changes made to the files in the container at /var/www/html will be reflected in the ./src directory on the host machine, and vice versa.

4. Create Your `.env` File

The .env file is a text file used by Docker Compose to define environment variables. These variables can be referenced in the docker-compose.yml file to make your configurations more flexible and easier to manage. It's a good way of preventing sensitive information like passwords from being included in source control.

It will look something like this:

DRUPAL_DB_HOST=db
DRUPAL_DB_USER=dbuser
DRUPAL_DB_PASSWORD=dbpass
DRUPAL_DB_NAME=drupal_db

MYSQL_ROOT_PASSWORD=root

Ensure you adjust it to use your own variables.

4. Create Your Drupal Dockerfile

The Dockerfile sets out the instructions for creating a Docker image, defining the base image, environment variables, software installations, and configuration commands.

An image for Drupal 7.103 with Apache, Drush and PHP Composer might look like this:

FROM drupal:7.103-apache

# Install required PHP extensions and tools
RUN apt-get update && apt-get install -y \
    vim \
    git \
    unzip \
    libicu-dev \
    libzip-dev \
    libxml2-dev \
    libonig-dev \
    zlib1g-dev \
    default-mysql-client \
    && docker-php-ext-install pdo pdo_mysql zip intl \
    && rm -rf /var/lib/apt/lists/*

# Configure PHP
RUN echo "memory_limit = 256M" > /usr/local/etc/php/conf.d/memory-limit.ini \
    && echo "upload_max_filesize = 64M" > /usr/local/etc/php/conf.d/upload-limit.ini \
    && echo "post_max_size = 64M" >> /usr/local/etc/php/conf.d/upload-limit.ini

# Install PHP extensions needed by Drupal
RUN docker-php-ext-install pdo pdo_mysql zip intl

# Enable Apache mods commonly needed by Drupal
RUN a2enmod rewrite

# Install Composer (from the Composer official image)
COPY --from=composer:2 /usr/bin/composer /usr/local/bin/composer

# Install Drush globally via Composer
RUN composer global require drush/drush:8.*

# Ensure Drush is on PATH
ENV PATH="/root/.composer/vendor/bin:${PATH}"

# Set the container working directory
WORKDIR /var/www/html

# Ensure the Apache user (www-data) owns the web root
RUN chown -R www-data:www-data /var/www/html

This grabs the offical Docker Hub repository image for Drupal 7.103 with the Apache web server. You'll notice the Drupal image doesn't include any specifications for a database. This will be handled by the docker-compose.yml file later.

If you followed my project structure above, place this Dockerfile in a drupal-7.103 folder inside the docker subdirectory.

Adjust the Dockerfile for your own needs but here are some notes to avoid headaches:

default-mysql-client: If you're familiar with installing MySQL on a Linux system, you might be tempted to run apt-get for mysql-client. Don't do this. The Docker repository for drupal:7.103-apache is based on Debian Bookworm (Debian 12). Debian has stopped packaging mysql-client as of Debian 10 so you will encounter errors. Make sure you use the default-mysql-client metapackage instead. This will install the MySQL compatible mariadb-client.
composer:2: Although Drupal 7 does not have native Composer support, we are using it to install Drush.
drush:8: Install Drush 8, which is the latest compatible version Drupal 7 websites. A later version will install but you will encounter errors running some Drush commands.

5. Create a phpMyAdmin Dockerfile (optional)

This step is optional but it's useful to install phpMyAdmin so that you can do some basic database tasks. A phpMyAdmin Dockerfile that pulls the latest version of phpMyAdmin from the official Docker Hub repository would look like this:

FROM phpmyadmin:latest

# Add ServerName configuration
RUN echo "ServerName localhost" >> /etc/apache2/apache2.conf

Place this Dockerfile in a phpmyadmin folder inside the docker subdirectory.

6. Create Your `docker-compose.yml` File

Docker Compose will let you define and run all the necessary applications using a docker-compose.yml file. The example below defines services for Drupal, MySQL and phpMyAdmin, and should be saved in the root of your project folder. Please read the Compose file reference for a detailed explanation of each section in order to customise it for your needs.

services:
    drupal:
        build:
            context: .
            dockerfile: ./docker/drupal-7.103/Dockerfile
        ports:
            - "8088:80"
        volumes:
            # Ensure you copy your Drupal site here to avoid permission issues
            # If you are starting with a fresh Drupal installation, download
            # the correct Drupal version and extract it here.
            # https://www.drupal.org/project/drupal/releases/7.103
            - ./src:/var/www/html:cached
        depends_on:
            db:
                condition: service_healthy
        env_file:
            .env
        environment:
            DRUPAL_DB_HOST: ${DRUPAL_DB_HOST}
            DRUPAL_DB_USER: ${DRUPAL_DB_USER}
            DRUPAL_DB_PASSWORD: ${DRUPAL_DB_PASSWORD}
            DRUPAL_DB_NAME: ${DRUPAL_DB_NAME}
            PHP_FPM_USER: www-data
            PHP_FPM_GROUP: www-data

    db:
        image: mysql:5.7
        env_file:
            .env
        environment:
            MYSQL_DATABASE: ${DRUPAL_DB_NAME}
            MYSQL_USER: ${DRUPAL_DB_USER}
            MYSQL_PASSWORD: ${DRUPAL_DB_PASSWORD}
            MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
        volumes:
            - db_data:/var/lib/mysql
        ports:
            - "3307:3306"
        healthcheck:
            test: ["CMD", "mysqladmin", "ping", "-h", "localhost", "-u", "drupal", "-pdrupal_pass"]
            interval: 10s
            timeout: 5s
            retries: 5

    phpmyadmin:
        build:
            context: .
            dockerfile: ./docker/phpmyadmin/Dockerfile
        ports:
            - "8081:80"
        env_file:
            .env
        environment:
            PMA_HOST: ${DRUPAL_DB_HOST}
            PMA_USER: ${DRUPAL_DB_USER}
            PMA_PASSWORD: ${DRUPAL_DB_PASSWORD}
            PMA_ABSOLUTE_URI: http://localhost:8081/
        depends_on:
            - db

volumes:
    db_data:

The MySQL Image

You will see that I used MySQL 5.7 in this configuration to simulate an outdated environment. MySQL 5.7 reached its end of life in October 2023 but as of late-2024, we have clients who, for one reason or another, are still running MySQL 5.7. They are not alone. A September 2024 article from Percona, a database software and support company, has a FAQ section titled, "Should I upgrade from MySQL 5.7 to 8.0?" Clearly, a large percentage of sites are still running legacy databases on their web stack.

If you are using MySQL versions 8.x, visit Docker Hub's MySQL repository to see the relevant image tags. You will need to update this section:

    db:
        image: mysql:5.7

Also, most development machines will already have a MySQL server running on the local port 3306. To avoid conflicts, this docker-compose.yml maps the container's MySQL port to the local port 3307. Adjust this to suit your own setup.

        ports:
            - "3307:3306"

7. Build and Start the Environment

Now you're ready to build and start your environment. Open up a terminal and run the following command:

docker compose up -d --build

This will use Docker Compose to build the containers and run them in detached mode. It may take a few minutes to complete if you're running this command for the first time. Docker will need to download all the images from the Docker repository before building.

8. Access Your Local Drupal Setup

If all goes well you should have your environment ready to install Drupal 7. Visit http://localhost:8080 in your browser to access the Drupal 7 instance running in the Docker container.

Follow the installation wizard and Use these database settings in your .env file.

6. Testing and Workflow

You can use these commands to test your installation. Check the documentation in the Additional Resources section below for more commands.

Basic Testing

Container Status:

# Check if all containers are running
docker compose ps

Expected output: db, drupal and phpMyAdmin services should show "Up" status

Drupal Installation:

Access the Drupal site at http://localhost:8088
You should see the Drupal installation page or site
Check error logs if needed:

docker compose logs drupal

Drush Functionality:

# Test Drush status
docker compose exec drupal drush status

# Test Drush version
docker compose exec drupal drush --version

# Test site-specific Drush commands
docker compose exec drupal drush core-status

Composer Functionality:

# Test Composer version
docker compose exec drupal composer --version

# Test Composer diagnostics
docker compose exec drupal composer diagnose

Database Connection:

# Test database connection via Drush
docker compose exec drupal drush sql-connect

# Test phpMyAdmin access
# Visit http://localhost:8081

Testing Your Migration Utilities With Sample Content

You can use Drush to generate sample content. This can be useful for testing your migration utilities.

1. Log Into the Container's Terminal

docker compose exec drupal bash

2. Install Helper Modules

Install the devel, devel_generate, and taxonomy_manager modules:

drush en devel -y
drush en devel_generate -y
drush en taxonomy_manager -y

Devel Module: The Devel module is a comprehensive toolkit for Drupal developers that offers several submodules and features to aid in development and debugging.
Devel Generate Module: The Devel Generate module is a submodule of the Devel module, specifically designed for generating dummy content.
Taxonomy Manager Module: Use the Taxonomy Manager module to mass insert taxonomy terms.

3. Generate Sample Content

Now generate some sample content:

# Generate nodes with randon content
drush generate-content 500

# Generate users
drush generate-users 25

# Generate taxonomy terms
drush generate-terms tags 20

# Generate nodes for a specific content type
drush generate-content 20 --types=article

# Generate comments on random nodes:
drush generate-comments 250

Development Workflow

Here are some basic commands to support your development and migration workflow.

Starting/Stopping Environment:

# Start containers
docker compose up -d

# Stop containers
docker compose down

# View logs
docker compose logs -f

Using Drush:

# Access Drush
docker compose exec drupal drush

# Clear cache
docker compose exec drupal drush cc all

# Update database
docker compose exec drupal drush updb

Working with Composer:

# Install dependencies
docker compose exec drupal composer install

# Add new package
docker compose exec drupal composer require [package-name]

Service Access:

Drupal: http://localhost:8088
- Username and password as set during the installation process.
phpMyAdmin: http://localhost:8081
- Username: (from .env)
- Password: (from .env)
MySQL: localhost:3307
- Username: (from .env)
- Password: (from .env)

Database Operations:

# Export database
docker compose exec db mysqldump -u [user] -p[root-password] drupal > backup.sql

# Import database
docker compose exec -T db mysql -u [user] -p[root-password] drupal < backup.sql

7. Preparing for Your Drupal 7 Migration

If you made it this far, you will have a fully working and tested Docker container with Drupal 7, access to the database, and some basic tools to support migration or upgrade tasks. This environment isolates your development work, ensuring that your live site remains unaffected throughout the process.

Importing Your Live Drupal Installation into the Container

To get started with your migration project, you'll need to transfer your existing live Drupal installation into the container. The Drupal 7 documentation for migrating a site between environments will give you an outline of the steps.

As a summary, you begin by exporting the database and files from your live site. Once you have these, you can load the database into the container's MySQL instance and place the site's files in the ./src directory on your host filesystem. (Remember, we created a bind mount to map the ./src directory to the container's web directory at /var/www/html.) This gives you a working copy of your live site, but in a safe, sandboxed environment.

Important note: In this article we used Drupal 7.103 for our container. To avoid problems with version conflicts, you should update your live Drupal site to the same version before exporting.

Creating a Pristine Snapshot

Before diving into migration tasks, it's a good idea to create a snapshot of the container in its pristine state. This serves as a clean starting point you can revert to if anything goes wrong during the migration process. A snapshot ensures you won't need to repeat the setup steps from scratch if you need to restart or experiment with different migration approaches.

You create a snapshot by committing the current state of your container to a new Docker image. I'll cover this in a separate article but at this stage you will now be ready to use whatever tools you need to upgrade or migrate your Drupal 7 installation.

Migration Options

Instructions for the migration itself will need to be covered elsewhere as it's a very detailed process. However, you can check these resources for your migration options:

Upgrading to a newer version of Drupal: You can use your container to trial-run the upgrade steps in the Drupal documentation, "Upgrading from Drupal 6 or Drupal 7."
Migrating to another platform: If you plan to migrate to another platform such as WordPress, please see our Drupal to WordPress Migration Guide.

8. Conclusion

Docker provides a very practical and reliable way to set up migration environments. While it requires an initial investment in learning, the long-term benefits include consistent workflows, reliable environments, and over-all, fewer frustrations when getting started with a migration project. Docker won't solve every migration challenge, but in my experience, it definitely simplifies many of the technical hurdles involved.

If you're facing challenges with Drupal 7 migrations or need expert assistance, reach out to us at Another Cup of Coffee. We can help make your next project smooth, efficient, and future-proof.

Focus on your mission, not your tech - Another Cup of Coffee (Posts about Docker)

How To Set Up Drupal 7 Docker Containers for Migration Projects

Table of Contents

1. Introduction

2. Upgrade Drupal 7 or Migrate?

3. Hassles with Setting up the Migration Environment

4. An Introduction to Docker

What is Docker?

Why Use Docker for Migrations

Key Advantages and Limitations of Docker

Essential Docker Concepts

5. How to Set Up Docker Containers for Drupal 7 Migrations

1. Install Docker

2. Create Your Project Structure

File and Database Persistence

3. Download the Drupal Installation Files

4. Create Your `.env` File

4. Create Your Drupal Dockerfile

5. Create a phpMyAdmin Dockerfile (optional)

6. Create Your `docker-compose.yml` File

The MySQL Image

7. Build and Start the Environment

8. Access Your Local Drupal Setup

6. Testing and Workflow

Basic Testing

Testing Your Migration Utilities With Sample Content

1. Log Into the Container's Terminal

2. Install Helper Modules

3. Generate Sample Content

Development Workflow

7. Preparing for Your Drupal 7 Migration

Importing Your Live Drupal Installation into the Container

Creating a Pristine Snapshot

Migration Options

8. Conclusion

Additional Resources

You may also like

Drupal to WordPress Migration Guide

Drupal 7 End of Life: Why WordPress is the Best Migration Option for Lower Maintenance Sites

Secure Your AI Workflow Using Local Tokenisation

Focus on your mission, not your tech - Another Cup of Coffee (Posts about Docker)

How To Set Up Drupal 7 Docker Containers for Migration Projects

Table of Contents

1. Introduction

2. Upgrade Drupal 7 or Migrate?

3. Hassles with Setting up the Migration Environment

4. An Introduction to Docker

What is Docker?

Why Use Docker for Migrations

Key Advantages and Limitations of Docker

Essential Docker Concepts

5. How to Set Up Docker Containers for Drupal 7 Migrations

1. Install Docker

2. Create Your Project Structure

File and Database Persistence

3. Download the Drupal Installation Files

4. Create Your .env File

4. Create Your Drupal Dockerfile

5. Create a phpMyAdmin Dockerfile (optional)

6. Create Your docker-compose.yml File

The MySQL Image

7. Build and Start the Environment

8. Access Your Local Drupal Setup

6. Testing and Workflow

Basic Testing

Testing Your Migration Utilities With Sample Content

1. Log Into the Container's Terminal

2. Install Helper Modules

3. Generate Sample Content

Development Workflow

7. Preparing for Your Drupal 7 Migration

Importing Your Live Drupal Installation into the Container

Creating a Pristine Snapshot

Migration Options

8. Conclusion

Additional Resources

You may also like

Drupal to WordPress Migration Guide

Drupal 7 End of Life: Why WordPress is the Best Migration Option for Lower Maintenance Sites

Secure Your AI Workflow Using Local Tokenisation

4. Create Your `.env` File

6. Create Your `docker-compose.yml` File