Magento 2 Docker Setup Guide: Step-by-Step Instructions

Setting up a local Magento 2 development environment the traditional way is a time sink. PHP version conflicts, missing extensions, and database mismatches can eat hours before you write a single line of code.

That’s exactly why the Magento 2 Docker approach has become the standard for development teams. This guide walks you through the full Magento 2 Docker setup — from installing Docker to running a working storefront — with practical configuration tips and common fixes along the way.

Summary

• Why Docker is the preferred environment for Magento 2 development
• System requirements and tools needed before you start
• How to create and configure a docker-compose.yml file for Magento
• Step-by-step container setup, Magento installation, and post-install configuration
• Common errors and how to resolve them quickly
• Performance and environment tips that competitors rarely cover

Why Use Docker for Magento 2 Development?

Before jumping into the Magento 2 Docker setup, it’s worth understanding why this approach beats a traditional LAMP/WAMP stack.

Isolated, Reproducible Environments

Docker containers package every dependency — PHP, MySQL, Nginx, Redis — into a self-contained unit. This means the environment on your machine matches your teammate’s and your staging server exactly. No more “it works on my machine” problems.

Faster Onboarding for New Developers

A new developer can clone the project, run docker-compose up, and have a working Magento store running in under 15 minutes. Without Docker, that onboarding can take half a day.

Multi-Project Management

Docker lets you run multiple Magento projects simultaneously on the same machine, each on isolated ports and databases. Switching between a Magento 2.4.6 and 2.4.7 project takes seconds. This flexibility is one reason Magento continues to hold its ground against enterprise SaaS platforms — if you’re evaluating whether Magento is the right platform before committing to a Docker-based development workflow, our Magento vs Salesforce Commerce Cloud comparison breaks down the architecture, cost, and customization trade-offs in detail.

System Requirements and Prerequisites

Make sure you have the following before starting the Magento 2 Docker setup guide. It’s also worth noting that Docker works specifically with Magento’s PHP-based open-source architecture — a key technical differentiator when comparing it to lighter-weight platforms. If you’re still evaluating Magento against other open-source options, the nopCommerce vs Magento breakdown covers the platform differences in scalability, customization depth, and total cost of ownership.

What You Need Installed

• Docker Desktop (Windows/macOS) or Docker Engine (Linux) — version 20.x or later
• Docker Compose — v2.x recommended (bundled with Docker Desktop)
• Git — for cloning repositories
• Composer — for Magento dependency management
• Magento Marketplace credentials — you’ll need an access key (public + private) from marketplace.magento.com

Minimum Hardware Recommendations

If you’re running on macOS with Apple Silicon (M1/M2/M3), use Docker Desktop 4.x or later — it includes Rosetta 2 support and works well with Magento’s PHP images.

Step 1: Install Docker and Docker Compose

Installing Docker

Go to docker.com/get-started and download Docker Desktop for your OS. On Linux, install Docker Engine via your package manager:

bash

sudo apt-get update

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

After installation, verify it works:

bash

docker --version

docker compose version

Enabling Required Resources

In Docker Desktop, go to Settings > Resources and allocate at least 4 GB RAM and 4 CPUs. Magento 2 is resource-heavy, especially during compilation and indexing. Under-allocating is the number one cause of slow containers and failed installs.

Step 2: Create the Project Directory and Docker Compose File

This is the core of your Magento 2 Docker setup. The docker-compose.yml file defines every service your store needs.

Setting Up the Project Folder

bash

mkdir magento2-docker && cd magento2-docker

The Docker Compose Configuration

Create a docker-compose.yml file in the project root with the following content:

yaml

version: '3.8'

services:

web:

image: magento/magento-cloud-docker-php:8.2-fpm

ports:

- '80:80'

environment:

- VIRTUAL_HOST=magento.local

volumes:

- .:/var/www/html

depends_on:

- db

- redis

db:

image: mysql:8.0

environment:

- MYSQL_ROOT_PASSWORD=root_password  

- MYSQL_DATABASE=magento

- MYSQL_USER=magento

- MYSQL_PASSWORD=magento_password

volumes:

- db_data:/var/lib/mysql

redis:

image: redis:7.0

ports:

- '6379:6379'

elasticsearch:

image: elasticsearch:7.17.0

environment:

- discovery.type=single-node

- ES_JAVA_OPTS=-Xms512m -Xmx512m

ports:

- '9200:9200'

volumes:

db_data:

Why Elasticsearch? Magento 2.4.x requires Elasticsearch (or OpenSearch) as its search engine. Skipping this service causes installation errors during catalog setup.

Now that the services are defined, the next step is pointing your local domain to the container.

Step 3: Configure the Hosts File

Add a local domain entry so your browser can reach the Magento container.

• Linux/macOS: Edit /etc/hosts
• Windows: Edit C:\Windows\System32\drivers\etc\hosts

Add this line:

127.0.0.1 magento.local

Save the file. You may need admin/sudo privileges to do this.

Step 4: Start the Docker Containers

Navigate to your project directory and run:

bash

docker compose up -d

The -d flag runs containers in detached mode (background). The first run will pull Docker images, which may take a few minutes depending on your connection speed.

Check that all services are running:

bash

docker compose ps

You should see web, db, redis, and elasticsearch listed as running.

Step 5: Install Magento 2 Inside the Container

This is the most involved step of the Magento 2 Docker setup guide. You’ll install Magento using Composer inside the web container.

Access the Web Container Shell

bash

docker compose exec web bash

Install Magento via Composer

bash

composer create-project --repository-url=https://repo.magento.com/ \

magento/project-community-edition=2.4.7 /var/www/html

When prompted, enter your Magento Marketplace public key as the username and your private key as the password.

Set Correct File Permissions

bash

find /var/www/html -type f -exec chmod 644 {} \;

find /var/www/html -type d -exec chmod 755 {} \;

chmod -R 777 /var/www/html/var /var/www/html/generated /var/www/html/pub/static /var/www/html/pub/media

Avoid blanket 777 permissions in production. They are fine for local Docker development but should never go to a live server.

Step 6: Run the Magento 2 Installation Command

Instead of using the web-based installer, run the CLI installer for a faster, more reliable setup:

bash

php bin/magento setup:install \

--base-url=http://magento.local/ \

--db-host=db \

--db-name=magento \

--db-user=magento \

--db-password=magento_password \

--admin-firstname=Admin \

--admin-lastname=User \

[email protected] \

--admin-user=admin \

--admin-password=Admin123! \

--language=en_US \

--currency=USD \

--timezone=America/Chicago \

--use-rewrites=1 \

--search-engine=elasticsearch7 \

--elasticsearch-host=elasticsearch \

--elasticsearch-port=9200

The –db-host=db matches the service name in your docker-compose.yml. Magento containers communicate by service name, not IP address.

Step 7: Post-Installation Configuration

With Magento installed, a few final steps will get your environment production-ready for development.

Enable Developer Mode

bash

php bin/magento deploy:mode:set developer

Developer mode disables caching and shows full error details — exactly what you need when building or debugging.

Flush Cache and Run Indexers

bash

php bin/magento cache:flush

php bin/magento indexer:reindex

Access the Storefront and Admin

• Storefront: http://magento.local
• Admin panel: http://magento.local/admin (use the credentials you set during install)

If you see a blank page or 404, check that your hosts file entry is saved and the containers are all running.

Configure Redis as the Cache Backend (Optional but Recommended)

Redis dramatically speeds up Magento’s cache response. Add the following to app/etc/env.php:

php

'cache' => [

'frontend' => [

'default' => [

'backend' => 'Cm_Cache_Backend_Redis',

'backend_options' => [

'server' => 'redis',

'port' => '6379',

],

],

],

],

This is one configuration step most Magento 2 Docker setup guides skip — but it makes a real difference in page load times during development.

Common Errors and Fixes

If you’re managing a live Magento store and need help beyond local development, Folio3’s Magento development services cover everything from architecture to ongoing optimization. And if your team is weighing Magento against enterprise-grade alternatives at the platform level, the Magento vs Oracle Commerce comparison is a useful reference — it covers deployment models, infrastructure ownership, and cost structures that directly affect how you architect your development environment.

Key Takeaways

• Docker eliminates environment inconsistency — every developer gets the same setup from a single config file.
• Magento 2.4.x requires Elasticsearch or OpenSearch; skipping it breaks the install.
• Use the CLI installer (setup:install) over the web wizard for speed and reliability.
• Redis as a cache backend meaningfully improves development environment performance.
• Permission errors and container startup timing cause 80% of Docker setup failures — address those first.

Frequently Asked Questions

What Is the Best Docker Image for Magento 2 Docker Setup?

The official magento/magento-cloud-docker-php images are the most reliable starting point. For Magento 2.4.7, use the PHP 8.2-fpm variant. Community images like markoshust/magento-nginx are also widely used and well-maintained for local development.

Does Magento 2 Docker Setup Work on Windows?

Yes. Use Docker Desktop with the WSL 2 backend enabled. Performance is significantly better with WSL 2 than with Hyper-V, especially for file I/O-heavy Magento operations. Mount your project inside the WSL 2 filesystem rather than the Windows filesystem for best results.

Which PHP Version Should I Use for Magento 2 Docker?

Magento 2.4.7 supports PHP 8.1 and 8.2. Use PHP 8.2-fpm for the latest compatibility. Check the Magento system requirements page to confirm the version matrix for your specific Magento release.

How Do I Add SSL to a Magento 2 Docker Environment?

For local development, use a tool like mkcert to generate a locally-trusted SSL certificate. Add an Nginx container to your docker-compose.yml configured to terminate SSL, then update your –base-url-secure parameter during install. Most local dev environments skip SSL, but it’s useful if testing payment gateways.

How Does Magento 2 Docker Setup Compare to Warden or DDEV?

Warden and DDEV are pre-configured Docker toolkits that handle the full Magento 2 Docker setup automatically — Nginx, PHP, MySQL, Redis, Elasticsearch, and SSL are all pre-wired. If you want full control over your environment, a custom docker-compose.yml is better. If you want a working store in under five minutes with no manual config, DDEV or Warden are faster.

Can I Use This Setup for a Magento 2 Production Environment?

No. This guide is for local development. Production deployments require proper security hardening, HTTPS configuration, restricted file permissions, and optimized PHP-FPM pool settings. Review the Magento deployment best practices for production guidance.

Conclusion

A proper Magento 2 Docker setup solves the environment consistency problem that slows down most development teams. By containerizing PHP, MySQL, Redis, and Elasticsearch, you get a reproducible, portable environment that works the same way for every developer on the team.

Follow this Magento 2 Docker setup guide from start to finish, and you’ll have a fully functional store running locally — with the right services, correct permissions, and performance configurations in place. If you’re planning to scale that store or need expert hands-on help with your Magento infrastructure, talk to Folio3’s Magento team to see how we can help.