Stack Dev Docker en VPS: entorno listo para programar

Un entorno de desarrollo local funciona, pero sigue ligado a una sola máquina: cambiar de equipo, incorporar a un nuevo colaborador o acceder desde otro país se convierten en fricciones. Al centralizar su stack Docker en un VPS, dispone de un servidor de desarrollo compartido, siempre encendido, accesible por SSH o desde el navegador esté donde esté. También gana en reproducibilidad: cada servicio se define en un archivo docker-compose.yml, lo que elimina el famoso problema de «en mi máquina funciona».

Un stack completo con PostgreSQL, Redis, Nginx y una aplicación consume en la práctica 4 GB de RAM como mínimo — por debajo, el OOM killer de Docker interrumpe PostgreSQL o Redis en mitad de una migración sin ningún mensaje de error a nivel de aplicación. El VPS debe funcionar con Ubuntu 22.04 LTS o Debian 12, con Docker Engine 26+ y Docker Compose v2.22+ instalados (el comando se escribe docker compose, sin guión). Verifique la versión con docker compose version: la funcionalidad watch usada más adelante requiere v2.22 como mínimo, lanzada en septiembre de 2023.

El stack de referencia de ServOrbit reúne seis servicios complementarios.

Nginx actúa como reverse proxy frontal: recibe las peticiones HTTP en el puerto 80 y las enruta hacia PHP-FPM (vía FastCGI) o hacia un servidor Node.js. La configuración nginx/default.conf se monta como volumen para poder editarse sin reconstruir la imagen.

PHP-FPM 8.3 (o Node.js 22 según el perfil del stack) ejecuta el código de la aplicación. Ambas variantes están disponibles en el Marketplace de ServOrbit; el docker-compose.yml incluye los dos servicios — desactive el que no necesite con profiles.

PostgreSQL 16 almacena los datos persistentes. El puerto 5432 no está expuesto en el host por defecto — solo la red interna de Docker dev_net tiene acceso, lo que evita cualquier exposición accidental en la IP pública del VPS.

Redis 7 actúa como caché y broker de mensajes. Como PostgreSQL, permanece en la red interna (puerto 6379) y es accesible desde el código de la aplicación mediante el nombre de servicio redis.

Mailpit 1.x sustituye a un servidor SMTP real en desarrollo: captura todos los correos salientes y los expone en una interfaz web en el puerto 8025. No se requiere ninguna configuración SMTP especial en el lado de la aplicación — simplemente apunte a mailpit:1025.

Adminer (puerto 8080) ofrece una interfaz web ligera para gestionar PostgreSQL o MySQL sin un cliente pesado. Solo es accesible desde la propia máquina o mediante un SSH tunnel.

El docker-compose.yml del stack declara tres volúmenes con nombre — postgres_data, redis_data y app_data — montados respectivamente en /var/lib/postgresql/data, /data y /var/www/html. Estos volúmenes sobreviven a un docker compose down: los datos de la base y los archivos subidos permanecen intactos entre reinicios.

Todos los servicios comparten la red interna dev_net de tipo bridge. Nginx es el único servicio que expone un puerto en el host (80); los demás permanecen aislados y se comunican por nombre de servicio — postgres, redis, mailpit.

Las variables sensibles (contraseña de PostgreSQL, clave secreta de la aplicación) nunca se escriben directamente en docker-compose.yml. Se leen desde /opt/docker-dev-stack/.env mediante la directiva env_file. Este archivo está excluido del repositorio Git mediante .gitignore. Las variables de entorno no sensibles (puerto, versión de PHP, nombre de la base) pueden aparecer directamente en el archivo Compose bajo la clave environment, para que sean visibles al revisar el código.

PostgreSQL, Adminer y Redis no están expuestos en la IP pública del VPS. Para acceder a ellos desde su equipo local, abra un SSH tunnel: ssh -L 5432:localhost:5432 -L 8080:localhost:8080 root@<IP_VPS> crea dos reenvíos locales — el puerto 5432 de su portátil apunta a PostgreSQL y el 8080 a Adminer. Su cliente SQL habitual se conecta entonces en localhost:5432 como si la base de datos estuviera funcionando en local.

Para los servicios HTTP (Nginx, Mailpit), hay dos opciones. Si dispone de un nombre de dominio, configure un registro A que apunte a la IP del VPS y ajuste Nginx para servir dev.yourdomain.com en HTTP plano (sin TLS, ya que es un entorno de desarrollo). Si trabaja sin dominio, el SSH tunnel es suficiente: ssh -L 8025:localhost:8025 root@<IP_VPS> da acceso a Mailpit en localhost:8025.

En desarrollo, el archivo .env centraliza todos los secretos. En producción, los secretos de Docker (docker secret) o un gestor de secretos externo (Vault, AWS Secrets Manager) sustituyen al archivo plano — un .env versionado por accidente expone credenciales en el historial de Git.

Los límites de recursos (deploy.resources.limits) merecen configurarse desde el desarrollo: PostgreSQL puede consumir toda la RAM disponible si una consulta se desvía. Comience con memory: 512m en PostgreSQL, memory: 256m en Redis y memory: 256m en PHP-FPM, y ajuste según los perfiles de uso reales.

Nunca monte el socket de Docker (/var/run/docker.sock) en un contenedor de aplicación salvo que sea estrictamente necesario: un contenedor con acceso al socket puede lanzar otros contenedores con privilegios de root en el host. En desarrollo el riesgo es limitado, pero los hábitos adquiridos aquí suelen reproducirse en producción.

Puerto ya en uso. El error Bind for 0.0.0.0:80 failed: port is already allocated indica que un servicio del host (Apache, nginx del sistema) ya está escuchando en el puerto 80. Detenga el servicio del sistema (systemctl stop nginx o systemctl stop apache2) o cambie el puerto del host en docker-compose.yml ("8080:80") y acceda al stack en el puerto 8080.

Permisos de volumen. El error Permission denied en un volumen montado suele deberse a un uid/gid del contenedor diferente al del host. Añada user: "1000:1000" en el servicio afectado, o cambie los permisos del directorio del host con chown -R 1000:1000 /opt/docker-dev-stack/app.

Red bridge no encontrada. El mensaje network dev_net declared as external, but could not be found aparece si usa external: true en una red aún no creada. Elimine external: true: Docker Compose crea la red automáticamente en el primer docker compose up.

RAM insuficiente. PostgreSQL muestra FATAL: out of memory o se reinicia en bucle si el VPS está subdimensionado. Compruebe con free -m: deben estar disponibles al menos 4 GB para el stack completo. Reduzca shared_buffers en la configuración de PostgreSQL (command: postgres -c shared_buffers=128MB) o pase a un plan VPS superior.