README

This project allows a Drupal project to be containerised for use as a standalone Docker/Podman container, in a Docker Compose/Swarm setup, or on Kubernetes.

It is intended for use in remote or production environments. There are already great solutions out there for local development.

Several Dockerfile alternatives are also available for production usage: (1, 2, 3,... In our opinion, these alternatives are complex and highly opinionated. They are not suited to out-of-the-box usage and lack some of the features we provide here.

Features

Multi-stage Dockerfile.
Apache + mod_php based.
Debian-based.
Full project codebase included in the resulting image.
Maximum flexibility: we avoid hardcoding configuration wherever possible.
Allow to specify APT packages to install.
Allow to specify PHP version and extensions to install in addition to the ones required by Drupal.
PHP configuration is managed via environment variables.
Integrates with drupal/settingsphp. This is not required, but highly recommended for a seamless integration.
Default MariaDB setup, with instructions for PostgreSQL alternative.
Includes a stage to build themes based on node.

What is included

Dockerfile.
.env.example.
System configuration files.
Operational scripts to run cron, deploy or healthcheck.
- cron and healthcheck implements a molly-guard mechanism to allow disabling them on deployment or maintenance operations.
- healthcheck integrates with drupal/health_check. You can override the url (see HEALTHCHECK_URL environment).
Example Docker Compose file for local testing.

Installation

The recommended method is to use Composer, since the process is the same as for any other Drupal package. However, a manual step is required, since we want to use the files from a location other than the vendor/. This could be a folder at the project level or at the parent level.

Alternatively you could just copy the contents of the dist/ subdirectory from this repository over your Drupal project and commit the files.

Composer project at the root of the repository

├── composer.json
├── config/
├── docker/
├── web/
│   └── ...
└── tests/
├── ...

composer require drupal/dockerize rsync -av vendor/drupal/dockerize/dist/ . cp docker/.env.example docker/.env git add .dockerignore docker/

Composer project in a subdirectory

├── docker/
├── docs/
├── src/
│   ├── composer.json
│   ├── config/
│   ├── web/
│   │   └── ...
│   └── ...
└── tests/

composer require drupal/dockerize rsync -av vendor/drupal/dockerize/dist/ .. cd .. cp docker/.env.example docker/.env editor .dockerignore # Adjust folders to the repository layout. git add .dockerignore docker/

Additionally, pass CODE_FOLDER argument to docker build with the relative path to the drupal project (CODE_FOLDER=src in this example).

Usage

Composer patches and other custom files

The Dockerfile copies the assets/ subdirectory into the image. Composer patches should be placed in the assets/patches/ subdirectory, and any other custom files, such as translations, should be placed in a subdirectory of assets/.

Build options

Available build arguments:

GIT_COMMIT. The SHA of the git commit related to this build.
PHP_VERSION. Defaults to 8.4.
PHP_DEFAULT_EXTENSIONS. The default set of extensions to install. See the Dockerfile for details. You can redefine this variable and exclude extensions.
PHP_EXTRA_EXTENSIONS. A set of extensions to install in addition to the default ones. Accepts a list such as bcmath,redis,zip.
PHP_ENVIRONMENT. Accepted values: production or development. This indicates which upstream php.ini file to use. Defaults to production.
APT_DEFAULT_PACKAGES. The default set of system packages to install. See the Dockerfile for details. You can redefine this variable and exclude packages.
APT_EXTRA_PACKAGES. An extra set of packages to install in addition to the default ones. It accepts a list such as curl,jq.
CODE_FOLDER. Path to the drupal project (i.e. the subdirectory containing the project's composer.json file). Defaults to ..

Example

docker build --build-arg GIT_COMMIT=$(git rev-parse HEAD) --build-arg PHP_EXTRA_EXTENSIONS="bcmath,redis,zip" --build-arg APT_EXTRA_PACKAGES="curl,jq" . -f docker/Dockerfile -t mydrupalsite-web

Manually build and push to a Docker registry

docker build . -f docker/Dockerfile -t registry.example.com/drupal:latest docker push registry.example.com/drupal:latest

Local testing with Docker Compose

Copy and adjust the .env file as needed:

cp docker/.env.example docker/.env

Build, launch and install:

docker compose -f docker/example.compose.yml build --build-arg GIT_COMMIT=$(git rev-parse HEAD) docker compose -f docker/example.compose.yml up -p dockerize-example -d docker compose -p dockerize-example exec drupal drush site:install -y

Visit: http://localhost:8080

Gitlab

This is a basic example based on Auto DevOps.

include:



template: Jobs/Build.gitlab-ci.yml

stages:

build

build:
  variables:
DOCKERFILE_PATH: docker/Dockerfile
AUTO_DEVOPS_BUILD_IMAGE_EXTRA_ARGS: >-
  --build-arg GIT_COMMIT=$CI_COMMIT_SHA
  --build-arg APT_EXTRA_PACKAGES=curl,jq
  --build-arg PHP_EXTRA_EXTENSIONS=bcmath,redis,zip
  --build-arg THEME_LIST=web/themes/custom/theme1,web/themes/custom/theme2
  --build-arg THEME_BUILD_COMMAND="npm ci; npm run esbuild; rm -rf node_modules"

GitHub Actions

TODO

PostgreSQL

To use a PostgreSQL database instead of MariaDB:

Replace the MariaDB variables with the PostgreSQL ones in the .env and example.compose.yml files.
Override APT_DEFAULT_PACKAGES and PHP_DEFAULT_EXTENSIONS variables to include the postgresql-client Debian package and pdo_pgsql PHP extension respectively in the build arguments.

drupal / dockerize

Maintainers

Package info

Statistics

Security