Please see available Dockerfiles on our Docker Hub Wiki page
This configuration is intended to be used as a Docker-based development environment for Magento 2.
compose: sample setups with Docker Compose
lib: files used in one line setup scripts
This setup assumes you are running Docker on a computer with at least 6GB of allocated RAM, a dual-core, and an SSD hard drive. Download & Install Docker Desktop for Mac (Community Edition).
This configuration has been tested on macOS.
This version of Docker-based development environment with mutagen sync is working fine even if it still under development, it requires the mutagen.io to be installed on your system. See the mutagen.io/documentation/introduction/installation or use Homebrew to install it on macOS
brew install havoc-io/mutagen/mutagen
Run one of the commands below from the directory you want to install your project to. Existing projects can be imported as well.
curl -s https://raw.githubusercontent.com/mage2click/docker-magento-mutagen/master/lib/setup | bash -s -- -i
-i flag above (shorthand of
--interactive) defines that setup script must be launched in interactive mode.
Simply follow the steps during setup initialisation to configure resulted Magento development environment.
curl -s https://raw.githubusercontent.com/mage2click/docker-magento-mutagen/master/lib/setup | bash -s -- --domain=magento2.test
--domain=magento2.test above defines the hostname to use.
Script accepts also other parameters and flags to configure resulted Magento development environment.
--domain=<domain>Domain to use for the project, default is
--php-version=<version>PHP version to use for the project, default is
7.2. Currently supported PHP versions:
--elasticsearch-version=<version>Elasticsearch version to use for the project, default is
6.7.2. Currently supported Elasticsearch versions:
6.7.2. All versions have the analysis-phonetic plugin installed.
--magento-archive=<path>Full path to downloaded Magento zip-archive to use in setup (optional).
--magento-project=<path>Full path to the existing Magento project to use in setup (optional).
--magento-db=<path>Full path to sql-file with database dump to use in setup (optional).
--magento-version=<version>Magento version to download from the official repository, default is
--magento-archiveparameter is specified, this will be skipped.
--composerUse `composer install` command during the setup process.
--varnishUse Varnish cache.
--mailhogUse MailHog email testing tool.
--rabbitmqUse RabbitMQ message-broker.
--cronUse cron service.
--interactiveStart interactive setup.
--helpShow usage information.
curl -s https://raw.githubusercontent.com/mage2click/docker-magento-mutagen/master/lib/setup | bash -s -- -h
-h flag above (shorthand of
--help) defines that setup script must only output usage information. This command won't start the installation process.
bin/bash: Drop into the bash prompt of your Docker container. The
phpfpmcontainer should be mainly used to access the filesystem within Docker.
bin/dev-urn-catalog-generate: Generate URN's for PHPStorm and remap paths to local host. Restart PHPStorm after running this command.
bin/cli: Run any CLI command without going into the bash prompt. Ex.
bin/clinotty: Run any CLI command with no TTY. Ex.
bin/clinotty chmod u+x bin/magento
bin/composer: Run the composer binary. Ex.
bin/copyfromcontainer: Copy folders or files from container to host. Ex.
bin/copytocontainer: Copy folders or files from host to container. Ex.
bin/fixowns: This will fix filesystem ownerships within the container.
bin/fixperms: This will fix filesystem permissions within the container.
bin/grunt: Run the grunt binary. Note that this runs the version from the node_modules directory for project version parity. Ex.
bin/magento: Run the Magento CLI. Ex:
bin/mr: Run n98-magerun2.phar inside the php-fpm container.
bin/mutagen: Mutagen sync related commands. Accepts params
flush [html|vendor]. If
flushhas extra param
vendor, only corresponded session will be flushed. Ex.
bin/node: Run the node binary. Ex.
bin/npm: Run the npm binary. Ex.
bin/redis: Run a command from the redis container. Ex
bin/redis redis-cli monitor
bin/remove: Remove all stopped service containers. Accepts params
--volumesto remove volumes.
bin/restart: Restarts all service containers. If one or more service names specified, only corresponded service containers will be restarted.
bin/restart-nginx: Restart the app container (nginx) to apply new changes to nginx.conf files (src/nginx.conf).
bin/root: Run any CLI command as root without going into the bash prompt. Ex
bin/root apt-get install nano
bin/rootnotty: Run any CLI command as root with no TTY. Ex
bin/rootnotty chown -R app:app /var/www/html
bin/self-update: Alias for bin/update.
bin/selfupdate: Alias for bin/update.
bin/share: Start share session over ngrok secure tunnels. Command accepts optional parameter to specify a region. Ex.
bin/share eu. Available regions are
in. Default is
us. For proper functioning of this command, required dependencies must be installed with
bin/setup/sharecommand (one-time action). Important: on existing setups, make sure you have using
magento-nginx:1.15-alpinedocker images in your
bin/start: Start all containers, good practice to use this instead of
docker-compose up -d, as it may contain additional helpers.
bin/status: Check the container status.
bin/stop: Stop all containers.
bin/update: Update the contents of the bin folder with the latest changes from the master branch and/or Docker images along with the rebuilding of corresponding containers and\or mutagen (only if needed). Accepts optional arguments
-v|--version=<version>(to specify version tag or branch path to fetch from, default is
master, affects only bin scripts),
-i|--imagesupdates only Docker images along with the rebuilding of corresponding containers,
-m|--mutagenupdates only mutagen (only if needed),
-a|--allupdates bin scripts, Docker images along with the rebuilding of corresponding containers and mutagen (if needed).
bin/varnish: Run commands in the Varnish container. Ex
bin/varnish varnishlog -q 'ReqURL ~ "^/$"'to monitor requests to homepage, or
bin/vanirsh varnishlog -g request -q 'ReqMethod eq "PURGE"'to monitor PURGE requests.
bin/xdebug: Disable or enable Xdebug by removing/adding corresponding .so line from/to .ini file in the PHP-FPM container. Accepts params
bin/xdebug enable. Xdebug extension is installed but disabled by default, as well as remote connections and autostart are disabled. Use our
bin/setup/xdebugcommand to get xdebug.* ini settings configured, or you can specify any xdebug.* settings via
pub/.user.inifile inside the magento project folder.
bin/setup/elasticsearch: Enable Elasticsearch as Search Engine (6.7.2 by default, see Magento 2.3.3 Supported versions for more info).
2.4: enable Elasticsearch 2.4
5.6: enable Elasticsearch 5.6
6.7.2or no flag: enable Elasticsearch 6.7.2
bin/setup/download: Download & extract specific Magento version to the
src directory. Ex.
bin/setup/import: Copy files of existing Magento project to the
src directory. Ex.
bin/setup/redis: Enable Redis for Backend Cache, Page Cache and Session.
bin/setup/share: Install Magento 2 Ngrok module for proper work of Magento with ngrok.io service. Important: on existing setups, make sure you have using
magento-nginx:1.15-alpine docker images in your
bin/setup/start: Run the Magento setup process to install Magento from the source code, with the optional parameter
--domain=<domain> (defaults to
magento2.test) and optional
--composer flag. Ex.
bin/setup/unzip: Extract downloaded Magento zip-archive to the
src directory. Ex.
bin/setup/varnishVarnish-related configurations and VCL-related actions
--configure: Apply required settings to enable Varnish as Caching Application for Full Page Cache and handle cache invalidations correctly
--generate-vcl: Generate the default.vcl file with the default Varnish config, save it to the var/default.vcl and copy from the phpfpm container to ./src/var/default.vcl .
--list-vcl: Show info from varnish container with the list of loaded VCLs, and active vcl.
--apply-vcl: Apply the specified VCL file with Varnish config (or default.vcl if no argument specified), with automated copying it from the ./src/var/ folder to the varnish container, also showing additional info about the list of loaded VCLs and active VCL before and after execution of this command.
--copy-vcl: Copy the specified file (or default.vcl if no argument specified) from the ./src/var/ folder to the varnish container.
--use-vcl: Use the specified VCL (you should specify one of the names from the bin/setup/varnish --list-vcl output - for example "boot") as active config for varnish container.
bin/setup/n98-magerun2: Install n98-magerun2.phar to the /usr/local/bin/ folder inside the php-fpm container.
bin/setup/xdebug: Enable remote debugging via set of xdebug.* ini settings in .user.ini file. Please see the detailed instructions of how to configure and use it on our Wiki page Xdebug & PHPStorm
The admin panel URL is auto-generated by the setup script. You can find the URL by using the
bin/magento info:admin command. The default username is
john.smith and the default password is
The hostname of each service is the name of the service within the
docker-compose.yml file. So for example, MySQL's (based on MariaDB:10.3 Docker image) hostname is
localhost) when accessing it from within a Docker container. Elasticsearch's hostname is
Here's an example of how to connect to the MySQL cli tool of the Docker instance:
bin/cli mysql -h db -umagento -pmagento magento
You can use the
bin/clinotty helper script to import a database. This example uses the root MySQL user, and looks for the
dbdump.sql file in your local host directory:
bin/clinotty mysql -hdb -umagento -pmagento magento < dbdump.sql
Get your authentication keys for Magento Marketplace. For more information about Magento Marketplace authentication, see the DevDocs.
The setup script will prompt you to provide authentication information!
To manually configure authentication, copy
src/auth.json. Then, update the username and password values with your Magento public and private keys, respectively. Finally, copy the file to the container by running
Redis is now the default cache and session storage engine, and is automatically configured & enabled when running
bin/setup on new installs.
Use the following lines to enable Redis on existing installs:
Enable for Cache:
bin/magento setup:config:set --cache-backend=redis --cache-backend-redis-server=redis --cache-backend-redis-db=0
Enable for Full Page Cache:
bin/magento setup:config:set --page-cache=redis --page-cache-redis-server=redis --page-cache-redis-db=1
Enable for Session:
bin/magento setup:config:set --session-save=redis --session-save-redis-host=redis --session-save-redis-log-level=4 --session-save-redis-db=2
You may also monitor Redis by running:
bin/redis redis-cli monitor
For more information about Redis usage with Magento, see the DevDocs.
Please see the detailed instructions of how to configure and use it on our Wiki page Xdebug & PHPStorm
Certified Magento Developer & Architect and Zend Certified Engineer, and available for consulting & development of your next project 🤓. You can read technical articles on my blog at markshust.com or contact me directly at [email protected].
Mark Shust's Free Course about Setup a Magento 2 Development Environment with Docker
A special thanks goes out to Nexcess for hosting public archives of every version of Magento 💙. I've used their Magento hosting services in the past also (both shared and enteprise offerings) and they're great, ...highly recommended!
Implemented Varnish support with https proxy Willem Wigman