Cómo desplegar una app de Docker Compose en Dokploy

Dokploy es una Plataforma como Servicio (PaaS) de código abierto y autoalojable para desplegar y gestionar aplicaciones con Docker y Traefik. Tiene más de 36.300 estrellas en GitHub y lanzamientos frecuentes (actualmente en v0.29.x), y es una alternativa gratuita a Vercel, Heroku y Netlify. Para comparaciones, consulta cómo se compara Dokploy con Coolify y Kamal 2 o nuestro resumen de paneles de servidores autoalojados.

Esta guía explica cómo desplegar cualquier app de Docker Compose en Dokploy. Usaré un stack de Flowise AI + PostgreSQL como ejemplo, pero el mismo flujo de trabajo se aplica a cualquier archivo compose.

Requisitos previos

Antes de empezar, asegúrate de tener todo listo:

Los precios de los VPS subieron en todos los proveedores en 2026 — si estás reconsiderando un servidor alquilado, consulta qué cambió y cuándo gana un mini PC.

Ejemplo con Flowise: el archivo Docker Compose que desplegaremos

Aquí está el archivo compose que usaremos a lo largo de esta guía. Ejecuta Flowise AI con un backend PostgreSQL. Esta es una versión limpia: sin etiquetas de Traefik y sin dokploy-network. Dokploy gestiona la red y el enrutamiento a través de la pestaña Domains o los Isolated Deployments.

services:
  flowise-db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - flowise-db-data:/var/lib/postgresql/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 5

  flowise:
    image: flowiseai/flowise:latest
    healthcheck:
      test: wget --no-verbose --tries=1 --spider http://localhost:${PORT}
    volumes:
      - flowiseai:/root/.flowise
    environment:
      DEBUG: false
      PORT: ${PORT}
      FLOWISE_USERNAME: ${FLOWISE_USERNAME}
      FLOWISE_PASSWORD: ${FLOWISE_PASSWORD}
      APIKEY_PATH: /root/.flowise
      SECRETKEY_PATH: /root/.flowise
      LOG_LEVEL: info
      LOG_PATH: /root/.flowise/logs
      DATABASE_TYPE: postgres
      DATABASE_PORT: 5432
      DATABASE_HOST: flowise-db
      DATABASE_NAME: ${POSTGRES_DB}
      DATABASE_USER: ${POSTGRES_USER}
      DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
    restart: on-failure:5
    depends_on:
      flowise-db:
        condition: service_healthy
    entrypoint: /bin/sh -c "sleep 3; flowise start"

volumes:
  flowiseai:
    driver: local
  flowise-db-data:
    driver: local

Algunas cosas a tener en cuenta:

• Sin sección networks:. Dokploy gestiona la red por ti (a través de la pestaña Domains o los Isolated Deployments).
• Sin bloque labels:. El enrutamiento de Traefik se configura en la pestaña Domains, no en el archivo compose.
• Sin container_name. Definirlo en Dokploy causa problemas con los logs y las métricas. Dokploy genera sus propios nombres de contenedor.
• Sin clave version:. Docker Compose v2 la ignora y puede mostrar un aviso. Si traes tu propio archivo compose con version: "3.8", simplemente elimina esa línea.
• Sintaxis ${VAR_NAME}. Las variables de entorno se referencian así porque Dokploy escribe las variables definidas en la interfaz en un archivo .env. Más sobre esto en la sección de variables de entorno.

Para repasar la sintaxis de compose, consulta los comandos esenciales de Docker. La documentación oficial tiene más ejemplos en los docs de Docker Compose de Dokploy y en el ejemplo oficial.

Apunta el dominio a tu servidor (DNS)

Antes de desplegar, apunta tu dominio o subdominio al servidor de Dokploy:

• Añade un registro A en la configuración de tu DNS:
  • Nombre: el subdominio que quieras (p. ej., flowise para flowise.yourdomain.com)
  • Valor: la dirección IP de tu servidor

Método 1: usar la pestaña Domains (recomendado)

Este es el enfoque recomendado por Dokploy. Pegas tu archivo compose tal cual y luego configuras el dominio y el puerto desde la interfaz. Dokploy inyecta las etiquetas de Traefik y la configuración de red automáticamente.

Para más detalles sobre cómo funciona Traefik internamente, consulta cómo funciona Traefik como proxy inverso en Docker.

Paso 1: crea el servicio compose

1. En el panel de Dokploy, ve a Projects y crea un proyecto nuevo o selecciona uno existente.
2. Haz clic en Create Service → Compose.
3. Dale un nombre (p. ej., flowise).
4. En General, selecciona Raw como fuente.
5. Pega el archivo compose limpio de arriba.
6. Haz clic en Save.

Paso 2: añade un dominio

1. Ve a la pestaña Domains.
2. Haz clic en Add Domain.
3. Rellena los campos:
   • Domain: introduce tu dominio (p. ej., flowise.yourdomain.com)
   • Service Name: selecciona el servicio del desplegable (p. ej., flowise. Es la clave de tu archivo compose)
   • Internal Port: el puerto en el que escucha tu app dentro del contenedor (3000 para Flowise)
   • Certificate Provider: selecciona Let’s Encrypt para HTTPS automático
4. Haz clic en Save.

Dokploy inyectará las etiquetas de Traefik necesarias en el archivo compose final. No necesitas añadirlas manualmente.

Paso 3: verifica con Preview Compose

Después de configurar tu dominio, haz clic en el botón Preview Compose. Muestra el archivo compose final que Dokploy ejecutará realmente, con todas las etiquetas de Traefik inyectadas, la configuración de red y los ajustes del dominio. Es un paso de verificación crítico. Comprueba que:

• Las etiquetas de Traefik incluyen tu dominio y el puerto correcto
• Se ha inyectado dokploy-network (o una red aislada si activaste esa opción)
• No se han hecho cambios inesperados en tus servicios

Método 2: etiquetas de Traefik manuales (avanzado)

Para la mayoría de usuarios, el Método 1 es suficiente. Usa etiquetas de Traefik manuales solo cuando necesites configuración personalizada: middleware (auth, rate limiting), múltiples reglas de host, entrypoints personalizados o configuración TLS no estándar.

Cuándo usar etiquetas manuales

• Necesitas middleware de Traefik (basic auth, rate limiting, cabeceras personalizadas)
• Enrutas varios dominios a un solo servicio
• Necesitas entrypoints o ajustes TLS más allá de lo que ofrece la pestaña Domains

Si nada de esto aplica, quédate con la pestaña Domains.

Añadir dokploy-network y las etiquetas de Traefik

Con este enfoque, modificas el archivo compose para incluir dokploy-network y las etiquetas de Traefik:

services:
  flowise:
    image: flowiseai/flowise:latest
    networks:
      - dokploy-network
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.flowiseai.rule=Host(`flowise.yourdomain.com`)"
      - "traefik.http.routers.flowiseai.entrypoints=websecure"
      - "traefik.http.routers.flowiseai.tls.certResolver=letsencrypt"
      - "traefik.http.services.flowiseai.loadbalancer.server.port=3000"
    # ... rest of your service config

networks:
  dokploy-network:
    external: true

El formato de las etiquetas de Traefik:

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.<unique-name>.entrypoints=websecure"
  - "traefik.http.routers.<unique-name>.tls.certResolver=letsencrypt"
  - "traefik.http.routers.<unique-name>.rule=Host(`app.yourdomain.com`)"
  - "traefik.http.services.<unique-name>.loadbalancer.server.port=3000"

Sustituye <unique-name> por un identificador único para tu servicio, pon tu dominio en Host() y el puerto en el que tu app escucha internamente.

Todos los servicios que necesiten comunicarse entre sí (p. ej., la app y su base de datos) deben estar en dokploy-network. Para más información sobre Traefik, consulta Certificado Wildcard GRATIS de Let’s Encrypt con Traefik.

Isolated Deployments (pestaña Advanced)

La función Isolated Deployments de Dokploy es una tercera opción para la red. Cuando está activada, Dokploy:

• Crea una red aislada por app automáticamente
• Conecta Traefik a esa red aislada
• Elimina la necesidad de añadir dokploy-network manualmente a cada servicio
• Evita conflictos de nombres de servicio al ejecutar varias instancias de la misma app

Para activarla: ve a la pestaña Advanced de tu servicio compose y activa Isolated Deployments.

Está disponible tanto para servicios compose Raw como de proveedor Git. Consulta los docs de Utilities para más detalles.

Configurar variables de entorno en Dokploy

El ejemplo de Flowise usa la sintaxis ${VAR_NAME} en todo el archivo. Así funciona en Dokploy.

Cómo funciona el mecanismo del archivo .env

Cuando defines variables de entorno en la pestaña Environment de Dokploy, se escriben en un archivo .env en el servidor. Tu archivo compose debe referenciarlas con la sintaxis ${VAR_NAME} (o usar env_file: - .env). Esto es diferente de los servicios de aplicación, donde las variables se inyectan directamente en los contenedores.

Para el ejemplo de Flowise, añade esto en la pestaña Environment:

PORT=3000
POSTGRES_USER='user'
POSTGRES_PASSWORD='pass'
POSTGRES_DB='flowise'
FLOWISE_USERNAME=bitdoze
FLOWISE_PASSWORD=bitdoze

Algunas notas adicionales:

• Cifrado en reposo: desde v0.29.12, todas las variables de entorno se cifran con AES-256-GCM.
• Variables compartidas: Dokploy admite variables compartidas a nivel de proyecto (${{project.VAR_NAME}}) y de entorno (${{environment.VAR_NAME}}). Útil cuando varios servicios del mismo proyecto comparten credenciales. Consulta los docs de Variables.

Para profundizar en las variables de entorno de Docker, consulta cómo funcionan las variables de entorno de Docker con ARG y ENV.

Despliega y verifica tu app

Después de configurar tu archivo compose, las variables de entorno y el dominio, es hora de desplegar:

1. Ve a General y haz clic en Deploy.
2. Cambia a la pestaña Deployments para ver los logs de la compilación.
3. Espera un estado “success”.

Revisar los logs del despliegue

La pestaña Deployments muestra logs en tiempo real. Un despliegue correcto termina con los contenedores en ejecución y Traefik enrutando el tráfico. Si ves errores, los logs apuntarán al problema concreto (tag de imagen incorrecto, variable de entorno ausente, conflicto de puertos, etc.).

Verificar que la app está en ejecución

Cuando el despliegue termine correctamente, verifícalo:

curl -I https://flowise.yourdomain.com

Deberías obtener una respuesta HTTP/2 200. El certificado SSL debería ser válido. Traefik lo emite automáticamente a través de Let’s Encrypt.

Copias de seguridad para apps de Docker Compose

Desde v0.22.0 (mayo de 2025), Dokploy admite copias de seguridad de bases de datos y de volúmenes para servicios de Docker Compose. Si ejecutas algo con datos persistentes, configúralo cuanto antes.

Copias de seguridad de bases de datos (PostgreSQL)

El ejemplo de Flowise usa PostgreSQL. Dokploy puede respaldar bases de datos PostgreSQL, MariaDB, MySQL y MongoDB dentro de servicios de Docker Compose. Lo configuras en los ajustes de backup del servicio y lo apuntas a un destino compatible con S3.

Para configurar Cloudflare R2 como destino de tus copias de seguridad, consulta cómo configurar backups de Dokploy con Cloudflare R2.

Copias de seguridad de volúmenes

Dokploy puede respaldar volúmenes Docker con nombre en almacenamiento compatible con S3. Esto cubre los volúmenes flowiseai y flowise-db-data de nuestro ejemplo.

Consulta los docs de Volume Backups para los detalles de configuración.

Resolución de problemas comunes

dig flowise.yourdomain.com +short

Para más comandos de depuración, consulta los comandos esenciales de Docker. Para monitorizar tu servidor después del despliegue, configura la monitorización del servidor con Beszel y Uptime Kuma.

Actualizar y mantener tu app compose

Tras el despliegue inicial, con el tiempo necesitarás actualizar imágenes, cambiar variables de entorno o modificar el archivo compose. Dokploy lo hace sencillo. Edita la configuración y vuelve a desplegar.

Para el flujo completo de actualización (incluido cómo manejar tags de imagen, rollbacks y redespliegues), consulta nuestra guía sobre actualizar tus apps de Docker Compose desplegadas en Dokploy.

Conclusiones

Desplegar una app de Docker Compose en Dokploy se reduce a dos enfoques:

1. Pestaña Domains (recomendado): pega tu archivo compose tal cual, configura el dominio y el puerto en la interfaz y Dokploy se encarga del resto. Sin editar etiquetas, sin configurar redes.
2. Etiquetas de Traefik manuales (avanzado): para cuando necesitas enrutamiento personalizado, middleware o una configuración TLS no estándar.

Con Isolated Deployments activado, puedes tomar el camino más limpio: cero modificaciones a tu archivo compose. Pega, define las variables de entorno, añade un dominio y despliega.

No te saltes las copias de seguridad. Configura backups de base de datos para cualquier servicio con estado y backups de volúmenes para los datos persistentes. Tarda cinco minutos y te evita pérdidas de datos.

Si te interesan más apps autoalojadas, puedes descubrir más contenedores Docker autoalojados o consultar la sección de self-hosted de toolhunt.net.