Conceptos y glosario
Todo lo que aplica sin importar cómo despliegues (Git, Zip, Docker): jerarquía del panel, routing, botones, webhooks y errores comunes. Las guías de despliegue enlazan aquí en vez de repetir esto.
Jerarquía en Dokploy
Project → carpeta lógica (agrupa servicios)
└── Environment → production por defecto (permite dev/staging/prod)
└── Service → Application | Database | Compose | Template
⚠️ Un Project en GitLab es un repositorio. Un Project en Dokploy es una carpeta que agrupa servicios. No son lo mismo.
Los 8 providers de Dokploy
De dónde puede sacar el código o la imagen:
| Provider | Restricción |
|---|---|
| GitHub / GitLab / Bitbucket / Gitea | — |
| Git (genérico) | — |
| Docker (imagen de un registry) | Solo Applications |
Drag & Drop .zip | Solo Applications |
| Raw (YAML pegado) | Solo Docker Compose |
Detalle de cada uno en Providers.
Los 6 Build Types
| Tipo | Qué hace | Cuándo |
|---|---|---|
| Nixpacks | Detecta el lenguaje, corre install + build. Con Publish Directory sirve estático. | Prototipos, POCs |
| Railpack 🆕 | Sucesor de Nixpacks, más moderno. | A evaluar (posible futuro default) |
| Dockerfile | Usa tu Dockerfile. Control total. | ✅ Producción |
| Heroku / Paketo Buildpacks | Buildpacks de esos ecosistemas. | Legacy / corporativo |
| Static | No construye. Copia el root a NGINX y lo sirve. | Archivos ya listos |
El trade-off central
Nixpacks: cero configuración, pero es una caja negra — cómodo hasta que te sales de sus convenciones (el error de Node 18 en Vite es exactamente eso).
Dockerfile: control total, build idéntico en local y servidor, versionado en el repo. Es el camino de producción.
DNS: registro directo vs wildcard
Registro directo (un subdominio)
Namecheap → dominio → Advanced DNS → Add New Record:
| Type | Host | Value |
|---|---|---|
| A Record | <subdominio> | 143.198.113.169 |
Verificar antes de desplegar:
dig +short <subdominio>.inmersys.dev # debe devolver la IP del droplet
⚠️ No dispares el Deploy con HTTPS activo si el DNS aún no resuelve. Let's Encrypt valida por HTTP-01: si el dominio no apunta al servidor, la emisión falla (y hay rate limit).
Registro wildcard (recomendado para desarrollo/POC)
| Type | Host | Value |
|---|---|---|
| A Record | * | 143.198.113.169 |
Cualquier loquesea.inmersys.dev resuelve al droplet — ya no vuelves a Namecheap por cada prueba. Traefik solo enruta lo configurado; el resto responde 404 inofensivo.
Los registros específicos ganan sobre el wildcard (regla del DNS: gana la coincidencia más específica). Así puedes sacar un subdominio a otro servidor cuando quieras:
A * → 143.198.113.169 (droplet Dokploy)
A api → 200.10.20.30 (otro droplet) ← este gana para api.inmersys.dev
Dos límites del *: no cubre sub-sub-dominios (v2.api... necesita *.api) ni el dominio raíz (inmersys.dev a secas necesita host @).
Recomendación: wildcard en desarrollo, registros explícitos en producción (para saber exactamente qué existe).
Container Port y routing por hostname
El Container Port es el puerto donde escucha el proceso dentro del contenedor:
| Qué corre adentro | Container Port |
|---|---|
| Static (NGINX) / Nixpacks con Publish Directory (Caddy) / Dockerfile+NGINX | 80 |
| Node / Express | el de app.listen() (ej. 3000, 5000) |
El panel sugiere 3000 como ejemplo, pero el valor correcto depende de la app. Si no coincide → 502 Bad Gateway.
El mismo puerto puede repetirse en N apps sin conflicto: cada contenedor tiene su red aislada. Traefik enruta por hostname (Host header / SNI), no por puerto:
Traefik :443
├─► testhtml.inmersys.dev → contenedor A :80
├─► dq.inmersys.dev → contenedor B :80
└─► api.inmersys.dev → contenedor C :3000
Los únicos puertos exclusivos son el 80 y 443 del host, que ya usa Traefik. Por eso en Dokploy no se exponen puertos del host directamente.
Advanced → Resources (límites por contenedor)
Sin límites, cualquier contenedor puede consumir toda la RAM y tumbar a Dokploy y a las demás apps.
| Campo | Ejemplo | Equivale a |
|---|---|---|
| Memory Limit | 536870912 | 512 MB |
| Memory Reservation | 134217728 | 128 MB |
| CPU Limit | 1000000000 | 1 CPU |
El panel espera el valor crudo en bytes / nanoCPU, no 512MB. El texto debajo del campo debe confirmar 512.00 MB. Si dice 0.00 MB, no se aplicó. Tras guardar → Reload (los límites son config de Docker, no de la imagen).
Verificación real desde consola:
docker stats --no-stream
Si LIMIT sigue mostrando la RAM total (ej. 3.824GiB), no se aplicaron. El panel puede decir que guardó; Docker es el que manda.
Glosario de botones
General → Deploy Settings
| Botón | Qué hace | ¿Construye? |
|---|---|---|
| Deploy | Clona + build + start. El normal. | ✅ |
| Reload | Reinicia el contenedor con la config nueva, sin reconstruir. Para cambios de env vars o límites. | ❌ |
| Rebuild | Reconstruye la imagen sin volver a clonar. | ✅ |
| Start / Stop | Arranca o detiene el contenedor. | — |
| Autodeploy | Toggle para que el webhook dispare deploys en push. Con GitLab el webhook se crea a mano (ver abajo). | — |
| Clean Cache | Build desde cero, sin capas cacheadas. Para cuando "no toma los cambios". | — |
Para cambios de configuración usa Reload — es el más barato y no dispara build.
Pestaña Deployments
| Botón | Qué hace |
|---|---|
| Kill Build 🪓 | Mata el build en curso. Botón de emergencia. |
| Cancel Queues | Cancela los deploys encolados, no el que corre. |
| Clear deployments | Limpia el historial de la lista. Cosmético — no revierte nada. |
| Configure Rollbacks | Volver a una versión anterior. Explorar antes de meter clientes reales. |
🪓 Kill Build es el freno de mano: el build corre en el mismo droplet que producción; si un
npm installdesbocado degrada apps de clientes, aquí lo matas.
Auto-deploy con webhooks
⚠️ Dokploy NO registra webhooks automáticamente en GitLab. (Con GitHub sí.) El toggle Autodeploy solo, no hace nada.
Es POR SERVICIO, no global. Cada Application tiene su propio Webhook URL. 10 apps con auto-deploy = 10 webhooks en GitLab.
📝 Contra para la migración: con GitLab, el auto-deploy requiere config manual por cada servicio. Es fricción real con decenas de proyectos.
Configuración
1. Copiar el Webhook URL: Application → Deployments → 📋 junto a Webhook URL.
https://panel.inmersys.dev/api/deploy/<TOKEN>
🔒 Esa URL es una credencial: quien la tenga dispara deploys. Censurarla en capturas. El botón 📋 la regenera si se filtra.
2. En GitLab: repo → Settings → Webhooks → Add new webhook:
| Campo | Valor |
|---|---|
| Name | algo identificable (habrá varios) |
| URL | la copiada |
| Secret token | (vacío — Dokploy no lo valida) |
| Push events | ✅ + Wildcard pattern con la branch de esta Application |
| SSL verification | ✅ |
⚠️ "Deployment events" NO aplica — se refiere a los Environments de GitLab, no a Dokploy. Dejar apagado.
3. En Dokploy: General → Deploy Settings → toggle Autodeploy ON.
Son dos piezas: el webhook (GitLab avisa) + el toggle (Dokploy escucha). Falta una y no funciona.
4. Probar: en GitLab → menú del webhook → Test → Push events. Debe aparecer un deployment nuevo. Si falla, Recent Deliveries muestra el código HTTP.
El deploy solo se dispara en la branch seleccionada. Esto habilita múltiples entornos: varias Applications sobre el mismo repo, cada una en una branch (dev, staging, main) y un dominio distinto.
Costo: los webhooks son gratis. El costo real es de recursos — cada webhook dispara un build, y los builds comen CPU/RAM. Controles: branch filter, toggle Autodeploy, y Kill Build / Cancel Queues.
El aviso de recursos del builder
"Builders can consume significant memory and CPU resources (recommended: 4+ GB RAM and 2+ CPU cores)"
El build corre en el mismo servidor que las apps en producción. Con un HTML plano es irrelevante; importa con builds reales (Vite, Unity WebGL). Análisis completo y la solución con CI/registry en El problema de los builds.
Errores comunes (aplican a cualquier fase)
| Síntoma | Causa probable |
|---|---|
| 502 Bad Gateway | Container Port no coincide con el puerto real de la app |
| Falla el certificado SSL | DNS no propagado al desplegar, o typo en el Host |
| Dropdown de repos vacío | OAuth de GitLab no autorizado (Conectar GitLab) |
| 404 en rutas internas al recargar | SPA fallback desmarcado en un proyecto con routing de cliente |
| Push no dispara deploy | Webhook no creado, toggle apagado, o push a otra branch |
Errores específicos de cada método están en su guía correspondiente.