Launch Docker

The ece-tools package (version 2002.0.13 or later) deploys to a read-only file system by default in the Docker environment, which mirrors the read-only file system deployed in the Production environment. You can use the docker:build command in the ece-tools package to generate the Docker Compose configuration and deploy Magento Commerce Cloud in a Docker container.

Launch modes

Mode is an additional configuration option for the Docker configuration generator (the docker:build command). This mode does not affect the Magento mode. It determines the Magento Commerce Cloud file system installation and read-only or read-write behavior.

You can launch your Docker environment in one of the following modes:

  • production—Production mode is the default configuration setting for launching the Docker environment with read-only filesystem permissions. This option builds the Docker environment in production mode and verifies configured service versions.
  • developer—Developer mode supports an active development environment with full, writable filesystem permissions. This option builds the Docker environment in developer mode and verifies configured service versions. System performance is slower in developer mode because of additional file synchronization operations.

For example, the following command starts the Docker configuration generator for the developer mode:

1

./vendor/bin/ece-tools docker:build --mode="developer"

To skip the interactive mode, use the -n, --no-interaction option.

Service versions

Magento Commerce Cloud references the .magento.app.yaml and .magento/services.yaml configuration files to determine the services you need. When you start the Docker configuration generator (the docker:build command), you can overwrite a service version with the following optional parameters:

Service Key Available versions
Elasticsearch --es 1.7, 2.4, 5.2, 6.5
MariaDB --db 10.0, 10.1, 10.2
NGINX --nginx 1.9, latest
Node --node 6, 8, 10, 11
PHP --php 7.0, 7.1, 7.2
RabbitMQ --rmq 3.5, 3.7
Redis --redis 3.2, 4.0, 5.0

The docker:build command runs in interactive mode and verifies the configured service versions. To skip the interactive mode, use the -n, --no-interaction option.

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

1

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

Prerequisites

  1. You must have the following software installed on your local workstation:

  2. Update the hosts file.

    Before you begin, you must add the following hostname to your /etc/hosts file:

    1

    127.0.0.1 magento2.docker

    Alternatively, you can run the following command to add it to the file:

    1

    echo "127.0.0.1 magento2.docker" | sudo tee -a /etc/hosts

    To change the magento2.docker hostname for your project, you must update the host in three files: .docker/config.php, docker-compose.yml, and /etc/hosts

  3. Stop the default Apache instance on Mac OS.

    Because Mac OS provides built-in Apache service, and may occupy port 80, you must stop the service with the following command:

    1

    sudo apachectl stop
  4. Optionally, enable Xdebug.

Launch the Docker environment

  1. Download a Magento application template from the Magento Cloud repository. Be careful to select the branch that corresponds with the Magento version.

  2. Add your Magento access credentials to the auth.json file.

  3. Install the template dependencies.

    1

    composer install

  4. Continue with steps for Production mode or Developer mode.

Production mode

Continue launching your Docker environment in the default production mode.

  1. Optional: If you have a custom PHP configuration file, copy the default configuration DIST file to your custom configuration file and make any necessary changes.

    1

    cp ./docker/config.php.dist ./docker/config.php

  2. In your local environment, start the Docker configuration generator. You can use the service keys, such as --php, to specify a version.

    1

    ./vendor/bin/ece-tools docker:build

  3. Optional: Configure the Docker global variables in the docker-compose.yml file. For example, you can configure Xdebug.

  4. Build files to containers and run in the background.

    1

    docker-compose up -d

  5. Install Magento in your Docker environment.

    • Build Magento in the Docker container:
    1

      docker-compose run build cloud-build

    • Deploy Magento in the Docker container:

      1

      docker-compose run deploy cloud-deploy

    For ece-tools v2002.0.12, install Magento with the docker-compose run cli magento-installer command.

  6. Configure and connect Varnish.

    1
2
3

    docker-compose run deploy magento-command config:set system/full_page_cache/caching_application 2 --lock-env &&
 \
docker-compose run deploy magento-command setup:config:set --http-cache-hosts=varnish

  7. Clear the cache.

    1

    docker-compose run deploy magento-command cache:clean

  8. Optional: Restart services if the static content does not synchronize with all images after generation on build phase.

    1

    docker-compose restart

  9. Access the Magento instance.

Developer mode

Continue launching your Docker environment in the developer mode. The developer mode supports active development on your local environment.

The ece-tools version 2002.0.18 and later supports developer mode.

  1. Install the docker-sync tool using the Installation instructions.

    Optionally, you can install the mutagen.io tool using the Installation instructions.

    If you have it installed, continue to the next step.

  2. Optional: If you have a custom PHP configuration file, copy the default configuration DIST file to your custom configuration file and make any necessary changes.

    1

    cp ./docker/config.php.dist ./docker/config.php

  3. In your local environment, start the Docker configuration generator. You can use the service keys, such as --php, to specify a version.

    1

    ./vendor/bin/ece-tools docker:build --mode="developer"

    By default, the docker-compose configuration uses ‘docker-sync’ for file synchronization. To use ‘mutagen.io’ for file synchronization, you must run the command with the --sync-engine=mutagen option.

    For example:

    1

    ./vendor/bin/ece-tools docker:build --mode="developer" --sync-engine=mutagen

  4. Optional: Configure the Docker global variables in the docker-compose.yml file. For example, you can enable and configure Xdebug.

  5. Start the file synchronization.

    For the docker-sync tool:

    1

    docker-sync start

    If it is the first installation you should wait a few minutes for synchronization files

    If you use mutagen.io for file synchronization, skip this step. You start mutagen.io after deploying the docker containers.

  6. Build files to containers and run in the background.

    1

    docker-compose up -d

  7. Start the file synchronization with mutagen.io. If you use docker-sync for file synchronization, skip this step.

    1

    bash ./mutagen.sh

    If you host your Docker environment on Windows and the session start fails, update the mutagen.sh file to change the value for the --symlink-mode option to portable.

  8. Deploy Magento in the Docker container:

    1
2

    docker-compose run deploy cloud-deploy && \
docker-compose run deploy magento-command deploy:mode:set developer

    Developer mode does not require the build operation.

  9. Configure and connect Varnish.

    1
2

    docker-compose run deploy magento-command config:set system/full_page_cache/caching_application 2 --lock-env && \
docker-compose run deploy magento-command setup:config:set --http-cache-hosts=varnish

  10. Clear the cache.

    1

    docker-compose run deploy magento-command cache:clean

  11. Access the Magento instance.

Access Magento instance

You can access the local Magento Cloud template by opening one of the following URLs in a browser:

  • http://magento2.docker

  • https://magento2.docker

Stop and start containers

You can stop containers and restore them afterwards using the following methods.

Action Command
Suspend containers to continue your work later docker-compose stop
Start containers from a suspended state docker-compose start
Stop the synchronization daemon docker-sync stop
Start the synchronization daemon docker-sync start

Use the following command to stop and remove the Docker configuration:

1

   docker-compose down -v

This removes all components of your local Docker instance including containers, networks, volumes, and images.

Advanced usage

Extend the Docker configuration

You can use the built-in extension mechanism of Docker to specify multiple compose files. The following example replaces the default value of the ENABLE_SENDMAIL environment variable.

  1. Create a docker-compose-dev.yml file inside your project root directory and add the following content:

    1
2
3
4
5

    version: '2'
services:
  deploy:
    environment:
      - ENABLE_SENDMAIL=true

  2. Pass both configuration files while executing your commands. For example:

    1

    docker-compose -f docker-compose.yml -f docker-compose-dev.yml run deploy bash
Updated
© 2023 Magento. All rights reserved.