How do I set up Magento 2 with Docker for local development?

For a Magento 2 Docker setup, install Docker and run the one-command installer from Mark Shust’s docker-magento project. That installer downloads Magento 2 and starts Nginx, PHP-FPM, MariaDB, OpenSearch, Redis, Mailcatcher, and phpMyAdmin in Docker Compose. The main other prerequisite is a set of Adobe Commerce Marketplace keys.

What you need to run Magento 2 in Docker

The docker-magento README assumes at least 6GB of RAM allocated to Docker, a dual-core CPU, and an SSD. The project is tested on macOS and Linux. Windows users run it through Docker on WSL.

Installing Magento Open Source or Adobe Commerce from Adobe’s Composer repository also requires Marketplace authentication keys. Generate them by following Adobe’s authentication keys guide. Composer treats your public key as the username and your private key as the password.

How to set up a new Magento 2 project with docker-magento

Step 1: Install Docker and give it enough memory

Install Docker Desktop on macOS or Windows. On Linux, install Docker Engine and Docker Compose and run Docker’s post-install steps. Linux also needs a few extra packages:

sudo apt install curl libnss3-tools unzip rsync

In Docker Desktop, raise the memory limit to at least 6GB under Settings > Resources > Advanced. With the WSL 2 backend on Windows, set it in your .wslconfig file instead.

Step 2: Run the docker-magento setup script

mkdir -p ~/Sites/magento
cd ~/Sites/magento
curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/onelinesetup | bash -s -- magento.test community 2.4.9

The three arguments set the local hostname, the edition, and the version. Always pass the edition. Older tutorials often show the one-liner without it.

As of October 2026, Mark Shust’s docker-magento defaults to Mage-OS, the community fork of Magento. Leave the edition out and you get Mage-OS instead of Magento Open Source. Use enterprise for Adobe Commerce if your keys have access to it.

Expect a prompt for your system password, because the script writes the hostname to your hosts file. If Composer asks for repo.magento.com credentials, enter your Marketplace keys. The script also runs bin/detect-versions. That pins the PHP, Nginx, OpenSearch, database, RabbitMQ, and cache images to your chosen Magento version.

Step 3: Open the storefront and Magento admin

Once the docker-magento setup script finishes, the store loads at https://magento.test and the admin at https://magento.test/admin/. The default admin username is john.smith with the password password123. Two-factor authentication codes go to Mailcatcher at http://magento.test:1080.

Step 4: Add sample data and dev modules (optional)

bin/init

Running bin/init installs sample data and development modules. You’ll want it when building a theme or extension against a realistic catalog.

Common docker-magento commands

Most work runs through docker-magento’s helper scripts in your project’s bin folder, so you rarely call Docker directly.

• bin/start and bin/stop bring the containers up and down. Use bin/start instead of docker compose up, since it also starts the cache-clean watcher. That watcher clears only the caches affected by your edits, so you can leave Magento’s caches switched on.
• bin/magento runs the Magento CLI inside the PHP container, for example bin/magento cache:flush.
• Composer runs inside the container through bin/composer, so the PHP version on your host doesn’t matter.
• bin/mysql and bin/mysqldump import and export the database.

Moving an existing Magento project into Docker

For a project that already exists, skip docker-magento’s onelinesetup script and download its Compose template instead. Then bring in your own code and database:

1. Get the template: in a new folder, run curl -s https://raw.githubusercontent.com/markshust/docker-magento/master/lib/template | bash.
2. Add your code: clone your repository into src, then run bin/start --no-dev and bin/copytocontainer --all.
3. Install dependencies: run bin/composer install if the vendor folder is empty.
4. Import the database: run bin/mysql < magento.sql.
5. Point Magento at the containers: in app/etc/env.php, set the database host to db and use the credentials from env/db.env. Then run bin/magento app:config:import, bin/setup-domain yoursite.test, and bin/restart.

docker-magento vs DDEV vs Warden

All three run Magento 2 locally in Docker, and each suits a different kind of setup.

Setup guides for the alternatives are in the DDEV quickstart and the Warden docs. Warden’s central services let several Magento environments run side by side without port conflicts. On macOS, Warden also needs Mutagen for Magento 2 file sync.

Keeping a docker-magento setup reliable

Pin the edition and version every time, even on a quick throwaway install. Keep the Docker config in its own repository, separate from your Magento code. Run bin/update occasionally to pick up fixes. Rolling the same setup out to a group of developers? Our Magento development team can help standardise it.