Configure Docker environment

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 ece-docker build:compose command in the ece-tools package to generate the Docker Compose configuration and deploy Magento Commerce Cloud in a Docker container.

The ece-docker build:compose command overwrites the existing docker-compose.yml configuration file. You can save your customizations for the Docker Compose configuration in a docker-compose.override.yml file. See a detailed example in the Docker quick reference.

Prerequisites

1. You must have the following software installed on your local workstation:
   • PHP version 7.1 or later
   • Composer
   • Docker
   • On MacOS and Windows, file synchronization is 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
   

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

   Because macOS 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 modes

Mode is an additional configuration option for the Docker configuration generator (the ece-docker build:compose command). This mode option 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-docker build:compose --mode="developer"

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

Stop and start containers

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

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

1
   docker-compose down -v

This command removes all components of your local Docker instance including containers, networks, volumes, and images except for the persistent database and the magento-sync volume. See Rebuild a clean environment.

Running Composer with Docker

You can run composer using the docker command before you create the container instance. This technique is useful to create an application instance during the CI/CD build process, or even during first time Magento set up.

When you run composer with Docker commands, you must use the Docker Hub PHP Image Tag that matches the Magento application version. The following example uses PHP 7.3. You run this command from the project root directory.

1
docker run -it  -v $(pwd):/app/ -v ~/.composer/:/root/.composer/ magento/magento-cloud-docker-php:7.3-cli-1.1 bash -c "composer install&&chown www. /app/"

This command passes in the current working directory as /app/, includes composer from ~/.composer/, and runs the composer install command in the container. After this set up, the command fixes the permissions on the files that have been added or changed.

Sendmail service

Send emails from your Docker environment by adding the following configuration to the docker-compose.yml configuration file:

1
ENABLE_SENDMAIL=true

We do not recommend using Sendmail on CLI containers because the service can slow down the container creation process.