Docker Compose para entornos locales

Las aplicaciones PHP reales nunca son solo PHP: necesitan una base de datos, una caché y, a veces, una cola y un capturador de correo. Docker Compose declara todos estos componentes como servicios en un solo archivo y los conecta a una red compartida para que puedan encontrarse por nombre.

En esta lección creará un stack local completo: PHP-FPM + nginx + MySQL + Redis, con volúmenes, comprobaciones de estado y orden de dependencias.

Un archivo de Compose enumera los servicios bajo services:. Cada uno puede compilarse mediante build a partir de un Dockerfile o descargar una image. Compose crea una red predeterminada en la que cada servicio está disponible mediante su clave: su aplicación PHP se conecta a MySQL usando el host db, no localhost.

FPM se comunica mediante FastCGI por el puerto 9000, no mediante HTTP. nginx termina las conexiones HTTP y reenvía las solicitudes .php a app:9000. La configuración de nginx hace referencia al servicio PHP mediante su nombre de Compose.

El servicio nginx monta el mismo código, para resolver SCRIPT_FILENAME, y la configuración; publica el puerto 80 y depende de app. Ambos comparten /app para que las rutas coincidan a ambos lados de FastCGI.

Los sistemas de archivos de los contenedores son efímeros. Los volúmenes con nombre conservan los archivos de la base de datos después de ejecutar docker compose down. Los bind mounts (./:/app) sincronizan en tiempo real el código del host durante el desarrollo. Use volúmenes con nombre para los datos con estado y bind mounts para el código fuente.

depends_on por sí solo solo espera a que el contenedor se inicie, no a que MySQL acepte conexiones. Añada un healthcheck y use condition: service_healthy para que su aplicación espere hasta que la base de datos esté realmente lista.

Compose carga automáticamente un archivo .env contiguo para interpolar variables, y permite pasar la configuración de la aplicación mediante environment o env_file. Mantenga los secretos fuera del archivo de Compose confirmado en el repositorio; haga referencia a variables en su lugar.

Dentro de la red, los nombres de host son los nombres de los servicios. Su código PHP se conecta directamente a db y redis. Este fragmento analiza un DSN como lo haría una capa de configuración y muestra cómo el nombre del servicio de Compose llega a la cadena de conexión.

Monte la configuración de Xdebug solo localmente, mediante el destino de compilación dev. Apunte client_host a host.docker.internal para que el depurador pueda llegar a su IDE en el host. Nunca incluya Xdebug en producción: reduce drásticamente el rendimiento.

docker compose run inicia un contenedor efímero para migraciones, pruebas o Composer; exec ejecuta comandos dentro de un servicio que ya está en ejecución. Use run --rm para estas tareas, de modo que el contenedor desechable se elimine al terminar.

Compose combina automáticamente docker-compose.yml con docker-compose.override.yml. Mantenga los valores predeterminados orientados a producción en el archivo base y coloque los volúmenes, puertos y Xdebug exclusivos de desarrollo en el override; así, CI utiliza el archivo base y los desarrolladores obtienen extras automáticamente.

¿Por qué no es suficiente un depends_on: [db] simple antes de ejecutar las migraciones?

Ensambló un stack local con Compose: PHP-FPM detrás de nginx, con FastCGI hacia app:9000; MySQL y Redis disponibles mediante el nombre del servicio; volúmenes con nombre para la persistencia; comprobaciones de estado que condicionan depends_on; configuración basada en variables de entorno; Xdebug en un override exclusivo de desarrollo; y comandos puntuales mediante run/exec.

Recuerde: los nombres de servicio son nombres de host DNS, los archivos de override mantienen los extras de desarrollo fuera de CI y las comprobaciones de estado son mejores que un orden de inicio ingenuo.