API Express

Proyecto de referencia: queruva-totems_quiz-back · desplegado con Nixpacks (build en el servidor). Fuera de alcance: el pipeline .gitlab-ci.yml no está implementado — aquí solo la config actual del panel.

---

1. Preparar el repositorio

1.1 El package.json

El cambio crítico es el script start:

{
  "engines": { "node": "22" },
  "scripts": {
    "start": "node src/app",
    "dev": "nodemon --env-file .env src/app"
  }
}

Por qué: Dokploy no crea un archivo .env en el contenedor — inyecta las variables como variables de entorno reales. Si start conserva --env-file .env, Node busca un archivo que no existe y el contenedor muere al arrancar. --env-file se queda solo en dev (donde sí hay .env local).

⚠️ "node": ">=22" (rango abierto) puede darte Node 23/24 en un build futuro y romper algo sin cambiar código. Para builds reproducibles, fija la versión: "22".

1.2 Escuchar en 0.0.0.0

this.app.listen(this.port, '0.0.0.0', () => { ... });

Obligatorio en contenedores. Si escucha en localhost, Traefik nunca la alcanza → 502.

1.3 public/ versionado

Si Server.js hace express.static("public"), esa carpeta debe estar en git (no en .gitignore, o no llega a la imagen). Verificar: git ls-files public.

---

2. General → Provider

Campo	Valor
Provider	Gitlab → la cuenta conectada
Repository / Branch	queruva-totems_quiz-back / develop
Build Path	/
Autodeploy	ON (crea webhook en GitLab)

Save. Verifica que el webhook se creó: GitLab → Settings → Webhooks. Si no aparece, el token de la app no tiene permisos.

---

3. Build Type

Campo	Valor
Build Type	Nixpacks
Publish Directory	vacío

Publish Directory es una trampa. Si le pones algo, Dokploy asume sitio estático, levanta NGINX y tu API nunca arranca. Ese campo es solo para frontends compilados (Vite, Astro). Nixpacks detecta el package.json, corre npm ci y npm start.

---

4. Environment

NODE_ENV=production
PORT=5000
JWT_SECRET=...
DNS_OVERRIDE=true
DB_URL=mongodb+srv://usuario:<password>@cluster.xxxx.mongodb.net/dev
DB_PASSWORD=...
# S3 (uploads)
S3_ENDPOINT=...
AWS_ACCESS_KEY=...
AWS_SECRET_ACCESS_KEY=...

Puntos que muerden:

• El placeholder <password> es obligatorio, no cosmético. config/database.js hace url.replace("<password>", password). Si pones el password real embebido, el .replace() no encuentra el placeholder y conecta "de casualidad" — rotar DB_PASSWORD dejaría de tener efecto. DB_URL debe conservar el literal <password>.
• DNS_OVERRIDE=true es necesario con Mongo Atlas (mongodb+srv://): la resolución SRV falla seguido con el DNS interno de Docker.
• NODE_ENV=production hace que Express deje de mandar el stack trace en los errores (sin él, un 500 expone tus rutas internas). ⚠️ Pero con Nixpacks puede hacer que npm install omita las devDependencies — si el build depende de una (TypeScript, esbuild), usar NIXPACKS_INSTALL_CMD=npm ci --include=dev.
• El editor soporta comentarios #. El icono del ojo oculta los valores al compartir pantalla.

---

5. Domains

Campo	Valor
Host	queruva-backdev.inmersys.dev
Container Port	5000
HTTPS	ON + Let's Encrypt

El error más común: puerto desalineado. El Container Port debe ser idéntico al PORT del Environment. Si la app escucha en 5000 y Traefik toca 3000 → 502 (ver Container Port).

Antes de guardar, crea el registro A en el DNS. Si no propagó, Let's Encrypt no emite el certificado — ese fallo se ve en los logs de Traefik, no en los de la app.

---

6. Advanced → Resources

Config general en Advanced → Resources. Valores para esta API:

Campo	Valor	Equivale a
Memory Limit	536870912	512 MB
CPU Limit	1000000000	1 CPU

Esta API consume ~53-60 MiB de RAM en reposo — el límite de 512 MB es 8x holgura.

docker stats --no-stream
# queruva-backdev...  53.05MiB / 512MiB   0.57%

---

7. Desplegar y verificar

Deploy → Logs. Debes ver:

server is running on http://localhost:5000
DB Connection successfully

Diagnóstico específico

Síntoma	Causa probable
Database is not connected	La IP del droplet no está en el Network Access de Atlas
El contenedor arranca y muere	start todavía tiene --env-file .env
Deploy verde pero fallan uploads	Faltan las variables de S3

Errores generales en Errores comunes.