ADR — Dokploy sobre Docker Swarm (no Kubernetes)

Contexto

CreaRack-Pro opera con equipo reducido (1-2 devs activos) y se despliega en servidor único en Hetzner. Stack principal en compose.yml: aplicación principal, PostgreSQL, servicios auxiliares. Infraestructura debe ser manejable por una persona sin dedicación exclusiva a operaciones, con capacidad de despliegue continuo, rollback sencillo y observabilidad básica sin overhead operacional elevado.

A finales de 2025, con crecimiento del proyecto, surgió la necesidad de capa de orquestación más formal que plain Docker Compose, que permitiera health checks, zero-downtime deploys y UI de gestión.

Opciones evaluadas

Kubernetes (K3s o K8s completo): orquestación enterprise, multi-node real, ecosistema maduro, escalabilidad horizontal. Curva de aprendizaje significativa, complejidad operacional alta incluso con K3s, para servidor único añade overhead sin beneficio proporcional. YAML manifests, networking interno y gestión de secrets requieren dedicación continua.

Docker Swarm + Dokploy: Swarm provee orquestación nativa sobre la misma sintaxis Compose, eliminando reescritura del stack. Dokploy añade UI web para deploys, variables de entorno, dominios y certificados TLS sobre Swarm, con soporte multi-proyecto desde panel único. Transición desde compose.yml prácticamente directa.

Nomad (HashiCorp): orquestador flexible y más ligero que Kubernetes, pero requiere aprender DSL propio (HCL), integración manual con Consul para service discovery, menor adopción en proyectos de este tamaño.

Plain Docker Compose: menor fricción, pero sin health-check automático entre reinicios del daemon, sin zero-downtime deploys nativos y sin panel de gestión.

Decisión

Docker Swarm con Dokploy como plataforma de orquestación. compose.yml existente convertido a stack de Swarm con cambios mínimos (adición sección deploy). Dokploy instalado en el mismo nodo Hetzner gestiona ciclo completo de despliegue: build de imagen, push al registry, update del stack, reverse proxy con Traefik integrado.

Consecuencias

Ventajas:

• Reutilización directa de compose.yml sin reescritura.
• Curva de aprendizaje mínima; cualquier miembro familiarizado con Compose puede operar.
• Dokploy provee UI funcional para deploys, logs y variables sin CLI exclusivo.
• Zero-downtime deploys vía rolling updates de Swarm.
• TLS automático via Traefik integrado.

Desventajas:

• No hay multi-node real productivo; escalar horizontalmente requeriría migrar a Kubernetes en el futuro.
• Docker Swarm tiene menor desarrollo activo upstream que Kubernetes.
• UI de Dokploy, al ser proyecto joven, puede tener inconsistencias en versiones tempranas.

Status

Accepted. Decisión vigente para servidor de producción en Hetzner. Revisión si el proyecto requiere escalar a múltiples nodos o si el equipo crece significativamente.

Véase también

• [[concept—biblioteca—supercontexto]]
• [[incident—20260220—pgbouncer-dokploy-networking]] — pgbouncer incompatible con Dokploy networking