Magento 2 — Ambiente Docker de Desenvolvimento

Stack: PHP 8.3-FPM · Nginx 1.25 · MySQL 8.0 · OpenSearch 2.12 · Redis 7.2 · RabbitMQ 3.12
Orquestração: Makefile (sem scripts auxiliares)

---

Índice

1. Pré-requisitos por plataforma
2. Estrutura do projeto
3. Setup do zero
4. Referência de comandos
5. Xdebug
6. Desenvolvimento de módulos
7. Portas expostas

---

1. Pré-requisitos por Plataforma

Linux

sudo apt-get install -y docker.io docker-compose-plugin make
sudo usermod -aG docker $USER && newgrp docker

macOS

• Docker Desktop 4.x — em Settings → General → Virtual File Sharing selecione VirtioFS
• Recursos mínimos: 6 CPU / 8 GB RAM (Settings → Resources)
• make já está disponível via Xcode Command Line Tools

Windows (obrigatoriamente via WSL2)

# PowerShell como Administrador
wsl --install -d Ubuntu
wsl --set-default-version 2

• Instale o Docker Desktop e ative "Use the WSL2 based engine"
• Todo o trabalho deve ocorrer dentro do WSL2 (~/projetos/...), nunca em /mnt/c/
• Instale make dentro do WSL2: sudo apt-get install -y make

Git Bash no Windows: O Makefile já exporta MSYS_NO_PATHCONV=1 e MSYS2_ARG_CONV_EXCL=* para evitar a conversão automática de paths Unix → Windows. Para make shell, prefixe com winpty se o terminal travar: winpty make shell

---

2. Estrutura do Projeto

.
├── Makefile                     # Orquestração completa (make help)
├── docker-compose.yml           # Stack de serviços
├── .env.example                 # Variáveis de ambiente — copie para .env
├── docker/
│   ├── nginx/
│   │   ├── default.conf         # Nginx otimizado para Magento
│   │   └── certs/               # SSL auto-assinado (gerado por make ssl)
│   ├── php/
│   │   ├── Dockerfile           # PHP 8.3 + extensões Magento + Xdebug 3
│   │   └── php-dev.ini          # memory=2G, OPcache agressivo, Xdebug
│   └── mysql/
│       └── my.cnf               # Tuning InnoDB
└── src/                         # Código-fonte Magento (bind mount)
    └── app/
        ├── code/                # ← Seus módulos (bind mount direto)
        └── design/              # ← Seus temas  (bind mount direto)

vendor/ fica em um volume Docker isolado — sem overhead de sincronização no Windows/macOS. I/O nativo do Docker Engine, até 10× mais rápido que bind mount.

---

3. Setup do Zero

Execute na ordem exata:

Passo 1 — Criar pastas e configurar credenciais

# Crie as pastas necessárias no host
mkdir -p src/app/code src/app/design src/app/etc src/var src/pub/media src/pub/static

# Configure as variáveis de ambiente
cp .env.example .env

Edite .env e preencha:

MAGENTO_PUBLIC_KEY=sua_chave_publica    # marketplace.magento.com → Access Keys
MAGENTO_PRIVATE_KEY=sua_chave_privada

Passo 2 — Gerar certificado SSL

make ssl

macOS: importe o certificado no Keychain:

sudo security add-trusted-cert -d -r trustRoot \
    -k /Library/Keychains/System.keychain docker/nginx/certs/local.crt

Linux: sudo cp docker/nginx/certs/local.crt /usr/local/share/ca-certificates/magento-local.crt && sudo update-ca-certificates

Passo 3 — Subir os containers

make up

Aguarde o OpenSearch ficar healthy (~60s na primeira vez). Acompanhe com:

make logs

Passo 4 — Baixar o Magento via Composer

# Configura as credenciais do Marketplace dentro do container
docker compose exec -u www-data phpfpm \
    composer config -g http-basic.repo.magento.com \
    $(grep MAGENTO_PUBLIC_KEY .env | cut -d= -f2) \
    $(grep MAGENTO_PRIVATE_KEY .env | cut -d= -f2)

# Baixa o Magento (pode levar 10–15 min na primeira vez)
MSYS_NO_PATHCONV=1 docker compose exec -u www-data phpfpm \
    composer create-project \
    --repository-url=https://repo.magento.com/ \
    magento/project-community-edition=2.4.7-p4 \
    /var/www/html \
    --no-interaction

Passo 5 — Instalar o Magento

make install

Passo 6 — Otimizar para desenvolvimento

make optimize

Passo 7 — Desativar 2FA (dev only)

make disable-2fa

Pronto. Acesse:

• Loja: https://localhost
• Admin: https://localhost/admin_dev — admin / Admin123!

---

4. Referência de Comandos

make help          # Lista todos os comandos disponíveis

# ── Ambiente ──────────────────────────────────────────────────────────────
make up            # Sobe containers em background (com build)
make down          # Para e remove containers (volumes preservados)
make clean         # Para, remove containers E volumes (reset total)
make restart       # Reinicia todos os serviços
make logs          # Tail de todos os logs
make ssl           # Gera certificado SSL auto-assinado

# ── Magento ───────────────────────────────────────────────────────────────
make cc            # cache:clean + cache:flush
make upgrade       # setup:upgrade + setup:di:compile
make compile       # setup:di:compile (mais rápido, sem upgrade)
make static        # setup:static-content:deploy pt_BR en_US
make reindex       # indexer:reindex
make mode-dev      # deploy:mode:set developer
make disable-2fa   # Desativa 2FA no Admin
make optimize      # Static sign off + caches seletivos

# ── Shell / Debug ─────────────────────────────────────────────────────────
make shell         # Shell www-data no container PHP
make xdebug-on     # Ativa Xdebug (porta 9003)
make xdebug-off    # Desativa Xdebug

# ── Composer ──────────────────────────────────────────────────────────────
make composer require vendor/pacote
make composer update

---

5. Xdebug

O Xdebug está instalado mas desabilitado por padrão.

make xdebug-on    # Recria o container phpfpm com XDEBUG_MODE=debug
make xdebug-off   # Recria o container phpfpm com XDEBUG_MODE=off

PHPStorm

1. Settings → PHP → Servers: localhost, porta 443, ative "Use path mappings"
2. Mapeamento: src/ (local) → /var/www/html (remoto)
3. Settings → PHP → Debug: porta 9003
4. Run → Start Listening for PHP Debug Connections

VS Code — .vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [{
    "name": "Listen for Xdebug",
    "type": "php",
    "request": "launch",
    "port": 9003,
    "pathMappings": { "/var/www/html": "${workspaceFolder}/src" }
  }]
}

---

6. Desenvolvimento de Módulos

src/app/code e src/app/design são bind mounts diretos — qualquer edição local aparece imediatamente no container.

O que rodar após cada tipo de alteração

Arquivo alterado	Comando
.phtml, layout .xml	make cc (em modo developer, muitas vezes desnecessário)
etc/di.xml, Plugin, Block	make compile + make cc
etc/module.xml, db_schema.xml	make upgrade + make cc

Criar novo módulo

mkdir -p src/app/code/Vendor/Module/etc

src/app/code/Vendor/Module/etc/module.xml:

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Vendor_Module"/>
</config>

src/app/code/Vendor/Module/registration.php:

<?php
use Magento\Framework\Component\ComponentRegistrar;
ComponentRegistrar::register(ComponentRegistrar::MODULE, 'Vendor_Module', __DIR__);

make upgrade
make cc

---

7. Portas Expostas

Serviço	Porta	URL
Nginx HTTP	80	→ redireciona HTTPS
Nginx HTTPS	443	https://localhost
MySQL	3306	localhost:3306
OpenSearch	9200	http://localhost:9200
Redis	6380	localhost:6380
RabbitMQ AMQP	5672	—
RabbitMQ UI	15672	http://localhost:15672
Mailpit SMTP	1025	—
Mailpit UI	8025	http://localhost:8025