To set up a Magento 2 development environment with docker-magento, make an empty project folder and run one command: curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s -- magento.test community 2.4.9. It downloads Magento, starts nginx, PHP, MariaDB, OpenSearch, Valkey and RabbitMQ, sets up SSL, and serves https://magento.test.
When I first started developing in Magento 2 back in 2015, I faced tons of issues trying to install Magento locally on my machine. These difficulties led me down the path of Docker, which changed the way I set up every Magento project. docker-magento is the setup I built out of that, and I've maintained it since 2016.
A working local environment is step one when you learn Magento. Docker runs each service (PHP, nginx, MariaDB, OpenSearch) in its own isolated container that shares the host kernel, so swapping a version is a one-line change, and everyone on the team runs the exact same stack. docker-magento is intended to be a development environment, though. It gets you close to production, not a copy of it.
System requirements
You'll need Docker Desktop (or Docker on Linux, or Docker on WSL for Windows) with at least 6GB of RAM allocated to Docker, a dual-core CPU and an SSD. The setup script checks the memory and stops if Docker has less than 6GB.
The one-line setup
The docker-magento repo is available at markshust/docker-magento, and it has nearly 3,000 stars on GitHub.
Create a new directory, navigate into it, and then run the one-liner from the README:
mkdir -p ~/Sites/magento
cd $_
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s -- magento.test community 2.4.9The three arguments are, in order:
- Domain:
magento.testis the hostname your store will be served from. - Edition:
communityfor Magento Open Source,enterprisefor Adobe Commerce, ormageosfor Mage-OS. - Version:
2.4.9here.
If you leave the edition and version off, docker-magento now defaults to Mage-OS (mageos 3.0.0 at the time of
writing), which is also what the README shows. Pass community 2.4.9 like above if you want Magento Open Source.
(Installing enterprise needs Adobe Commerce access on your Composer auth keys.)
Once executed, docker-magento takes care of the rest. It runs bin/detect-versions first, which pins the PHP, nginx,
OpenSearch, database, RabbitMQ and cache images that match the edition and version you picked, then boots the
containers, downloads Magento with Composer, and runs setup:install with Valkey (a Redis-compatible cache) wired up
for the cache, full page cache and sessions.
Secure certificates and /etc/hosts
docker-magento serves your store over HTTPS with a certificate from a local certificate authority, and it adds your
domain to /etc/hosts. Both need root, so you'll be prompted for your system password during setup.
Selective sync
The docker-magento repo also includes a selective sync setup to improve performance with large file systems on Docker.
It only bind-mounts the folders and files that need bi-directional sync (like app/code and app/design) and keeps
everything else, including vendor, in a native Docker volume. The why and the numbers are in my
Docker Desktop performance guide for Mac, and the original write-up is
my volume mount approach for performance
from 2018.
If you'd rather skip host mounts entirely, there's also an SSH/SFTP mode (compose.dev-ssh.yaml). Every file lives in
the container volume, and PhpStorm or VS Code syncs through SFTP.
Install sample data
Once the setup is complete, Magento 2.4.9 will be completely installed and accessible at https://magento.test.
To install sample data along with the dev-related modules, run:
bin/initbin/init deploys sample data, runs setup:upgrade, installs my
DisableTwoFactorAuth module as a dev dependency,
stretches the admin session lifetime, generates the URN catalog for your IDE, and flushes the cache.
If you only want the sample data, the manual pair still works:
bin/magento sampledata:deploy
bin/magento setup:upgradeAdditional CLI commands
The docker-magento repo includes a list of custom CLI commands found in the README. These commands execute underlying Docker commands in the background, so every developer on the team runs the same commands against the same stack, without having to learn all the Docker specifics first.
A few that are worth knowing on day one:
bin/magento,bin/composerandbin/bashrun inside the PHP container.bin/copytocontainerandbin/copyfromcontainermove files that aren't bind-mounted.bin/detect-versionsre-pins the service images after you upgrade Magento in place.bin/setup-hyva,bin/hyva-buildandbin/hyva-watchbuild Hyvä/Tailwind CSS inside the container.
If you need local tweaks to the Compose setup, put them in a compose.override.yaml file in the project root. It loads
last and wins, and bin/update never overwrites it.
Learn more about Magento 2 dev environments
This is just a really brief overview of how to get up & running quickly with docker-magento.
For a full deep dive into setting up a Magento 2 development environment, the Magento 2 Development Environment course is open access and already in your Library account, no credit card needed.
Wrapping it up
docker-magento takes the Magento environment setup down to one command, and makes onboarding easy for new developers.
If you have found docker-magento useful, please consider starring the GitHub repo ⭐️. And if something in the setup trips you up, open an issue on the repo. That feedback is how it keeps getting better. For those working with custom Docker setups, learning how to write a Dockerfile for a custom Docker image is the next thing to pick up.
