Deployment

1. Visión General del Pipeline

El deployment de Nvito combina múltiples herramientas según el ambiente y el tipo de servicio. El flujo general es: el desarrollador hace push, GitLab CI valida calidad, y el proveedor de hosting despliega automáticamente.

Matriz de Deployment

2. Coolify VPS (DEV/TEST)

Coolify v4 es un PaaS open-source que gestiona contenedores Docker en el VPS de Contabo. Funciona como un "Heroku self-hosted".

2.1 Infraestructura del VPS

2.2 Servicios Desplegados

2.3 Flujo de Deploy en Coolify

2.4 Conexión con GitLab

Coolify v4 no tiene integración nativa con GitLab (solo GitHub y Gitea). La conexión se hace via deploy keys SSH:

1. Generar SSH key en Coolify: Security > Private Keys > Add
2. Copiar la clave pública al repo en GitLab: Settings > Repository > Deploy Keys
3. Configurar servicio en Coolify como "Private Repository (with Deploy Key)"
4. Configurar webhook URL de Coolify en GitLab: Settings > Webhooks > Push events

2.5 Variables de Entorno en Coolify

Las variables se configuran directamente en el dashboard de Coolify por servicio. No se usan archivos .env ni BWS para el runtime de las aplicaciones en Coolify.

2.6 SSL y Dominios

Traefik gestiona SSL automáticamente:

1. Coolify configura labels de Traefik en el contenedor con el dominio custom
2. Traefik detecta el nuevo dominio y solicita certificado Let's Encrypt via ACME HTTP-01
3. El certificado se renueva automáticamente 30 días antes de expirar
4. Cloudflare proxy (modo Full) confía en el certificado Let's Encrypt del origin

2.7 Sin Suspensión

Docker en VPS no duerme los contenedores. Esto es crítico porque nvito-api usa Bull queues con Redis para procesar emails, WhatsApp y jobs asíncronos. Si el backend se suspende, los jobs en cola no se procesan.

3. Railway Pro (Producción)

Railway Pro es la plataforma de hosting planificada para producción. Ofrece deployment automático, private networking y escalado vertical sin gestión de servidores.

3.1 Configuración del Proyecto

3.2 Auto-Deploy desde GitLab

Railway soporta deployment automático conectando el repositorio de GitLab:

1. Vincular repo GitLab al servicio Railway
2. Configurar branch de deploy: main
3. Cada push a main dispara build + deploy automático
4. Railway detecta el Dockerfile y ejecuta multi-stage build
5. Health check antes de cortar trafico al contenedor anterior

3.3 Custom Domains y CNAME

Para cada servicio en Railway se configura un custom domain que apunta via CNAME:

app.nvito.mx      CNAME    nvito-pwa-prod.up.railway.app
inv.nvito.mx      CNAME    nvito-inv-prod.up.railway.app
admin.nvito.mx    CNAME    nvito-admin-prod.up.railway.app

Para api.nvito.mx, el CNAME apunta al Cloudflare Worker (no directamente a Railway).

3.4 Health Checks

Si el health check falla después de 3 retries, Railway revierte al deployment anterior automáticamente.

3.5 Pricing Railway Pro

4. Cloudflare Pages (Docs + Landing)

Los sitios estáticos de Nvito (documentación y landing page) se despliegan en Cloudflare Pages, aprovechando la red edge global y el deploy automático.

4.1 Proyectos en CF Pages

4.2 Configuración de Build

4.3 Configuración en Pages Dashboard

nvito-docs:

nvito-landing (Astro — Producción en CF Pages):

nvito-landing (Astro — DEV/TEST en Coolify):

4.4 Custom Domain + CF Access

Para docs.nvito.mx:

1. Conectar repositorio GitLab a Cloudflare Pages
2. Configurar custom domain en CF Pages dashboard
3. CF agrega CNAME automáticamente: docs.nvito.mx → nvito-docs.pages.dev
4. Habilitar CF Access en el subdominio (requiere autenticación del equipo)

4.5 nvito-docs — Métricas de Build

5. CI/CD GitLab

5.1 Pipeline Stages

5.2 Stage Quality

Se ejecuta en cada push a develop, test, main y en merge requests. Contiene 2 jobs paralelos:

Job lint:

lint:
  stage: quality
  script:
    - npm ci --cache $NPM_CONFIG_CACHE
    - npm run lint
    - npm run format:check

Job test:unit:

test:unit:
  stage: quality
  services:
    - postgres:15-alpine
  variables:
    POSTGRES_DB: nvito_test
    DATABASE_URL: "postgresql://test:test@postgres:5432/nvito_test"
  script:
    - npm ci --cache $NPM_CONFIG_CACHE
    - npx prisma generate
    - npx prisma migrate deploy
    - npm run test:ci
  artifacts:
    reports:
      junit: junit.xml
      coverage_report:
        coverage_format: cobertura
        path: coverage/cobertura-coverage.xml
    expire_in: 30 days

5.3 Stage Migrate

Se ejecuta solo cuando hay cambios en prisma/migrations/**/*. Usa Bitwarden Secrets Manager (BWS) para obtener la DATABASE_URL del ambiente correspondiente.

5.4 Estrategia de Branching

Flujo:

feature/xyz → MR a develop → merge → deploy DEV
develop → merge a test → deploy TEST
test → merge a main → deploy PROD

5.5 Variables de CI/CD en GitLab

Todos los demás secretos (DATABASE_URL, API keys, tokens) se almacenan en Bitwarden Secrets Manager y se inyectan via bws run en runtime.

5.6 Estado Actual

6. Dockerfiles y Multi-Stage Builds

Todos los proyectos de Nvito usan Dockerfiles multi-stage para producir imágenes mínimas y seguras.

6.1 Patrón Común (3 Stages)

6.2 Ejemplo: nvito-api Dockerfile

# Stage 1: Install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts

# Stage 2: Build application
FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npx prisma generate
RUN npm run build
RUN npm prune --production

# Stage 3: Production runtime
FROM node:20-alpine AS runtime
RUN apk add --no-cache dumb-init
WORKDIR /app
USER node

COPY --from=build --chown=node:node /app/dist ./dist
COPY --from=build --chown=node:node /app/node_modules ./node_modules
COPY --from=build --chown=node:node /app/prisma ./prisma
COPY --from=build --chown=node:node /app/package.json ./

EXPOSE 3000
CMD ["dumb-init", "node", "dist/main.js"]

6.3 Ejemplo: nvito-admin Dockerfile (Next.js Standalone)

# Stage 1: Dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

# Stage 2: Build
FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
# NEXT_PUBLIC_* variables must be available at build time
ARG NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
ARG NEXT_PUBLIC_API_URL
ENV NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=$NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY
ENV NEXT_PUBLIC_API_URL=$NEXT_PUBLIC_API_URL
RUN npm run build

# Stage 3: Runtime (standalone output)
FROM node:20-alpine AS runtime
RUN apk add --no-cache dumb-init
WORKDIR /app
USER node

COPY --from=build --chown=node:node /app/.next/standalone ./
COPY --from=build --chown=node:node /app/.next/static ./.next/static
COPY --from=build --chown=node:node /app/public ./public

EXPOSE 5050
ENV PORT=5050
CMD ["dumb-init", "node", "server.js"]

6.4 Buenas Prácticas en los Dockerfiles

7. Rollback

Cada plataforma de hosting ofrece mecanismos de rollback en caso de deploy fallido.

7.1 Railway

Railway mantiene historial de todos los deployments. El rollback vía dashboard es instantáneo porque reutiliza la imagen Docker ya construida.

7.2 Coolify

7.3 Cloudflare Pages

CF Pages mantiene todos los deployments históricos como snapshots inmutables. El rollback es instantáneo.

7.4 Base de Datos

7.5 Diagrama de Decisión de Rollback