How to Set Up a Docker Development Environment for Magento 2: Complete Guide

You can set up a complete Magento 2 Docker development environment by cloning Mark Shust's docker-magento configuration, configuring the .env file with your desired PHP and Magento versions, and running bin/docker-compose up -d to orchestrate containers for Nginx, PHP-FPM, MySQL, Elasticsearch, and Redis.

Magento 2 requires a complex stack including Nginx, PHP-FPM, MySQL, Elasticsearch, and Redis. A Docker development environment for Magento 2 isolates these services into containers, ensuring version consistency across development teams. The Mageres repository curates several Docker-based setups, with Mark Shust's Docker configuration being the most widely adopted for production-grade local development.

Why Use Docker for Magento 2 Development?

Docker containers encapsulate every service Magento 2 requires, eliminating "works on my machine" issues. Each developer runs identical versions of PHP-FPM, MySQL, Elasticsearch, and Redis, configured exactly as specified in the docker-compose.yml file. This isolation prevents conflicts with host system packages and allows running multiple Magento versions simultaneously on the same workstation.

Recommended Approach: Mark Shust's Docker Configuration

The Mageres repository lists Mark Shust's configuration as the premier Docker setup for Magento 2. This open-source project provides a complete orchestration layer with helper scripts that abstract Docker complexity, allowing developers to run Magento CLI commands as if PHP were installed locally.

Architecture Overview

The environment consists of seven interconnected containers:

• nginx: Handles HTTP/HTTPS traffic on ports 80/443, serving static assets and proxying PHP requests
• php: Runs PHP-FPM (version 8.3 by default) to execute Magento application code
• db: MariaDB or MySQL 8 database server storing catalog and customer data
• elasticsearch: Search engine for product catalog queries
• redis: Session storage and application cache backend
• mailhog: SMTP trap for testing transactional emails
• varnish: HTTP accelerator (optional) for full-page caching

All containers share a Docker network, and the Magento source code lives in a mounted volume (./src) so host file changes reflect instantly inside containers.

Key Components and File Structure

• docker-compose.yml: Defines all service containers, networks, and volumes
• .env: Central configuration for PHP versions (8.3), Magento versions (2.4.7), and MySQL versions (8)
• bin/docker-compose: Wrapper script that automatically includes the --env-file .env flag
• bin/magento: Executes Magento CLI commands inside the PHP container without requiring local PHP installation
• docker/nginx/conf.d: Nginx virtual host configuration for Magento-specific rewrite rules and FastCGI settings
• src/: Mounted directory containing the Magento application code

Step-by-Step Setup Guide

Prerequisites

Install Docker Desktop (macOS/Windows) or Docker Engine with Docker Compose (Linux). Ensure Docker has at least 4GB RAM allocated for Elasticsearch and Magento to function properly.

1. Clone the Docker Configuration

git clone https://github.com/markshust/docker-magento.git magento-docker
cd magento-docker

2. Configure Environment Variables

Copy the sample environment file and customize versions as needed:

cp .env.sample .env

Edit .env to specify your stack versions:

PHP_VERSION=8.3
MAGENTO_VERSION=2.4.7
MYSQL_VERSION=8
ELASTICSEARCH_VERSION=8.9.0

3. Start the Containers

Execute the wrapper script to launch the entire stack:

bin/docker-compose up -d

This command downloads images, creates containers, initializes the database volume, and establishes the Docker network.

4. Install Magento 2

Run the Magento setup command inside the PHP container using the helper script:

bin/magento setup:install \
  --base-url=http://magento.test \
  --db-host=db \
  --db-name=magento \
  --db-user=magento \
  --db-password=magento \
  --admin-firstname=Admin \
  --admin-lastname=User \
  --admin-email=admin@example.com \
  --admin-user=admin \
  --admin-password=Admin123 \
  --language=en_US \
  --currency=USD \
  --timezone=America/Chicago \
  --use-rewrites=1

5. Configure Local DNS

Add the domain to your hosts file so it resolves to the Docker container:

echo "127.0.0.1 magento.test" | sudo tee -a /etc/hosts

Access the storefront at http://magento.test and the admin panel at http://magento.test/admin.

Essential Docker Compose Configuration

The docker-compose.yml file orchestrates the multi-container architecture. Here is the core service definition:

services:
  nginx:
    image: nginx:stable-alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./src:/var/www/html:cached
      - ./docker/nginx/conf.d:/etc/nginx/conf.d:cached
    depends_on:
      - php

  php:
    image: php:${PHP_VERSION}-fpm
    build:
      context: ./docker/php
      args:
        PHP_VERSION: ${PHP_VERSION}
    env_file:
      - .env
    volumes:
      - ./src:/var/www/html:cached
    depends_on:
      - db
      - redis
      - elasticsearch

  db:
    image: mariadb:${MYSQL_VERSION}
    environment:
      MYSQL_ROOT_PASSWORD: root
      MYSQL_DATABASE: magento
      MYSQL_USER: magento
      MYSQL_PASSWORD: magento
    volumes:
      - dbdata:/var/lib/mysql

  elasticsearch:
    image: elasticsearch:${ELASTICSEARCH_VERSION}
    environment:
      - "discovery.type=single-node"
    volumes:
      - esdata:/usr/share/elasticsearch/data

  redis:
    image: redis:6-alpine
    volumes:
      - redisdata:/data

volumes:
  dbdata: {}
  esdata: {}
  redisdata: {}

Environment Configuration

Centralize version management in the .env file to avoid modifying the compose file directly:

# Docker image versions

PHP_VERSION=8.3
MYSQL_VERSION=8
ELASTICSEARCH_VERSION=8.9.0

# Magento version

MAGENTO_VERSION=2.4.7

# Composer auth (optional)

COMPOSER_AUTH_JSON={"http-basic":{"repo.magento.com":{"username":"<public_key>","password":"<private_key>"}}}

Daily Development Commands

The helper scripts in the bin/ directory abstract container complexity. Use these for daily workflows:

# Run any Magento CLI command (executes inside php container)

bin/magento cache:clean
bin/magento setup:upgrade
bin/magento indexer:reindex

# Run Composer inside the PHP container

bin/composer require magento/product-community-edition

# Open a shell inside the PHP container

bin/bash

# View logs for a specific service

bin/docker-compose logs -f php

# Stop the environment

bin/docker-compose down

To enable Xdebug for PHPStorm or VS Code, set XDEBUG_MODE=debug in your .env file before starting the containers.

Summary

• Mark Shust's Docker configuration provides the most robust Docker development environment for Magento 2, featuring containers for Nginx, PHP-FPM 8.3, MySQL 8, Elasticsearch, and Redis.
• The docker-compose.yml file orchestrates seven interconnected services, while the .env file centralizes version management without editing compose files directly.
• Helper scripts in bin/docker-compose and bin/magento eliminate the need for local PHP installation by executing commands inside appropriate containers.
• The setup requires only Docker Desktop or Docker Engine, and the entire stack initializes with a single bin/docker-compose up -d command after configuring environment variables.

Frequently Asked Questions

What are the system requirements for running Magento 2 in Docker?

You need Docker Desktop (macOS/Windows) or Docker Engine with Docker Compose (Linux). Allocate at least 4GB of RAM to Docker for Elasticsearch and Magento to function properly, as the search indexer and PHP-FPM processes consume significant memory during catalog operations.

How do I switch PHP versions in the Docker environment?

Modify the PHP_VERSION variable in your .env file (for example, change PHP_VERSION=8.3 to PHP_VERSION=8.2), then run bin/docker-compose down followed by bin/docker-compose up -d to recreate the PHP container with the new image version. The docker-compose.yml references ${PHP_VERSION} dynamically when building the PHP-FPM image.

Can I use this setup for production deployments?

No, Mark Shust's Docker configuration is optimized for local development with features like Mailhog (email catching), Xdebug support, and mounted volumes for live code editing. Production environments require hardened security configurations, proper SSL termination, backup strategies, and resource limits that differ significantly from this development-focused orchestration.

How do I debug with Xdebug in the Docker containers?

Set XDEBUG_MODE=debug in your .env file before starting the containers, then restart the PHP container with bin/docker-compose restart php. Configure your IDE (PHPStorm or VS Code) to connect to localhost on port 9003 (or 9000 depending on configuration), mapping the remote path /var/www/html to your local ./src directory. The helper script bin/bash provides direct shell access for debugging CLI scripts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}