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.

Servicio Swarm	Imagen	Función
`dokploy`	`dokploy/dokploy:v0.28.8`	Panel web (puerto 3000) + orquestador
`dokploy-postgres`	`postgres:16`	BD interna (proyectos, config, historial)
`dokploy-redis`	`redis:7`	Cache/queue interna

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

Red	Driver	Subnet	Quién la usa
`dokploy-network`	overlay (Swarm)	`10.0.1.0/24`	Traefik ↔ web container
`crearack_internal`	bridge	`172.19.0.0/16`	web ↔ db, cache, VM, pgbouncer, worker
`crearack_default`	bridge	`172.20.0.0/16`	Red default del compose
`ingress`	overlay	—	Red interna de Swarm
`docker_gwbridge`	bridge	`172.18.0.0/16`	Puente entre host y overlay

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/):

Archivo	Contenido
`middlewares.yml`	`redirect-to-https` (HTTP→HTTPS), `hide-server-header`
`dokploy.yml`	Router al panel Dokploy (localhost only)
`acme.json`	Certificados Let’s Encrypt (auto-renovados)

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

Contenedor	Red(es)	Puerto expuesto	Rol
`crearack-pro-zcmvsl-web-1`	internal + default + dokploy-network	0.0.0.0:8000	Django/Daphne ASGI
`crearack-pro-zcmvsl-worker-1`	internal	—	Huey task worker
`crearack-pro-zcmvsl-db-1`	internal	—	PostgreSQL 18
`crearack-pro-zcmvsl-pgbouncer-1`	internal	—	Connection pooler (6432)
`crearack-pro-zcmvsl-cache-1`	internal	—	Valkey 7.2
`crearack-pro-zcmvsl-victoriametrics-1`	internal	—	Time-series DB
`dokploy` (Swarm)	dokploy-network	0.0.0.0:3000	Panel Dokploy
`dokploy-traefik`	dokploy-network	0.0.0.0:80,443	Reverse proxy
`dokploy-redis` (Swarm)	dokploy-network	—	Redis Dokploy
`dokploy-postgres` (Swarm)	dokploy-network	—	PG Dokploy

7. Volúmenes persistentes

Volumen	Datos	Tamaño	Backup offsite
`pg_data_prod`	Base de datos PostgreSQL	~20 MB	Sí (pg_dump → Object Storage)
`app_media`	Media uploads (stencils, signage)	~654 MB	No
`valkey_data_prod`	Cache Valkey (AOF)	< 10 MB	No (reconstruible)
`vm_data_prod`	Métricas VictoriaMetrics	~83 MB	No (repoblable)
`mib_cache`	MIBs SNMP compiladas	< 5 MB	No (regenerable)
`app_logs`	Logs de la aplicación	Variable	No
`dokploy`	Config Docker de Dokploy	< 1 MB	No
`dokploy-postgres`	BD interna Dokploy	< 5 MB	No

8. FOOTGUNS — Lo que NUNCA hacer

Acción	Consecuencia	Alternativa
`docker swarm leave`	Destruye Dokploy, Traefik y toda la infra de deploy	NUNCA hacerlo
Quitar `dokploy-network` del web service en compose	App inaccesible (Traefik no la alcanza)	Mantener siempre
`docker compose up` manual en el servidor	Containers sin labels de Traefik → 404	Redesplegar desde Dokploy
`docker compose down` manual	Dokploy queda desincronizado	Usar panel Dokploy
Editar `.env` directamente en servidor	Se sobreescribe en el próximo deploy	Editar env vars desde panel Dokploy
Borrar `acme.json`	Pierde certificados SSL → downtime hasta re-emisión	Hacer backup antes
Cambiar label `traefik.docker.network`	Traefik busca en red equivocada → 404	Debe ser `dokploy-network`
Añadir servicios a `crearack_internal` manualmente	No resuelven DNS si no están en el compose	Añadir al compose.prod.yml
Commit message con `[skip ci]` o cualquier “skip”	Dokploy omite el deploy silenciosamente (HTTP 200 pero sin deploy)	Usar `[skip ci]` solo en docs-only
Password Valkey/Redis con caracteres especiales (`-`, `!`, `@`)	El parser de config falla al leer la password	Usar solo caracteres hex (`a-f0-9`)
Healthcheck del worker apuntando a `curl localhost:8000`	Worker no es servidor web → healthcheck siempre falla	Usar `pgrep run_huey`

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:

Tipo	Variables	Ejemplo
Django	`DJANGO_SETTINGS_MODULE`, `DJANGO_SECRET_KEY`, `DJANGO_ALLOWED_HOSTS`, `CSRF_TRUSTED_ORIGINS`	—
PostgreSQL	`POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`	—
Cache	`REDIS_PASSWORD`	hex-only (sin `-`, `!`, `@`)
AI Providers	`GEMINI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`	—
Email	`RESEND_API_KEY`	—
GitHub	`GITHUB_TOKEN`	—
Monitoring	`VICTORIAMETRICS_URL`	`http://victoriametrics:8428`
Seguridad cookies	`SECURE_COOKIES`	`true` (producción) / `false` (staging HTTP)

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

Parámetro	Valor
IP	178.104.131.173
Hostname	`crearack-staging`
Tipo	CX23 con 2 vCPU, 3.7 GB RAM (upgrade sin snapshot previo), 40 GB disco
OS	Ubuntu 24.04.4 LTS (Noble Numbat)
Python	3.12.3 (suficiente para `bib_ast.py` — zero-deps, solo stdlib)
Setup	Dokploy + stack completo (misma configuración que producción)
Diferencia clave	`SECURE_COOKIES=false` (HTTP sin SSL)

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:

Cron	Script	Propósito
`0 0 * * *`	`/opt/dr-backups/cron-dr-backup.sh`	Backup nightly del workspace D1 (ver Auto-Reports)
`0 3 * * 0`	`/opt/dr-backups/cron-gdrive-sync.sh`	Sync semanal de backups a Google Drive
`0 8 * * *`	`/opt/dr-backups/cron-stale-check.sh`	Chequeo diario de docs desactualizados
`/10 * * *`	`/opt/bib-reindex/cron-bib-reindex.sh`	Reindex de la Biblioteca (desde 2026-04-21)

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

Dokploy Internals — CreaRack Pro

Dokploy Internals — CreaRack Pro

1. Qué es Dokploy

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

Mapa de redes

El container web está en 3 redes simultáneamente

Por qué esto importa

3. Traefik — Reverse proxy

Arquitectura

Configuración (3 niveles)

4. Flujo de deploy

Cómo Dokploy despliega CreaRack

Estructura en disco

5. Deploy manual (sin Dokploy)

6. Contenedores en producción

7. Volúmenes persistentes

8. FOOTGUNS — Lo que NUNCA hacer

9. Troubleshooting

“404 Not Found” en crearack.com

“502 Bad Gateway”

Dokploy no arranca

Traefik no renueva SSL

10. Variables de entorno

11. Servidor de Staging

Crons del sistema (fuera de Dokploy)

Otros directorios operacionales

Véase también

El container `web` está en 3 redes simultáneamente