Dokploy Internals — CreaRack Pro

Fecha: 07-04-2026 Objetivo: Documentar cómo Dokploy gestiona redes, labels, Swarm y deploys Contexto: Incidentes del 04-04-2026 por desconocimiento de la arquitectura interna

1. Qué es Dokploy

Dokploy v0.28.8 es una plataforma de deploy self-hosted. No es un binario — es un conjunto de 3 contenedores Docker gestionados por Docker Swarm.

Dato crítico: Dokploy requiere Docker Swarm con node.role == manager. Sin Swarm, Dokploy no existe.

2. Redes Docker — El punto más crítico

Mapa de redes

El container web está en 3 redes simultáneamente

Internet → Traefik (dokploy-network:10.0.1.18)
               ↓
           web (dokploy-network:10.0.1.28)  ← Traefik enruta aquí
           web (crearack_internal:172.19.0.7) ← DB, cache, VM viven aquí
           web (default:172.20.0.2)

Por qué esto importa

• Traefik solo busca en dokploy-network (configurado en traefik.yml)
• Si web no está en dokploy-network, Traefik no lo encuentra → 404
• Si web no está en crearack_internal, no puede hablar con la BD → 500
• Los labels de Traefik deben decir traefik.docker.network=dokploy-network

3. Traefik — Reverse proxy

Arquitectura

Traefik v3.6.7 corre como container standalone (no Swarm service), conectado a dokploy-network.

Internet → :80 (HTTP) → middleware redirect-to-https → :443
         → :443 (HTTPS + HTTP/3) → router → web:8000

Configuración (3 niveles)

Nivel 1 — Estática (/etc/dokploy/traefik/traefik.yml):

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
    http3: {}           # HTTP/3 habilitado

providers:
  docker:
    exposedByDefault: false          # Solo containers con traefik.enable=true
    network: dokploy-network         # Red donde Traefik busca containers
  swarm:
    exposedByDefault: false
    network: dokploy-network
  file:
    directory: /etc/dokploy/traefik/dynamic
    watch: true

certificatesResolvers:
  letsencrypt:
    acme:
      email: info@crearack.com
      storage: /etc/dokploy/traefik/dynamic/acme.json
      httpChallenge:
        entryPoint: web

Nivel 2 — Dinámica (/etc/dokploy/traefik/dynamic/):

Nivel 3 — Labels en containers (inyectados por Dokploy en deploy):

traefik.enable=true
traefik.docker.network=dokploy-network

# HTTP → redirect a HTTPS
traefik.http.routers.crearack-pro-zcmvsl-1-web.rule=Host(`crearack.com`)
traefik.http.routers.crearack-pro-zcmvsl-1-web.entrypoints=web
traefik.http.routers.crearack-pro-zcmvsl-1-web.middlewares=redirect-to-https@file

# HTTPS → TLS con Let's Encrypt
traefik.http.routers.crearack-pro-zcmvsl-1-websecure.rule=Host(`crearack.com`)
traefik.http.routers.crearack-pro-zcmvsl-1-websecure.entrypoints=websecure
traefik.http.routers.crearack-pro-zcmvsl-1-websecure.tls.certresolver=letsencrypt

# Load balancer → Daphne en puerto 8000
traefik.http.services.crearack-pro-zcmvsl-1-web.loadbalancer.server.port=8000

IMPORTANTE: Estos labels los inyecta Dokploy. No están en compose.prod.yml. Si haces docker compose up manual, los containers NO tendrán labels y Traefik no los verá.

4. Flujo de deploy

Cómo Dokploy despliega CreaRack

1. Webhook GitHub (push a main)
   ↓
2. Dokploy recibe webhook → clona/actualiza repo
   en /etc/dokploy/compose/crearack-pro-zcmvsl/code/
   ↓
3. Inyecta variables de entorno (.env)
   ↓
4. docker compose build (usa Dockerfile.prod)
   ↓
5. docker compose up -d (con labels de Traefik)
   ↓
6. Traefik detecta nuevo container → enruta tráfico

IMPORTANTE — [skip ci] bloquea Dokploy: Si el mensaje del commit contiene la palabra skip (ej. [skip ci]), Dokploy omite silenciosamente el deploy. Devuelve HTTP 200 OK pero el log indica "Deployment skipped: commit message contains skip keyword". Usar [skip ci] solo en commits de documentación que no deban disparar deploy.

Estructura en disco

/etc/dokploy/
├── compose/
│   └── crearack-pro-zcmvsl/
│       └── code/                    ← Git clone completo del repo
│           ├── compose.prod.yml
│           ├── Dockerfile.prod
│           ├── .env                 ← Generado por Dokploy (secrets)
│           └── ... (todo el código)
├── traefik/
│   ├── traefik.yml                  ← Config estática
│   └── dynamic/
│       ├── acme.json                ← Certificados SSL
│       ├── middlewares.yml
│       └── dokploy.yml
├── applications/                    ← Vacío (no usamos tipo "application")
├── logs/
├── monitoring/
├── schedules/
├── ssh/
└── volume-backups/

5. Deploy manual (sin Dokploy)

Si Dokploy muere y necesitas desplegar manualmente:

# 1. Ir al directorio del código
cd /etc/dokploy/compose/crearack-pro-zcmvsl/code/

# 2. Pull último código
git pull origin main

# 3. Rebuild
docker compose -f compose.prod.yml build web

# 4. Recrear con labels de Traefik
docker compose -f compose.prod.yml up -d web \
  --label "traefik.enable=true" \
  --label "traefik.docker.network=dokploy-network"

# ⚠️ PROBLEMA: docker compose up no soporta --label
# Alternativa: añadir labels al compose.prod.yml temporalmente:
#
# services:
#   web:
#     labels:
#       - "traefik.enable=true"
#       - "traefik.docker.network=dokploy-network"
#       - "traefik.http.routers.crearack-web.rule=Host(`crearack.com`)"
#       - "traefik.http.routers.crearack-web.entrypoints=websecure"
#       - "traefik.http.routers.crearack-web.tls.certresolver=letsencrypt"
#       - "traefik.http.services.crearack-web.loadbalancer.server.port=8000"

# 5. Conectar a dokploy-network manualmente si no está
docker network connect dokploy-network crearack-pro-zcmvsl-web-1

# 6. Verificar que Traefik ve el container
curl -s https://crearack.com/health

6. Contenedores en producción

7. Volúmenes persistentes

8. FOOTGUNS — Lo que NUNCA hacer

9. Troubleshooting

“404 Not Found” en crearack.com

# 1. ¿Web container está corriendo?
docker ps | grep web

# 2. ¿Está en dokploy-network?
docker inspect crearack-pro-zcmvsl-web-1 | grep -A 5 dokploy-network
# Si no aparece:
docker network connect dokploy-network crearack-pro-zcmvsl-web-1

# 3. ¿Tiene labels de Traefik?
docker inspect crearack-pro-zcmvsl-web-1 | grep traefik
# Si no: redesplegar desde Dokploy

# 4. ¿Traefik está corriendo?
docker ps | grep traefik
# Si no: docker start dokploy-traefik

“502 Bad Gateway”

# Web container existe pero no responde
docker logs crearack-pro-zcmvsl-web-1 --tail 20

# Health check
docker exec crearack-pro-zcmvsl-web-1 curl -s localhost:8000/health

# Reiniciar
docker restart crearack-pro-zcmvsl-web-1

Dokploy no arranca

# Verificar Swarm
docker info | grep "Swarm:"
# Si "inactive": docker swarm init

# Verificar servicios
docker service ls
# Si no aparecen: reinstalar Dokploy
curl -sSL https://dokploy.com/install.sh | sh

Traefik no renueva SSL

# Verificar ACME
cat /etc/dokploy/traefik/dynamic/acme.json | python3 -m json.tool | head -20

# Verificar que puerto 80 está abierto (ACME HTTP challenge)
curl -s http://crearack.com/.well-known/acme-challenge/test
# Debe responder (aunque sea 404 de Traefik, no timeout)

# Forzar renovación: borrar acme.json y reiniciar Traefik
# ⚠️ Solo si SSL está expirado y no se renueva automáticamente
mv /etc/dokploy/traefik/dynamic/acme.json /etc/dokploy/traefik/dynamic/acme.json.bak
docker restart dokploy-traefik

10. Variables de entorno

Las variables se gestionan exclusivamente desde el panel Dokploy (Settings → Environment).

Categoría de variables actuales:

NOTA: Si Dokploy muere, estos secrets se pierden (están en la BD interna de Dokploy). Mantener una copia cifrada fuera del servidor.

11. Servidor de Staging

El staging sirve para probar cambios antes de producción. Mismo compose.prod.yml, pero con las variables de entorno ajustadas al dominio de staging. No tiene WAL archiving ni backups offsite — la BD se restaura manualmente desde un backup de producción si es necesario.

Crons del sistema (fuera de Dokploy)

Además del stack Docker, Staging ejecuta varios crons del host como “servidor de tareas periódicas” del ecosistema CreaRack:

El reindex de la Biblioteca vivía hasta 2026-04-20 en el Task Scheduler del PC de Edu (diario 04:00). Se movió a Staging para que el grafo evolucione sin depender de equipos individuales.

Instalación del reindex (documentada para reproducibilidad):

• Repo clonado en /opt/crearack-pro via SSH deploy key staging-bib-reindex (read-only) añadida a CreaRackSL/CreaRack-Pro.
• BIB_MCP_TOKEN en /opt/bib-reindex/.token (chmod 600).
• Cron en /etc/cron.d/bib-reindex con flock -n /tmp/bib-reindex.lock para evitar solapamiento si un run tarda >10 min.
• Log en /opt/bib-reindex/cron-bib-reindex.log (rotado automáticamente al pasar de 5 MB).

Otros directorios operacionales

• /opt/workspace-mirror/ — mirror del workspace accesible en :8090 (entorno de testing de Astro builds).
• /opt/dr-backups/ — backups JSON y scripts de recuperación.
• /opt/bib-reindex/ — script, token y log del cron de reindexación.

Generado por: Claude (Anthropic) + Edu Actualizado: 21-04-2026 (auditoría + migración bib-reindex)

Véase también

• [[crearack-tech—admin—dokploy-guide]] — guía operativa de Dokploy
• [[crearack-tech—admin—server-management]] — gestión global de servidores
• [[decision—20251201—dokploy-vs-kubernetes]] — decisión Dokploy vs Kubernetes
• [[incident—20260220—pgbouncer-dokploy-networking]] — incidente pgbouncer+Dokploy networking
• [[crearack-tech—guides—docker-guide]] — guía de Docker