Entorno de Desarrollo Symfony con Docker: Guía Completa

Tener un entorno de desarrollo consistente y reproducible es fundamental para cualquier proyecto serio. En este tutorial te muestro cómo usar mi Boilerplate Docker para Symfony que te ahorrará horas de configuración.

Repositorio: github.com/walteru/Boilerplate-Docker-Symfony

¿Qué incluye este Boilerplate?

Servicio	Puerto	Descripción
PHP 8.2 + Apache	`localhost:1500`	Servidor web con todas las extensiones necesarias
MySQL 8.0	`localhost:1000`	Base de datos con charset UTF8MB4
MailHog	`localhost:8025`	Interfaz web para capturar emails de prueba
Xdebug 3	Puerto 9003	Depuración paso a paso en VS Code

Además incluye: Composer, Node.js 18, Symfony CLI, Yarn y alias útiles para la terminal.

Requisitos Previos

Antes de comenzar, asegúrate de tener instalado:

Docker >= 20.10
Docker Compose >= 2.0
Make (viene preinstalado en Linux/macOS)
Git

# Verificar instalaciones
docker --version
docker compose version
make --version

Paso 1: Clonar el Repositorio

git clone https://github.com/walteru/Boilerplate-Docker-Symfony.git mi-proyecto
cd mi-proyecto

Paso 2: Configurar Variables de Entorno

Copia el archivo de ejemplo y ajusta según tus necesidades:

cp .env.example .env

El archivo .env contiene:

# Puertos (cámbialos si hay conflictos)
APP_PORT=1500
MYSQL_PORT=1000
MAILHOG_WEB_PORT=8025
MAILHOG_SMTP_PORT=1025

# MySQL
MYSQL_ROOT_PASSWORD=root
MYSQL_DATABASE=project_database

# Xdebug (ver tabla abajo)
XDEBUG_CLIENT_HOST=172.17.0.1
XDEBUG_CLIENT_PORT=9003

Configuración de Xdebug según tu SO

Sistema	XDEBUG_CLIENT_HOST
Linux	Ejecuta `ip a \| grep docker0` y usa esa IP
macOS	`host.docker.internal`
Windows (WSL2)	`host.docker.internal`

Paso 3: Construir e Iniciar

# Construir las imágenes Docker
make build

# Iniciar los contenedores
make start

# Verificar que todo está corriendo
make status

Deberías ver algo como:

NAME              STATUS          PORTS
symfony-app       Up (healthy)    0.0.0.0:1500->80/tcp
symfony-mysql     Up (healthy)    0.0.0.0:1000->3306/tcp
symfony-mailhog   Up              0.0.0.0:8025->8025/tcp

Paso 4: Verificar Funcionamiento

Crea un archivo de prueba:

echo "<?php phpinfo();" > src/public/index.php

Abre http://localhost:1500 en tu navegador. Deberías ver la página de información de PHP.

Paso 5: Crear tu Proyecto Symfony

Opción A: Nuevo proyecto desde cero

# Entrar al contenedor
make ssh-app

# Crear proyecto Symfony (dentro del contenedor)
symfony new . --webapp

# Salir del contenedor
exit

Opción B: Clonar proyecto existente

# Clonar dentro de src/
cd src
git clone git@github.com:tu-usuario/tu-proyecto.git .
cd ..

# Instalar dependencias
make composer-install

Paso 6: Configurar Symfony para usar los Servicios

Edita el archivo src/.env o src/.env.local:

# Base de datos
DATABASE_URL="mysql://root:root@mysql:3306/project_database?serverVersion=8.0"

# Correo (MailHog captura todos los emails)
MAILER_DSN=smtp://mailhog:1025

Comandos Útiles del Makefile

El boilerplate incluye un Makefile completo. Aquí los comandos más útiles:

Gestión de Contenedores

make start       # Iniciar contenedores
make stop        # Detener contenedores
make restart     # Reiniciar
make status      # Ver estado
make logs        # Ver todos los logs
make logs-app    # Solo logs de PHP/Apache

Acceso a Contenedores

make ssh-app     # Terminal en contenedor PHP
make ssh-db      # Terminal en contenedor MySQL

Desarrollo con Composer

make composer-install                    # Instalar dependencias
make composer-update                     # Actualizar dependencias
make composer-require PKG=doctrine/orm   # Agregar paquete

Base de Datos

make migrations       # Ejecutar migraciones
make schema-validate  # Validar esquema Doctrine
make schema-update    # Actualizar esquema

Tests

make tests            # Ejecutar PHPUnit
make tests-coverage   # Tests con reporte de cobertura

Configurar Depuración en VS Code

1. Instalar extensión Dev Containers

En VS Code, instala la extensión Dev Containers de Microsoft.

2. Conectar al contenedor

Abre Remote Explorer en la barra lateral
Busca el contenedor symfony-app
Haz clic en Attach to Container

3. Instalar PHP Debug

Una vez dentro del contenedor, instala la extensión PHP Debug (Xdebug).

4. Crear launch.json

En el contenedor, ve a Run and Debug (Ctrl+Shift+D) y crea un archivo launch.json:

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

5. Depurar

Coloca breakpoints en tu código
Presiona F5 para iniciar el listener
Haz una petición a tu aplicación
El debugger se detendrá en tus breakpoints

Alias Disponibles en el Contenedor

Cuando estés dentro del contenedor (make ssh-app), tienes estos alias:

Alias	Comando
`sf`	`bin/console`
`cc`	`bin/console cache:clear`
`dsv`	`bin/console doctrine:schema:validate`
`dsu`	`bin/console doctrine:schema:update`
`dmm`	`bin/console doctrine:migration:migrate`

Ejemplo:

# En lugar de escribir:
php bin/console cache:clear

# Solo escribes:
cc

Probar el Envío de Emails

MailHog captura todos los emails enviados desde tu aplicación. Es perfecto para desarrollo.

Configura Symfony para usar MailHog:
```
MAILER_DSN=smtp://mailhog:1025
```
Envía un email desde tu código (o usa el comando de test de Symfony)
Abre http://localhost:8025 para ver los emails capturados

Solución de Problemas Comunes

Los contenedores no inician

# Ver logs detallados
make logs

# Reconstruir desde cero
make clean
make build
make start

Error de permisos en archivos

# Verificar UID
make check

# Reconstruir con UID correcto
make rebuild

Xdebug no conecta

Verifica XDEBUG_CLIENT_HOST en .env
Asegura que el puerto 9003 no esté bloqueado por firewall
Reinicia: make restart

MySQL no inicia

# Ver logs específicos
make logs-db

# Si persiste, limpiar volumen
make clean
make build
make start

Estructura del Proyecto

mi-proyecto/
├── docker/
│   ├── database/
│   │   ├── Dockerfile       # Imagen MySQL
│   │   └── databases.sql    # Script inicial
│   └── php-apache/
│       ├── Dockerfile       # Imagen PHP 8.2 + Apache
│       ├── default.conf     # VirtualHost
│       ├── php.ini          # Config PHP
│       └── xdebug.ini       # Config Xdebug
├── src/                     # Tu proyecto Symfony
├── .env                     # Variables de entorno
├── docker-compose.yml
├── Makefile
└── README.md

Conclusión

Con este boilerplate tienes un entorno de desarrollo profesional listo en minutos:

Reproducible: Cualquier miembro del equipo puede levantar el mismo entorno
Aislado: No contamina tu sistema con instalaciones globales
Completo: PHP, MySQL, emails de prueba y depuración incluidos
Productivo: Makefile con comandos para las tareas comunes

El repositorio está en constante mejora. Si encuentras algún problema o tienes sugerencias, ¡las contribuciones son bienvenidas!

Repositorio: github.com/walteru/Boilerplate-Docker-Symfony