Cloud Docker development

Cloud Docker for Commerce provides an option to deploy Adobe Commerce to a Docker environment for development, testing, and automation tasks. It includes the following features:

  • Cross-platform support–Supports Linux, macOS and Windows with WSL2
  • Magento Cloud emulation–Provides a Cloud-like deployment pipeline and filesystem to test code locally before deploying your Cloud for Adobe Commerce project to Staging or Production servers
  • Adobe Commerce development–Creates a local development environment for Magento On-premises projects
  • Multiple sync options–Provides three file synchronization options: native, mutagen, and manual-native. The manual-native option provides the best performance on macOS and Windows.
  • Extensibility–Use a standard Docker configuration file to extend and customize your development environment

Cloud Docker for Commerce is a Magento Community Engineering project supported by the Magento developer community. For details and support information, see Get support for Cloud Docker for Commerce.

Host Operating Systems

The Cloud Docker environment supports Linux, macOS, and Windows operating systems. The containers should run on any Docker host, but some of the set up scripts require you to install PHP and Composer.

Prerequisites

  • Git for interaction between your local system and Cloud for Adobe Commerce source repositories
  • Docker for Mac 2.2.0.0 or later or Docker for Linux
  • Developer mode on macOS systems might require the mutagen option for file synchronization.

Docker engine

Cloud Docker for Commerce requires the following Docker resources to support local Docker development.

  • CPUs: 2
  • Memory: 6.00 GB
  • Swap: 1.00 GB

You can configure Docker resources from the Docker Desktop.

PHP and Composer

Cloud Docker for Commerce does not require PHP and Composer to be installed locally. We provide an installation script, init-docker.sh to perform PHP and Composer operations.

The init-docker.sh script runs the following command which installs the template dependencies and sets both the PHP version and the Cloud Docker for Commerce image version.

1
docker run --rm -e "MAGENTO_ROOT=/app" -v "$(pwd)":/app -v ~/.composer/cache:/root/.composer/cache "magento/magento-cloud-docker-php:${PHP_VERSION}-cli-${IMAGE_VERSION}" composer install --ansi

The script option settings determine the PHP version and Cloud Docker for Commerce image version. The script also adds the default hostname, magento2.docker, to your /etc/hosts file.

init-docker.sh options

Option Description
-p, --php PHP version (for installing dependencies). You must specify a PHP version that is compatible with the Adobe Commerce version deployed to the Cloud Docker envrionment. Defaults to 7.2
-i, --image Cloud Docker for Commerce image version (for installing dependencies). Defaults to 1.1
--host Domain name to add to the /etc/hosts file. Defaults to magento2.docker
--add-host Add domain name to /etc/hosts file. Defaults to true (yes)
-h, --help Get help

Examples:

To run the script with default settings:

1
bin/init-docker.sh

To run the script to install PHP 7.3 and skip adding the domain to the etc/hosts file:

1
bin/init-docker.sh --php 7.3 --add-host no

On initial project installation, you can use cURL to run the installation script and install the template dependencies. See Update the hosts file and install dependencies.

Web server configuration

Cloud Docker for Commerce binds to port 80 on your host environment. If you have enabled the bundled web server on your workstation you must stop the service before launching the Docker environment.

1
sudo apachectl stop

If you start your Docker environment with Apache running, the following error displays: Cannot start service tls: Ports are not available: port is already allocated

Composer authentication keys

Prior to setting up a local workspace, gather the following credentials and account information:

  • Magento authentication keys (Composer keys)

    Magento authentication keys are 32-character authentication tokens that provide secure access to the Magento 2 Composer repository (repo.magento.com), and any other Git services required for Magento development such as GitHub. Your account can have multiple Magento authentication keys. For the workspace setup, start with one specific key for your code repository. If you do not have any keys, contact the Account Owner to create them, or create the Magento authentication keys yourself.

  • (Optional) Cloud Project account

    The License Owner or Technical Admin (Super User) should invite you to the Cloud for Adobe Commerce project. When you receive the e-mail invitation, click the link and follow the prompts to create your account. See Set up an account for details.

  • (Optional) Magento Encryption Key

    When importing an existing Magento instance, capture the Magento encryption key used to protect your access and data for the Magento database. For details on this key, see Resolve issues with encryption key