Docker Compose en Dokploy

Docker Compose en Dokploy permite desplegar aplicaciones multi-contenedor como una unidad. Es ideal para stacks que combinan API, frontend, base de datos, cache y otros servicios que necesitan comunicarse entre si.

Cuando usar Docker Compose en Dokploy

Usa Compose cuando tu aplicacion necesita:

• Multiples servicios que se comunican entre si (API + DB + cache)
• Un stack completo definido como codigo
• Servicios con dependencias de arranque (depends_on)
• Volumenes compartidos entre contenedores
• Redes internas aisladas

Si solo necesitas deployar un unico contenedor, usa Application con Nixpacks o Dockerfile. Compose agrega complejidad que solo vale la pena con multiples servicios.

Crear un servicio Compose desde el panel

1. Ve a tu proyecto en Dokploy
2. Clic en Create Service
3. Selecciona Compose (en lugar de Application o Database)
4. Asigna un nombre descriptivo, por ejemplo mi-stack-fullstack
5. Selecciona la fuente del codigo:
   • GitHub: Repositorio que contiene el docker-compose.yml
   • Raw: Pegar el contenido del compose directamente en el editor

Fuente desde GitHub

Si tu repositorio contiene un docker-compose.yml en la raiz, Dokploy lo detecta automaticamente. Si esta en otra ubicacion, configura el Compose Path:

./infra/docker-compose.yml
./docker/docker-compose.prod.yml

Fuente Raw (editor inline)

Dokploy permite escribir o pegar el contenido del compose directamente en un editor dentro del panel. Esto es util para stacks simples o cuando no quieres mantener un repositorio separado.

Ejemplo: app full-stack (API + frontend + base de datos)

Un stack tipico con una API en Node.js, un frontend en Nginx y PostgreSQL:

version: "3.8"

services:
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: miapp
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U admin"]
      interval: 10s
      timeout: 5s
      retries: 5

  api:
    build:
      context: ./api
      dockerfile: Dockerfile
    environment:
      DATABASE_URL: postgresql://admin:${DB_PASSWORD}@db:5432/miapp
      NODE_ENV: production
      PORT: 3000
    depends_on:
      db:
        condition: service_healthy
    ports:
      - "3000:3000"

  web:
    build:
      context: ./web
      dockerfile: Dockerfile
    depends_on:
      - api
    ports:
      - "80:80"

volumes:
  pgdata:

Variables de entorno en Compose

Las variables referenciadas con ${VARIABLE} se configuran en la seccion Environment del servicio Compose en Dokploy. Agrega:

DB_PASSWORD=mi_password_seguro

Dokploy inyecta estas variables antes de ejecutar docker compose up.

Estructura del repositorio

Para el ejemplo anterior, la estructura seria:

mi-stack/
  docker-compose.yml
  api/
    Dockerfile
    src/
    package.json
  web/
    Dockerfile
    nginx.conf
    dist/

Cada servicio con build necesita su propio directorio con un Dockerfile. Los servicios que usan image (como db) no necesitan directorio.

Seleccionar servicios individuales en la terminal

Dokploy expone una terminal web para cada servicio Compose. Para acceder:

1. Ve al servicio Compose en tu proyecto
2. En la seccion Overview, veras la lista de servicios definidos en el compose
3. Clic en un servicio especifico (por ejemplo, api)
4. Ve a la pestana Terminal
5. Selecciona el contenedor del servicio en el dropdown

Desde la terminal puedes ejecutar comandos dentro del contenedor:

# Dentro del contenedor api
node -v
npm run migrate
npm run seed

# Dentro del contenedor db
psql -U admin -d miapp
\dt
SELECT count(*) FROM users;

Tambien puedes acceder via SSH al servidor y usar Docker directamente:

# Listar contenedores del compose
docker compose -p <nombre-proyecto> ps

# Ejecutar comando en un servicio
docker compose -p <nombre-proyecto> exec api sh

# Ver logs de un servicio especifico
docker compose -p <nombre-proyecto> logs -f api

El nombre del proyecto en Docker Compose lo asigna Dokploy internamente. Puedes verlo en los logs de deployment.

Monitoring por servicio

Dokploy ofrece metricas individuales para cada servicio dentro del compose:

Logs

En la seccion Logs del servicio Compose, selecciona el servicio especifico del dropdown. Puedes filtrar por:

• Servicio individual (api, db, web)
• Todos los servicios combinados
• Rango de tiempo

Metricas de recursos

Para cada contenedor dentro del compose, Dokploy muestra:

• CPU: Uso porcentual y grafico temporal
• Memoria: Uso actual vs limite
• Red: Trafico entrante y saliente
• Disco: Uso de volumenes

Health checks

Si defines healthcheck en el compose, Dokploy muestra el estado de salud de cada servicio en la vista general. Los estados posibles:

• healthy: El healthcheck pasa correctamente
• unhealthy: El healthcheck falla repetidamente
• starting: El contenedor aun esta arrancando

Volumenes persistentes

Los volumenes definidos en el compose persisten entre deploys. Dokploy no elimina los volumenes nombrados al redesplegar:

volumes:
  pgdata:        # Persiste entre deploys
  redis-data:    # Persiste entre deploys

Para volumenes que necesitan backup, configura una tarea de backup en Dokploy o usa la funcionalidad nativa de backup de la base de datos.

Redes en Compose

Por defecto, Docker Compose crea una red interna para todos los servicios del stack. Los servicios se comunican usando el nombre del servicio como hostname:

services:
  api:
    environment:
      # "db" es el nombre del servicio, resuelve a la IP interna
      DATABASE_URL: postgresql://admin:pass@db:5432/miapp
      # "redis" tambien resuelve internamente
      REDIS_URL: redis://redis:6379

  db:
    image: postgres:17-alpine

  redis:
    image: valkey/valkey:8-alpine

Si necesitas que un servicio del compose se comunique con otro servicio de Dokploy (fuera del compose), usa la red de Dokploy:

services:
  api:
    networks:
      - default
      - dokploy-network

networks:
  dokploy-network:
    external: true

Diferencias entre Compose en Dokploy vs terminal directa

Aspecto	Dokploy	Terminal directa
UI/Dashboard	Panel visual con metricas	Solo CLI
SSL/Dominios	Automatico via Traefik	Configuracion manual
Variables de entorno	Gestion centralizada con encriptacion	Archivos .env en disco
Deployments	Historial, rollback, logs	Manual con docker compose up -d
Volumenes	Gestion visual	Solo docker volume ls
Redes	Integracion con red de Dokploy	Redes aisladas por defecto
Escalado	Desde el panel	docker compose up --scale api=3
Healthchecks	Visualizacion en dashboard	docker compose ps
Actualizaciones	Redeploy con un clic o auto-deploy	docker compose pull && up -d

Limitaciones de Compose en Dokploy

• No soporta todos los campos de Docker Compose (por ejemplo, deploy.resources puede no aplicar)
• El escalado horizontal es limitado comparado con Docker Swarm
• Los volumenes bind-mount (./data:/data) pueden tener problemas de permisos
• El path del compose debe ser relativo al repositorio

Ejemplo: stack con cache y worker

Un patron comun con Redis como cache y un worker de background:

version: "3.8"

services:
  api:
    build: ./api
    environment:
      REDIS_URL: redis://cache:6379
      DATABASE_URL: postgresql://app:${DB_PASS}@db:5432/prod
    ports:
      - "3000:3000"
    depends_on:
      - db
      - cache

  worker:
    build: ./api
    command: ["node", "dist/worker.js"]
    environment:
      REDIS_URL: redis://cache:6379
      DATABASE_URL: postgresql://app:${DB_PASS}@db:5432/prod
    depends_on:
      - db
      - cache

  cache:
    image: valkey/valkey:8-alpine
    volumes:
      - cache-data:/data

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: prod
      POSTGRES_USER: app
      POSTGRES_PASSWORD: ${DB_PASS}
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
  cache-data:

El servicio worker usa la misma imagen que api pero con un comando diferente. Comparten la conexion a base de datos y cache.

---

Anterior: Capitulo 7: Dockerfile y Builds Personalizados | Siguiente: Capitulo 9: Fuentes de Deploy