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

> Easily set up your Magento 2 Docker development environment. Clone the aleron75/mageres repo, configure env, and launch containers with one command for a seamless M2 workflow.

- Repository: [Alessandro Ronchi/mageres](https://github.com/aleron75/mageres)
- Tags: tutorial
- Published: 2026-02-24

---

**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`](https://github.com/aleron75/mageres/blob/main/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`](https://github.com/aleron75/mageres/blob/main/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

```bash
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:

```bash
cp .env.sample .env

```

Edit `.env` to specify your stack versions:

```dotenv
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:

```bash
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:

```bash
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:

```bash
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`](https://github.com/aleron75/mageres/blob/main/docker-compose.yml) file orchestrates the multi-container architecture. Here is the core service definition:

```yaml
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:

```dotenv

# 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:

```bash

# 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`](https://github.com/aleron75/mageres/blob/main/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`](https://github.com/aleron75/mageres/blob/main/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.