Docker container architecture

The magento/magento-cloud-docker repository contains build information to create a Docker environment with the required specifications for Magento Cloud. The build configuration creates a Docker instance with CLI and service containers required to run Magento Cloud in a local Docker environment. You can customize the Docker containers available in the repository and add more as needed.

Magento Cloud Docker generates the docker-compose.yml file to the required specifications. Then, you use docker-compose to create the container instances and to build and deploy the Magento Commerce site.

CLI Containers

The following CLI containers, most of which are based on a PHP-CLI version 7 Docker image, provide magento-cloud and ece-tools commands to perform file system operations and interact with the application:

Name Service Key Available Versions Notes
build Build Container none none PHP Container, runs build process
deploy Deploy Container none none PHP Container, runs the deploy process
cron Cron Jobs none none PHP Container, runs cron tasks
node Node --node 6, 8, 10, 11 Used gulp or other NPM based commands

See Docker CLI containers for details.

Service containers

Magento Cloud Docker references the and .magento/services.yaml configuration files to determine the services you need. When you start the Docker configuration generator using the ece-docker build:compose command, use the optional build parameters to override a default service version or specify custom configuration.

For example, the following command starts the Docker configuration generator in developer mode and specifies PHP version 7.2:

./vendor/bin/ece-docker build:compose --mode="developer" --php 7.2

Service configuration options

The following table shows the options to customize service container configuration when you generate the Docker Compose configuration file.

Name Service Key & options Available Versions Notes
db MariaDB or MySQL
--db, --db-image (MySQL)
10.0, 10.1, 10.2
5.6, 5.7
Use the increment and offset options to customize the auto-increment settings for replication.

Use the --with-entrypoint and --with-mariadb-config options to automatically configure database directories in the Docker environment

Example build commands:
ece-docker build:compose --db <mariadb-version>
ece-docker build:compose --db <mysql-version> --db-image
elasticsearch Elasticsearch --es
1.7, 2.4, 5.2, 6.5, 6.8, 7.5, 7.6 Use the options to specify the Elasticsearch version, customize Elasticsearch configuration options, or to build a Docker environment without Elasticsearch.
7.0, 7.1, 7.2, 7.3, 7.4 Used for all incoming requests. Optionally, add Xdebug configuration to debug PHP code in the Docker environment.
node Node --node 6, 8, 10, 11 Used gulp or other NPM based commands
rabbitmq RabbitMQ --rmq 3.5, 3.7, 3.8  
redis Redis --redis 3.2, 4.0, 5.0 Standard redis container
selenium Selenium --with-selenium
Any Enables Magento application testing using the Magento Functional Testing Framework (MFTF)
tls SSL Endpoint     Terminates SSL, can be configured to pass to varnish or nginx
varnish Varnish --no-varnish 4, 6.2 Varnish is provisioned by default. Use the --no-varnish option to skip Varnish service installation
web NGINX --nginx 1.9, latest  

Use the following command to view the available options for the ece-docker build:compose command:

./vendor/bin/ece-docker build:compose --help

Request Flow

Web requests to https://magento2.docker/ are handled by the Docker containers using the following request flow:

  1. TLS
  2. Varnish
  3. Web (nginx)
  4. FPM

You can remove Varnish from the configuration, in which case the traffic passes directly from the TLS container to the Web container.

Sharing data between host machine and container

You can share files easily between your machine and a Docker container by placing the files in the .docker/mnt directory. You can find the files in the /mnt directory the next time you build and start the Docker environment using the docker-compose up command.

Sharing Magento Cloud project data

When you launch the Magento Commerce Cloud project in a local Docker environment, the default project configuration creates the following volumes:


You can use these volumes to interact with the shared writeable mount directories for your Magento Cloud project, which are configured by default in the file.

 # The mounts that will be performed when the package is deployed.
    "var": "shared:files/var"
    "app/etc": "shared:files/etc"
    "pub/media": "shared:files/media"
    "pub/static": "shared:files/static"

You can customize this configuration by updating the mounts section in the file.

File synchronization

Additionally, you can share data into the containers using file synchronization. See the File synchronization and Developer mode documentation.

Container Volumes

Magento Cloud Docker uses Docker volumes to maintain data throughout the lifecycle of the Docker containers. These volumes can be defined in several ways:

You do not interact with most of these volumes, which are used by the Docker containers and follow the docker-compose lifecycle. The only exception to this is the magento-sync directory that is an external volume used by the Mutagen application to transport data into the containers from the host operating system.

Rebuild a clean environment

The docker-compose down command removes all components of your local Docker instance, including containers, networks, volumes, and images. However, this command does not affect the persistent database volume or the magento-sync volume used for file synchronization.

To remove all data and rebuild a clean environment:

 bin/magento-docker down -v

The magento-sync volume is an external volume that you must create or delete manually. If the magento-sync volume does not exist, the following error message displays:

ERROR: Volume magento-sync declared as external, but could not be found. Please create the volume manually using `docker volume create --name=magento-sync` and try again.

Container Logs

All containers use the Docker logging method. You can view the logs using the docker-compose command. The following example uses the -f option to follow the log output of the TLS container:

docker-compose logs -f tls

Now you can see all requests that are passing through the TLS container and check for errors.