Deploy y CI/CD

El despliegue corre sobre Dokploy, disparado por GitHub Actions después de un CI en verde. Hay dos entornos: producción (rama main) y dev (rama dev, con su propio dominio y su propia base de datos).

feature/* · fix/* ──push──▶ PR ──▶ merge a dev ──▶ CI ──▶ Deploy (dev) ──▶ https://dev.tudominio.com
                                                     │
                                       (cuando dev está estable)
                                                     ▼
                                    PR release: dev ──▶ main ──▶ CI ──▶ Deploy (prod) ──▶ health check

Activar el despliegue

Los workflows vienen apagados; se encienden con variables y secretos del repositorio (Settings → Secrets and variables → Actions).

Variables

Secretos

Imagen (GHCR)

El build corre en GitHub y publica una imagen en GitHub Container Registry (ghcr.io/<owner>/foodstack): tag :main para producción, :dev para dev y :sha-<commit> inmutable para rollback. Dokploy deja de construir el repo: en cada aplicación, Source → Docker → la imagen del entorno (puerto 3000). Si el paquete es privado, agrega credenciales de registro (PAT con read:packages).

El entorno dev (dev.tudominio.com)

Una segunda aplicación en Dokploy que sirve la rama dev, con base de datos propia. Los pasos completos están en la sección Entorno dev de DEPLOYMENT.md; en resumen:

1. Base de datos: una rama (branch) de Neon para dev, creada desde la principal. Su connection string será DEV_DATABASE_URL.
2. Aplicación en Dokploy: Source → Docker con la imagen ghcr.io/<owner>/foodstack:dev, puerto del contenedor 3000. Health check en /api/health.
3. Variables de la app dev: NUXT_DATABASE_URL (rama dev), BETTER_AUTH_SECRET propio y NUXT_APP_URL apuntando al dominio de dev. Better Auth usa esa URL como baseURL: magic links, invitaciones y callbacks deben apuntar ahí.
4. Dominio: agrega el host en Dokploy (HTTPS con Let's Encrypt) y crea un registro DNS A apuntando a la IP del servidor (o CNAME al dominio raíz).
5. Automatización: pega el webhook en el secreto DOKPLOY_DEV_WEBHOOK_URL y enciende DOKPLOY_DEV_DEPLOY_ENABLED.
6. E2E remoto (opcional): E2E_ENABLED=true + E2E_BASE_URL y los secretos E2E_EMAIL / E2E_PASSWORD de una cuenta owner de dev. La suite escribe y borra datos: apúntala solo a dev.

# Primera vez: crea la rama dev desde un main que ya tenga los workflows
git switch main && git pull
git switch -c dev
git push -u origin dev

Variables por entorno

Cada aplicación de Dokploy tiene su propio Environment: la app de dev y la de producción no comparten variables aunque vivan en el mismo proyecto. Hay tres niveles — compartidas del proyecto (${{project.VAR}}), del entorno (${{environment.VAR}}, si tu versión los soporta) y del servicio (las de cada app, que pisan a las anteriores); lo que cambia por entorno va siempre a nivel de servicio.

Guardar cambios en la pestaña Environment no toca el contenedor en marcha: lanza un Deploy después de editar. NUXT_APP_URL además se lee al construir (i18n baseUrl): va como build-arg desde las variables NUXT_APP_URL / DEV_NUXT_APP_URL de GitHub (ver Imagen (GHCR)).

Páginas estáticas (prerender)

Las páginas públicas se generan en el build y se sirven como archivos estáticos desde .output/public; el resto (dashboard, auth, API) sigue renderizándose en el servidor.

• La lista vive en routeRules (nuxt.config.ts): '/', '/_payload.json', '/docs' y '/docs/**' con prerender: true, y un catch-all '/**': { prerender: false } que mantiene al crawler fuera de /app y /auth.
• Agregar una sección no requiere tocar la config: el crawler (crawlLinks) descubre los archivos nuevos de content/docs/ desde los enlaces del índice.
• El build pasa sin .env (CI no tiene secretos): auth, colas y Resend se protegen con import.meta.prerender. No hay nada que configurar.
• El HTML se genera en inglés; el idioma del visitante (cookie i18n_locale) se aplica en el cliente inmediatamente después de la hidratación, sin recargar.
• Si en el futuro agregas otra página pública, dale su propia regla prerender: true (el catch-all la bloquearía) y verificá que exista su _payload.json en .output/public.

pnpm build                              # 13 rutas prerenderizadas
(nohup node .output/server/index.mjs &) # sirve .output: estáticas + SSR
mv .env .env.ci-bak && pnpm build; mv .env.ci-bak .env   # la prueba de CI, sin secretos

Migraciones (expand/contract)

El paso de migraciones corre antes del rollout, así que durante unos minutos conviven dos versiones del código contra el mismo esquema. Toda migración sigue el patrón expand/contract:

1. Expand: agrega (columna nullable, tabla nueva, índice CONCURRENTLY).
2. Migrar código: despliega la versión que escribe ambos formatos o que usa lo nuevo.
3. Backfill: rellena datos con un script o una tarea, fuera del deploy.
4. Contract: borra lo viejo (NOT NULL, drop) recién en un deploy posterior.

pnpm db:generate   # después de cambiar el schema
pnpm db:migrate    # lo aplica también el workflow de deploy

Backups de la base de datos

El dashboard admin (/app/admin/dashboard) genera backups manuales: un job de pg-boss corre pg_dump --format=custom y sube el dump al bucket dedicado (NUXT_APP_S3_BACKUP_BUCKET_NAME). Dos requisitos de despliegue:

• pg_dump en la imagen: lo instala el Dockerfile (postgresql-client-17 desde el repo PGDG); debe ser una versión ≥ a la del servidor PostgreSQL.
• Conexión directa: si NUXT_DATABASE_URL es la pooled de Neon (-pooler), el dump deriva la conexión directa automáticamente; también se puede fijar NUXT_BACKUP_DATABASE_URL.

Salud y rollback

• Liveness (/api/health): público y barato, no toca la base de datos. Es el que usan Dokploy y el paso final del workflow.
• Rollback: los tags :main/:dev son móviles; para volver atrás apunta la app a un :sha-<commit> inmutable y lanza un Deploy. Gracias a expand/contract, la versión anterior del código sigue siendo compatible con el esquema.
• Salud profunda (/api/admin/system/health): base de datos, Redis, colas y backups, solo para administradores.