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:

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:

   • PHP version 7.1 or later
     • php@7.1
     • php@7.2
   • Composer
   • Docker
   • File synchronization required for developer mode—use one of the following:
     • docker-sync
     • mutagen

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
   

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. 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
   

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
   

   Convert custom PHP configuration files to Docker ENV files.

   1
   ./vendor/bin/ece-tools docker:config:convert
   

   This generates the following Docker ENV files:

   • .docker/config.env

   The ece-tools version 2002.0.12 package does not support the docker:config:convert command.

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
   docker-compose run deploy magento-command config:set system/full_page_cache/caching_application 2 --lock-env
   

7. Clear the cache.

   1
   docker-compose run deploy magento-command cache:clean
   

8. 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. If you have it installed, continue to the next step.

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 --mode="developer"
   

3. 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
   

   Convert custom PHP configuration files to Docker ENV files.

   1
   ./vendor/bin/ece-tools docker:config:convert
   

   This generates the following Docker ENV files:

   • .docker/config.env

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
   

   For the mutagen tool:

   1
   bash ./mutagen.sh 
   

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

   1
   docker-compose up -d
   

7. Install Magento in your Docker environment.

   • 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.

8. Configure and connect Varnish.

   1
   docker-compose run deploy magento-command config:set system/full_page_cache/caching_application 2 --lock-env
   

9. Clear the cache.

   1
   docker-compose run deploy magento-command cache:clean
   

10. 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.

To stop and remove the Docker configuration:

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

1
docker-compose down -v

To stop docker-sync daemon:

1
docker-sync stop

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