Skip to main content

Docker

https://github.com/docker/cli https://github.com/docker/compose

Docker is a platform for developing, shipping, and running applications in containers.

Vortex provides a configuration for Docker and Docker Compose to run the project in all environments using containers.

Special thanks to Lagoon for providing the container images that make this possible.

info

Lagoon images run in production environments, receive regular updates, and are maintained by the Lagoon team.

If you are using Lagoon as your hosting provider, then all of your environments are using identical images to run the project.

About Docker and Docker Compose​

note

Below is a brief overview of Docker and Docker Compose. For more information, see the official documentation.

Docker lets you define services such as a web server or a database server as standalone containers, which then run in an isolated environment and can talk to each other.

The containers are started from images - templates that define what is installed in the container and how it is configured - so every container starts with consistent content and configuration.

Docker is the engine that runs containers built from images, letting them share host system resources and communicate with each other. When run locally, Docker is controlled with the Docker CLI command, docker.

Docker Compose describes a multi-container Docker application in a single docker-compose.yml file: all the containers that work together are defined in one place, which makes them easier to manage.

When working with Drupal, which requires multiple service containers, a developer would normally use the Docker Compose CLI (docker compose) rather than the Docker CLI. These commands run in the context of the current directory, so run them from the project root: they only affect the containers defined in the docker-compose.yml file there, not other containers running on the host.

When a project is fully configured, the usage of Docker-based application comes down to a handful of commands to manage the state of the containers (per project):

  • docker compose up -d - start the containers in the background.
  • docker compose down - stop and remove the containers.
  • docker compose exec <service> - run a command in a running <service> container.
  • docker compose logs -f - follow the logs of all the containers.
  • docker compose ps - list all running containers.

More advanced commands are normally used when adjusting the project Docker configuration and services.

Using Docker​

Vortex uses Docker to run the project in a containerized environment locally and in the continuous integration pipeline.

Some of the commands are wrapped in the Ahoy script as a shorthand. But all the commands can be run directly using docker compose command.

Specific commands are described in the relevant Development documentation.

Understanding docker-compose.yml​

Docker Compose reads the configuration from the docker-compose.yml and docker-compose.override.yml files. The configuration files are written in YAML, which support anchors and references that help to reduce duplication.

The file provided by Vortex contains the following sections:

Volumes definitions​

Volumes are used to share data between containers. If the host supports volume mounting, then the data can be shared between containers through the host, making it possible to access and modify the data from the host.

This is used during development to share the application code between the container and the host, so that the changes made on the host are immediately reflected in the running application.

There are 2 volumes defined:

  • Project root directory . maps to /app directory within a container. This is where a PHP engine accesses the application code.
  • Files directory ./web/sites/default/files maps to /app/web/sites/default/files directory within a container as an override to the default volume definition. This allows a different type of syncing to optimize performance, because files are not changed as often as the code.

There are 2 more volumes defined and commented out - these are used in environments without volume mounting support, such as CircleCI. These volumes definitions are automatically uncommented in the continuous integration environment, and they replace the host volume mounting, which is removed.

The VOLUME_FLAGS environment variable defines the consistency of the data within mounted volumes. The values are:

  • default: Equivalent to consistent.
  • consistent: Full consistency. The container runtime and the host maintain an identical view of the mount at all times.
  • cached: The host's view of the mount is authoritative. There may be delays before updates made on the host are visible within a container.
  • delegated: The container runtime's view of the mount is authoritative. There may be delays before updates made in a container are visible on the host.

The default value is delegated: it prioritizes the container's write performance for heavy operations like dependency installation, at the cost of container-made changes taking a moment to appear on the host.

Default user​

The default user is defined as 1000 - this is the user ID that is used in the container to run the application. This is the same user ID as the host user, so that the files created in the container are owned by the host user.

Change this value if your user ID is different.

Environment variables​

By default, Docker Compose reads environment variables from the .env file. Vortex additionally reads the .env.local file, so you can override environment variables locally without modifying the .env file.

The variables read from .env and .env.local files then passed into the containers.

This section only defines 2 types of variables:

  1. Variables that are specific to the stack and require a default value ( like LAGOON_ROUTE).
  2. Variables that cannot be stored in .env file and are injected from the actual environment (like secrets).

Any other variables should be defined in the .env file.

Consider the example:

TZ: ${TZ:-UTC}
# Local development URL.
LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io
# Local development route used in Lagoon images and Pygmy to route requests.
LAGOON_ROUTE: *default-url

where

  • TZ: ${TZ:-UTC} - defines a variable TZ with a default value of UTC, but only if TZ variable is not defined.
  • LOCALDEV_URL: &default-url ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io - defines a variable LOCALDEV_URL with a default value of ${COMPOSE_PROJECT_NAME:-example-site}.docker.amazee.io, but only if LOCALDEV_URL variable is not defined. The value of the variable is also stored in a YAML anchor default-url for later use.
  • LAGOON_ROUTE: *default-url - defines a variable LAGOON_ROUTE with a value of *default-url, which is a reference to the default-url YAML anchor defined above.

See more information about environment variables in the official documentation.

Services​

Services section describes the configuration for each container.

The following services are defined in the docker-compose.yml file provided by Vortex:

  • cli - a container that runs a shell. This container is used to run commands in the context of the project, such as composer or drush. This is also a container where cron jobs are run within a hosting environment (if that environment supports containerization).
  • nginx - a container that runs a web server. This container is used to serve the application and pass requests to the PHP container.
  • php - a container that runs a PHP engine. This container is used to run the application code and execute commands in the context of the application. It is different from the cli container in that it does not have certain development dependencies installed, has a smaller size and is optimized for scalability.
  • database - a container that runs a database server. This container is used to store the application data. It can be accessed from the host via a randomly assigned port - run docker compose port database 3306 to get the port number.
  • database2 - an optional second database container holding the source database for migrations. It is only present when the migration feature is enabled.
  • redis - an optional container that runs a Redis-compatible (Valkey) server. This container is used to store the application cache.
  • solr - an optional container that runs an Apache Solr 9 search server to store the application search index and provide full-text search. It is built from .docker/solr.dockerfile on top of the Lagoon uselagoon/solr-9-drupal image, with the configuration set maintained locally in .docker/config/solr/config-set/ so the Solr schema can be customized and version controlled. The container can be accessed from the host via a randomly assigned port - run docker compose port solr 8983 to get the port number. The Solr admin interface is available at http://localhost:<port>/solr/.
  • clamav - an optional container that runs a ClamAV antivirus server. This container is used to scan uploaded files for viruses.
  • chrome - container that runs a Chrome browser. This container is used to run Behat tests. It is based on the official Selenium image which has additional required tools, like virtual desktop, installed.
  • wait-for-dependencies - a container that runs a script to wait for applications within other containers to become available. Docker itself can coordinate startup of containers, but it does not know when the application within the container is ready to accept connections. This container is used to wait for specified application ports to become available. The whole stack is considered ready to be worked with only when this container exits with a zero exit code.

Networks​

Networks section defines the networks that are used to connect containers to each other. Pygmy provides the default amazeeio-network network that is used to connect all containers together.

Build context and .dockerignore​

When an image is built, Docker sends a build context - the set of files it is allowed to copy into the image - to the build engine. Vortex controls this context with a .dockerignore file written as a deny list: every file is part of the build context by default, and the file lists only what must be kept out.

Excluded from the image build context:

  • Version control, IDE, and operating system files (.git, .idea, **/.DS_Store).
  • Credentials and local overrides (.env.local, docker-compose.override.yml, web/sites/*/settings.local.php).
  • Host-installed dependencies, which are reinstalled during the build (vendor, node_modules, web/themes/**/node_modules).
  • Composer-generated Drupal directories, which are regenerated during the build (web/core, web/libraries, web/modules/contrib, web/profiles/contrib, web/themes/contrib, drush/Commands/contrib).
  • Content files, caches, logs, and compiled theme assets (web/sites/*/files, .data, .logs, web/themes/**/build).

Keeping these out of the context matters for both security - secrets and database dumps never reach an image layer - and speed, since a smaller context builds faster. Everything not listed, such as application code, configuration, composer.json, and settings files, is included automatically, so a new file you add reaches the build without any change to .dockerignore.

Validate docker-compose.yml​

After updating the docker-compose.yml file, it is useful sometimes to validate it before running the build. This can be done with the following command:

docker compose -f docker-compose.yml config