Despliegue PHP con Docker Compose: tutorial completo DNMP (Nginx+MySQL+PHP)

En la terminal, el error que no para de aparecer: “Nginx no encuentra el socket de PHP-FPM”. El octavo de esta noche. Instalé LNMP a mano, toqué nginx.conf, php-fpm.conf y my.cnf, reinicié los servicios una docena de veces y el entorno sigue sin arrancar.

El compañero de al lado dice: “En mi equipo funciona perfecto, ¿seguro que no es la versión de PHP?”

Él usa PHP 7.4; yo instalé 8.1. Él tiene MySQL 5.7; yo, sin querer, 8.0. No es de extrañar que el código no corra.

Cada miembro del equipo tiene un entorno distinto. Los nuevos tardan medio día en configurar, con ayuda uno a uno de los veteranos. El código funciona en el equipo A y explota en el B. El despliegue al servidor es una lotería.

Probé Docker Compose para desplegar DNMP y esos problemas desaparecieron. En 10 minutos tienes Nginx, MySQL y PHP; todo el equipo usa el mismo archivo de configuración y ya nadie dice “en mi máquina funciona”.

Por qué elegir Docker Compose para desplegar PHP

Tres dolores del despliegue LNMP tradicional

Dolor 1: instalación manual tediosa, un error y todo se complica

¿Recuerdas la primera vez que instalaste LNMP? Primero apt-get install nginx, luego php-fpm, después MySQL. Y luego tocar configuraciones: location en nginx.conf, extensiones en php.ini, parámetros en my.cnf.

Tres archivos en directorios distintos: /etc/nginx/, /etc/php/, /etc/mysql/. Un error y el servicio no arranca. Para depurar hay que revisar logs de Nginx, PHP-FPM y MySQL hasta marearse.

Conozco a alguien que puso listen = /run/php/php7.4-fpm.sock en lugar de listen = 127.0.0.1:9000 en php-fpm.conf; Nginx no encontraba PHP y tardó tres horas en localizarlo.

Dolor 2: compatibilidad de versiones que vuelve loco

Siempre hay quien se queda en una versión antigua. Proyectos legacy en PHP 5.6, proyectos nuevos en PHP 8.1. El GROUP BY de MySQL 5.7 falla en 8.0 porque 8.0 activa ONLY_FULL_GROUP_BY por defecto.

Peor aún, cada miembro tiene versiones distintas:

• El Mac de Li: PHP 7.4 + MySQL 5.7
• El Ubuntu de Wang: PHP 8.0 + MySQL 8.0
• El Windows del becario: PHP 8.1 + MariaDB 10.6

El código corre en el equipo de Li, subes a Git y Wang lo baja con errores. El entorno de pruebas es otra versión; producción, otra más. ¿Qué puede salir mal?

Dolor 3: colaboración en equipo a ritmo de tortuga

El primer día del nuevo, el veterano dedica medio día a enseñarle el entorno:

1. Instalar Nginx (20 min)
2. Instalar PHP y extensiones (30 min, a veces compilando)
3. Instalar MySQL (15 min)
4. Configurar la comunicación entre servicios (1 h, con trampas)
5. Importar datos de prueba (10 min)

Con suerte, por la tarde escribe código. Si no, mañana.

En una startup, por inconsistencia de entornos, un registro de usuario pasó en desarrollo y en producción falló con “conexión a base de datos fallida”. En dev MySQL root no tenía contraseña; en prod sí, y olvidamos actualizar la config. Rollback de madrugada; el jefe casi explota.

Tres ventajas de Docker Compose

Ventaja 1: configuración como código, un archivo para todo el equipo

Docker Compose concentra todo en docker-compose.yml:

• ¿Qué versión de Nginx? (nginx:1.25-alpine)
• ¿Qué extensiones PHP? (mysqli, pdo_mysql, redis)
• ¿Parámetros de MySQL? (my.cnf unificado)
• ¿Cómo se comunican los servicios? (resolución DNS automática)

Subes el archivo a Git y todos bajan el mismo entorno. ¿Nuevo en el equipo? Clona el proyecto, docker-compose up -d, un café y listo.

Ya no preguntas “¿cuál es la contraseña de MySQL?”, “¿dónde está php.ini?” o “¿me pasas la config de Nginx?”. Un archivo resuelve todo.

Ventaja 2: arranque y destrucción con un comando, limpio

Arrancar todos los servicios:

docker-compose up -d

Detener y eliminar contenedores:

docker-compose down

¿Cambiar versión de PHP? Una línea: image: php:7.4-fpm → image: php:8.1-fpm, vuelves a hacer up y listo.

A diferencia del método tradicional, no desinstalas PHP viejo ni temes borrar algo crítico del sistema. Los contenedores están aislados; borras y punto.

Ventaja 3: aislamiento y coexistencia de versiones

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

¿Correr PHP 7.4 y 8.1 a la vez? A mano instalas dos PHP, dos puertos, ajustas Nginx con distintos fastcgi_pass. Un rollo.

Con Docker Compose defines dos servicios PHP:

php74:
  image: php:7.4-fpm

php81:
  image: php:8.1-fpm

En Nginx apuntas al que necesites. Proyecto viejo en php74, nuevo en php81, sin interferencias.

El proyecto DNMP más popular en GitHub (imeepo/dnmp) supera 5000 estrellas: no es experimental, es una solución probada por muchos equipos.

Arquitectura DNMP en detalle

Qué es DNMP

DNMP es LNMP en Docker. Cada letra es un componente:

• D = Docker: plataforma de contenedores, cada servicio en su “caja”
• N = Nginx: servidor web, recibe HTTP y reenvía a PHP
• M = MySQL: base relacional (también MariaDB o PostgreSQL)
• P = PHP: PHP-FPM, ejecuta el código

Además suele haber:

• Redis: caché para lecturas rápidas
• PHPMyAdmin: administración visual de MySQL

En LNMP tradicional todo va en el sistema mezclado. DNMP pone cada servicio en un contenedor, como VMs ligeras.

Orquestación de servicios

Imagina un equipo de sonido: amplificador, altavoces, reproductor. Cada pieza funciona sola pero necesita cables para trabajar juntas.

DNMP es igual: Nginx, PHP y MySQL son contenedores independientes unidos por la red Docker.

Flujo de peticiones:

1. El navegador envía HTTP a localhost:80
2. Nginx recibe y detecta un archivo PHP
3. Nginx reenvía al contenedor PHP por el puerto 9000 (servicio php)
4. PHP ejecuta; si necesita datos, conecta a MySQL (servicio mysql)
5. PHP devuelve el resultado a Nginx
6. Nginx entrega HTML al navegador

Comunicación:
Docker Compose crea una red bridge y conecta todos los servicios. Cada uno tiene nombre de servicio y Docker resuelve DNS.

Para conectar a MySQL desde PHP no uses 127.0.0.1:3306; escribe mysql:3306. Docker resuelve mysql a la IP del contenedor.

Mapeo de puertos:

• Nginx:80 → host:80 (localhost muestra el sitio)
• MySQL:3306 → host:3306 (Navicat y similares)
• PHPMyAdmin:80 → host:8080 (localhost:8080)
• Redis:6379 → host:6379

Volúmenes:
¿Se pierden datos al borrar contenedores? No, con volúmenes:

• ./www → /var/www/html en Nginx y PHP (código)
• ./mysql/data → /var/lib/mysql en MySQL (datos)
• ./nginx/logs → /var/log/nginx en Nginx (logs)

Aunque recrees contenedores, los datos siguen en el host.

Estructura de directorios

Un proyecto DNMP típico:

dnmp/
├── docker-compose.yml       # Orquestación, define todos los servicios
├── .env                     # Variables (contraseñas, puertos)
├── .gitignore               # .env no se sube
├── nginx/
│   ├── conf.d/
│   │   └── default.conf    # Sitio (raíz, reglas PHP)
│   └── logs/
│       ├── access.log
│       └── error.log
├── php/
│   ├── Dockerfile          # Imagen PHP (extensiones)
│   ├── php.ini             # Memoria, tamaño de subida
│   └── php-fpm.conf        # Procesos FPM
├── mysql/
│   ├── data/               # Persistencia
│   └── my.cnf              # Charset, conexiones máximas
└── www/
    └── index.php           # Prueba

Archivos clave:

• docker-compose.yml: imagen, volúmenes, puertos
• .env: p. ej. MYSQL_ROOT_PASSWORD=123456, datos sensibles aparte
• nginx/conf.d/default.conf: raíz del sitio, reglas PHP
• php/Dockerfile: mysqli, redis, etc.
• mysql/data/: datos que sobreviven al recrear contenedores

Muchos archivos, pero cada uno con un rol claro. No como LNMP clásico con configs dispersas.

Práctica en 10 minutos: DNMP desde cero

Requisitos previos

1. Instalar Docker

• Mac/Windows: Docker Desktop, incluye docker-compose
• Linux (Ubuntu):

  sudo apt update
  sudo apt install docker.io docker-compose -y
  sudo systemctl start docker
  sudo systemctl enable docker
  

2. Verificar instalación

docker --version
# Salida: Docker version 24.0.6, build xxx

docker-compose --version
# Salida: Docker Compose version v2.21.0

Si ves versiones, está listo.

3. Configuración recomendada

• RAM: mínimo 4 GB (ajustable en Docker Desktop)
• Disco: 20 GB libres (las imágenes ocupan espacio)
• Red: acceso a Docker Hub (o mirror regional si es lento)

Opción rápida: proyecto open source (recomendado)

¿Sin ganas de pelearse? Usa un proyecto listo, 10 minutos.

1. Clonar

Recomiendo imeepo/dnmp, compatible con Arm (chips Apple M):

git clone https://github.com/imeepo/dnmp.git
cd dnmp

2. Variables de entorno

cp .env.example .env

Edita .env:

# Contraseña root MySQL (no uses 123456)
MYSQL_ROOT_PASSWORD=your_strong_password

# Zona horaria
TZ=Asia/Shanghai

# Puertos (si 80 está ocupado, usa 8080)
NGINX_HTTP_PORT=80
MYSQL_PORT=3306

3. Arranque

docker-compose up -d

-d es segundo plano. La primera vez descarga imágenes; puede tardar unos minutos. Éxito si ves:

Creating network "dnmp_default" with the default driver
Creating dnmp_mysql_1 ... done
Creating dnmp_php_1   ... done
Creating dnmp_nginx_1 ... done
Creating dnmp_redis_1 ... done

4. Verificar

Abre http://localhost: deberías ver phpinfo con versión PHP y extensiones.

Nginx y PHP están arriba.

http://localhost:8080: PHPMyAdmin:

• Servidor: mysql (no localhost)
• Usuario: root
• Contraseña: la de .env

Si entras, MySQL también funciona.

5. Estado de contenedores

docker-compose ps

Algo así:

Name               Command              State           Ports
--------------------------------------------------------------------
dnmp_nginx_1   nginx -g daemon off;   Up      0.0.0.0:80->80/tcp
dnmp_php_1     php-fpm                Up      9000/tcp
dnmp_mysql_1   docker-entrypoint...   Up      0.0.0.0:3306->3306/tcp
dnmp_redis_1   redis-server           Up      6379/tcp

State en Up significa que corre.

Opción avanzada: docker-compose.yml a mano

¿Quieres entender la lógica? Escribe la config tú mismo.

1. Directorio del proyecto

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

mkdir my-dnmp && cd my-dnmp
mkdir -p nginx/conf.d php mysql/data www

2. docker-compose.yml

version: '3.8'

services:
  # Nginx
  nginx:
    image: nginx:1.25-alpine
    container_name: dnmp-nginx
    ports:
      - "80:80"
    volumes:
      - ./www:/var/www/html
      - ./nginx/conf.d:/etc/nginx/conf.d
      - ./nginx/logs:/var/log/nginx
    depends_on:
      - php
    networks:
      - dnmp-network

  # PHP
  php:
    build: ./php
    container_name: dnmp-php
    volumes:
      - ./www:/var/www/html
    networks:
      - dnmp-network

  # MySQL
  mysql:
    image: mysql:8.0
    container_name: dnmp-mysql
    ports:
      - "3306:3306"
    environment:
      MYSQL_ROOT_PASSWORD: root123456
      MYSQL_DATABASE: test_db
      TZ: Asia/Shanghai
    volumes:
      - ./mysql/data:/var/lib/mysql
    networks:
      - dnmp-network

  # Redis (opcional)
  redis:
    image: redis:7-alpine
    container_name: dnmp-redis
    ports:
      - "6379:6379"
    networks:
      - dnmp-network

networks:
  dnmp-network:
    driver: bridge

3. Dockerfile de PHP

php/Dockerfile:

FROM php:8.1-fpm

RUN apt-get update && apt-get install -y \
    libzip-dev \
    zip \
    unzip

RUN docker-php-ext-install \
    mysqli \
    pdo_mysql \
    zip \
    opcache

RUN pecl install redis && docker-php-ext-enable redis

WORKDIR /var/www/html

4. Configuración Nginx

nginx/conf.d/default.conf:

server {
    listen 80;
    server_name localhost;
    root /var/www/html;
    index index.php index.html;

    access_log /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log;

    location ~ \.php$ {
        fastcgi_pass php:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ \.(js|css|png|jpg|gif|ico)$ {
        expires 7d;
    }
}

5. Archivos de prueba

www/index.php:

<?php
phpinfo();

www/db_test.php:

<?php
$host = 'mysql';
$user = 'root';
$pass = 'root123456';
$db = 'test_db';

try {
    $pdo = new PDO("mysql:host=$host;dbname=$db", $user, $pass);
    echo "¡Conexión a base de datos exitosa!<br />";
    echo "Versión MySQL: " . $pdo->getAttribute(PDO::ATTR_SERVER_VERSION);
} catch(PDOException $e) {
    echo "Conexión fallida: " . $e->getMessage();
}

6. Arrancar

docker-compose up --build -d

--build reconstruye la imagen PHP. La primera vez tarda por descargas e instalación de extensiones.

Verificación y pruebas

1. Probar PHP

http://localhost: phpinfo con PHP 8.1 y mysqli, pdo_mysql, redis en enabled.

2. Probar base de datos

http://localhost/db_test.php: mensaje de éxito y versión MySQL.

Si falla:

• ¿MySQL arriba? docker-compose ps
• ¿host es localhost? Debe ser mysql
• ¿Contraseña correcta?

3. Estado

docker-compose ps

Todos en Up.

4. Logs

docker-compose logs php
docker-compose logs -f nginx

Los logs indican errores de sintaxis, puertos ocupados, etc.

Mejores prácticas para equipos

Control de versiones

Principio: sube la config, no los secretos

.gitignore:

# Secretos
.env

# Datos de BD (muy pesados)
mysql/data/

# Logs
nginx/logs/*.log
php/logs/*.log

# Código de negocio en otro repo
www/*
!www/.gitkeep

Archivos en Git:

git add docker-compose.yml
git add .env.example
git add nginx/conf.d/
git add php/Dockerfile
git add php/php.ini
git add mysql/my.cnf
git commit -m "feat: add DNMP environment config"
git push

Onboarding (3 minutos):

1. Clonar: git clone xxx
2. Copiar: cp .env.example .env
3. Cambiar contraseña en .env
4. Arrancar: docker-compose up -d
5. Importar: docker exec -i dnmp-mysql mysql -uroot -p < backup.sql

Listo. Sin preguntar “¿dónde está tu Nginx?” Todo está en los archivos.

Varias versiones de PHP

Escenario: legacy en 7.4, nuevo en 8.1.

Opción: varios servicios PHP en docker-compose.yml

services:
  php74:
    image: php:7.4-fpm
    container_name: dnmp-php74
    volumes:
      - ./www:/var/www/html
    networks:
      - dnmp-network

  php81:
    image: php:8.1-fpm
    container_name: dnmp-php81
    volumes:
      - ./www:/var/www/html
    networks:
      - dnmp-network

Nginx por proyecto:

nginx/conf.d/old-project.conf:

server {
    listen 80;
    server_name old.local;
    root /var/www/html/old-project;

    location ~ \.php$ {
        fastcgi_pass php74:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

nginx/conf.d/new-project.conf:

server {
    listen 80;
    server_name new.local;
    root /var/www/html/new-project;

    location ~ \.php$ {
        fastcgi_pass php81:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }
}

hosts:

127.0.0.1 old.local
127.0.0.1 new.local

http://old.local → PHP 7.4; http://new.local → PHP 8.1.

Persistencia y respaldos

La persistencia ya está con ./mysql/data → /var/lib/mysql.

Script de respaldo — scripts/backup.sh:

#!/bin/bash
BACKUP_DIR="./backups"
DATE=$(date +%Y%m%d_%H%M%S)
MYSQL_CONTAINER="dnmp-mysql"
MYSQL_USER="root"
MYSQL_PASSWORD="root123456"
DATABASE="test_db"

mkdir -p $BACKUP_DIR

echo "Iniciando respaldo de $DATABASE..."
docker exec $MYSQL_CONTAINER mysqldump -u$MYSQL_USER -p$MYSQL_PASSWORD $DATABASE > $BACKUP_DIR/${DATABASE}_${DATE}.sql

echo "Respaldo completado: $BACKUP_DIR/${DATABASE}_${DATE}.sql"

Cron:

crontab -e

# Diario a las 2:00
0 2 * * * /path/to/scripts/backup.sh

Restaurar:

docker exec -i dnmp-mysql mysql -uroot -proot123456 test_db < ./backups/test_db_20251218.sql

Problemas comunes y trampas

Problema 1: puerto ocupado

Síntoma:

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

Diagnóstico:

# Mac/Linux
lsof -i :80

# Windows
netstat -ano | findstr :80

Solución:

• Detener lo que usa el puerto 80 (Apache, IIS)
• O cambiar mapeo: NGINX_HTTP_PORT=8080 en .env, acceder por localhost:8080

Problema 2: permisos de archivos (Linux/Mac)

Síntoma:

• Nginx 403 Forbidden
• PHP Permission denied al escribir

Causa:
UID de www-data (33) en contenedor distinto al del host (p. ej. 1000).

Temporal (dev):

chmod -R 777 ./www

Correcto (ajustar UID en Dockerfile):

FROM php:8.1-fpm

RUN usermod -u 1000 www-data && groupmod -g 1000 www-data

docker-compose build php
docker-compose up -d

Problema 3: extensión PHP faltante

Síntoma:

Fatal error: Call to undefined function mysqli_connect()

Diagnóstico:

docker exec dnmp-php php -m

Solución:

RUN docker-php-ext-install mysqli pdo_mysql

docker-compose build php
docker-compose restart php

Problema 4: conexión a base de datos fallida

Síntoma:

SQLSTATE[HY000] [2002] Connection refused

Errores típicos:

• host = localhost o 127.0.0.1
• MySQL aún no listo
• Contraseña incorrecta

Correcto:

$host = 'mysql';
$user = 'root';
$pass = 'root123456';

try {
    $pdo = new PDO("mysql:host=$host;dbname=test_db", $user, $pass);
    echo "Conexión exitosa";
} catch(PDOException $e) {
    echo "Fallo: " . $e->getMessage();
}

Si sigue fallando:

docker-compose logs mysql

Busca mysqld: ready for connections.

Problema 5: contenedor sale al instante

Síntoma:

docker-compose ps
# Status Exit 1 o Exit 127

Diagnóstico:

docker-compose logs nombre_servicio

Causas:

1. Sintaxis: falta ; en Nginx, indentación incorrecta en compose (espacios, no tabs)
2. Falta MYSQL_ROOT_PASSWORD
3. Dependencia no arranca (Nginx depende de PHP caído)

Solución:

docker-compose down
docker-compose up -d

Conclusión

El valor de Docker Compose para DNMP se resume en tres puntos:

1. Ahorra tiempo: 10 minutos; tiempo para dos cafés más
2. Menos trampas: entorno unificado, sin bugs de madrugada por “en mi máquina funciona”
3. Fácil de mantener: la config es la documentación; el nuevo entiende sin tutoría

Yo instalaba LNMP a mano hasta las dos de la mañana sin éxito. Con Docker Compose: up, café, entorno listo.

Prueba 10 minutos antes de irte: clona imeepo/dnmp, siente el arranque con un comando. Luego escribe tu propio compose.

Si algo falla:

1. docker-compose logs
2. Busca en GitHub Issues
3. Abre un Issue en el repo; la comunidad responde

Docker Compose no es solo PHP: Node.js, Python, Go… La misma lógica sirve para cualquier stack.

Próximos pasos:

• Acción inmediata: git clone https://github.com/imeepo/dnmp.git y levanta tu primer DNMP
• Profundizar: documentación oficial de Docker Compose (p. ej. docker-compose.override.yml)
• Compartir: si te ayudó, pásalo a quien aún instala a mano