1. Visión General
Nvito opera en 4 ambientes que reflejan el ciclo de vida del código desde el desarrollo hasta producción. Cada ambiente tiene su propia infraestructura de datos (BD, Redis, Storage, Email) y subdominios independientes.
Flujo de Promocion entre Ambientes
LOCALDocker Compose — localhost
DEVVPS + Coolify — dev-*.nvito.mx
TESTVPS + Coolify — test-*.nvito.mx
PRODRailway Pro — *.nvito.mx
| Ambiente | Branch | Propósito | Usuarios | Hosting |
|---|---|---|---|---|
| Local | cualquiera | Desarrollo individual, debugging, iteración rápida | Desarrolladores | Docker Compose (máquina local) |
| DEV | develop | Integración continua, validación de features | Desarrolladores | VPS Contabo + Coolify |
| TEST | test | QA formal, pruebas de regresión, demos a stakeholders | QA + stakeholders | VPS Contabo + Coolify |
| PROD | main | Producción real con usuarios finales | Todos | Railway Pro + Cloudflare |
2. Ambiente Local (Docker Compose)
El ambiente local replica toda la infraestructura de Nvito en la máquina del desarrollador usando Docker Compose. Permite trabajar sin conexión a internet y con iteraciones rápidas.
2.1 Arquitectura Local
Ambiente Local — Docker Compose
Aplicaciones (procesos locales)
nvito-adminNext.js :5050
nvito-invitationsNext.js :3001
nvito-pwaNext.js :3002
nvito-docsNext.js :3333
nvito-landingAstro :4321
Docker Compose
Adminer:8080
MinIO ClientCrea buckets al iniciar
Aplicaciones (procesos locales)
nvito-apiNestJS :3000
Docker Compose
MinIO:9000 API / :9001 Console
Servicios Cloud (obligatorios)
Clerk AuthDev mode, cloud
Docker Compose
PostgreSQL 15:5432
Redis 7:6379
MailDev:1025 SMTP / :1080 Web
2.2 Servicios Docker y Puertos
| Servicio | Imagen | Puerto(s) | Función | Datos persisten |
|---|---|---|---|---|
| postgres | postgres:15-alpine | 5432 | Base de datos principal (Prisma ORM) | Sí (volumen externo) |
| redis | redis:7-alpine | 6379 | Cache, Bull queues, rate limiting | Sí (volumen externo, AOF) |
| minio | minio/minio:latest | 9000 (API), 9001 (Console) | Storage S3-compatible (reemplaza R2) | Sí (volumen externo) |
| minio-client | minio/mc:latest | — | Crea 4 buckets automáticamente al iniciar | N/A |
| maildev | maildev/maildev:latest | 1080 (Web UI), 1025 (SMTP) | Servidor SMTP local (reemplaza Mailtrap) | No (efímero) |
| adminer | adminer:latest | 8080 | UI web para gestión de PostgreSQL | No (efímero) |
2.3 Aplicaciones Locales y Puertos
| Aplicación | Puerto | Comando | Descripción |
|---|---|---|---|
| nvito-api | 3000 | npm run start:dev | Backend NestJS con hot reload |
| nvito-admin | 5050 | npm run dev | Panel admin Next.js |
| nvito-invitations | 3001 | npm run dev | Servidor de invitaciones |
| nvito-pwa | 3002 | npm run dev | Progressive Web App |
| nvito-landing | 4321 | npm run dev | Landing page + smart link |
| nvito-docs | 3333 | npm run dev | Hub de documentación |
2.4 Setup Inicial
# 1. Crear volumenes Docker (una sola vez)
docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data
# 2. Levantar infraestructura
cd nvito-api
docker compose up -d
# 3. Verificar que todos los servicios están healthy
docker compose ps
# 4. Aplicar migraciones de BD
npx prisma migrate deploy
# 5. Iniciar la aplicación
npm run start:dev
2.5 Credenciales Locales
| Servicio | Usuario | Password | URL de acceso |
|---|---|---|---|
| PostgreSQL | nvito | nvito_dev_password | postgresql://nvito:nvito_dev_password@localhost:5432/nvito_dev |
| Redis | — | — (sin auth) | redis://localhost:6379 |
| MinIO | minioadmin | minioadmin123 | http://localhost:9001 (Console) |
| MailDev | — | — | http://localhost:1080 (Web UI) |
| Adminer | nvito | nvito_dev_password | http://localhost:8080 |
2.6 Buckets de MinIO
El servicio minio-client crea automáticamente 4 buckets al iniciar:
| Bucket | Acceso público | Contenido |
|---|---|---|
nvito-uploads | Sí | Fotos de galería, avatares, logos |
nvito-assets | Sí | Assets estáticos de invitaciones |
nvito-private | No | Contratos, documentos internos |
nvito-templates | Sí | Templates HTML compilados de invitaciones |
Clerk requiere internet
Clerk Auth siempre se conecta a la nube (no hay modo offline). Las claves pk_test_ y sk_test_ del modo desarrollo de Clerk son necesarias incluso en local. Es el único servicio externo obligatorio.
3. Ambiente DEV (VPS + Coolify)
El ambiente DEV refleja la rama develop y se usa para integración continua. Los desarrolladores ven aquí sus cambios desplegados automáticamente después de cada push.
3.1 Infraestructura
| Componente | Proveedor | Detalle |
|---|---|---|
| Hosting | VPS Contabo (Cloud VPS 10) | 4 vCPU, 8 GB RAM, 150 GB SSD, Ubuntu 22.04 |
| IP | 212.28.185.197 | Compartida con TEST |
| PaaS | Coolify v4 | Gestión de contenedores Docker |
| Reverse Proxy | Traefik | Integrado en Coolify |
| SSL | Cloudflare Origin Certificate | Certificado de 15 años, modo Full (Strict) |
| Base de datos | Neon PostgreSQL (Free) | Proyecto nvito-dev, 0.5 GB, auto-suspend 5 min |
| Cache/Colas | Upstash Redis (Free) | 256 MB, 500K cmds/mes, TLS, compartido con TEST |
| Storage | Cloudflare R2 (Free) | 4 buckets con prefijo dev-nvito-* |
| Mailtrap (Free) | 100 emails/mes, inbox visual | |
| Auth | Clerk (Dev mode) | Instancia compartida con TEST |
3.2 Subdominios y Servicios
| Servicio | Branch | Subdominio | Puerto interno |
|---|---|---|---|
| nvito-api-dev | develop | dev-api.nvito.mx | 3000 |
| nvito-admin-dev | develop | dev-admin.nvito.mx | 5050 |
| nvito-invitations-dev | develop | dev-inv.nvito.mx | 3001 |
| nvito-pwa-dev | develop | dev-app.nvito.mx | 3002 |
| nvito-landing-dev | develop | dev-landing.nvito.mx | 4000 |
3.3 Flujo de Deploy
Deploy DEV — Pipeline CI + Coolify
Desarrollador
GitLab
GitLab CI
Bitwarden SM
Neon PostgreSQL
Coolify
Docker Engine
git push develop
par[Pipeline CI + Auto-deploy]
Trigger quality + migrate
lint + test:unit
Solicitar DATABASE_URL
prisma migrate deploy
else[Auto-deploy]
Webhook POST
git pull (deploy key SSH)
docker build (multi-stage)
Health check OK
Traefik actualiza routing
Desarrollador
GitLab
GitLab CI
Bitwarden SM
Neon PostgreSQL
Coolify
Docker Engine
3.4 Limitaciones del Ambiente DEV
| Limitación | Impacto | Workaround |
|---|---|---|
| Neon auto-suspend | BD duerme tras 5 min inactiva; primer query tarda 3-5s | Cold start esperado, no afecta desarrollo |
| Upstash compartido | DEV y TEST usan la misma DB Redis | Datos efímeros (cache + queues), sin colisión en la práctica |
| Mailtrap 100/mes | Límite de 100 emails en free tier | Suficiente para desarrollo; emails se ven en inbox visual |
| VPS compartido | DEV y TEST comparten el mismo VPS | 8 GB RAM bastan para 8 contenedores ligeros |
4. Ambiente TEST (VPS + Coolify)
El ambiente TEST refleja la rama test y se usa para QA formal antes de producción. Su estructura es idéntica a DEV con la única diferencia del prefijo de subdominios y la base de datos.
4.1 Diferencias con DEV
| Aspecto | DEV | TEST |
|---|---|---|
| Branch | develop | test |
| Subdominios | dev-*.nvito.mx | test-*.nvito.mx |
| Base de datos Neon | Proyecto nvito-dev | Proyecto nvito-test |
| Buckets R2 | dev-nvito-* | test-nvito-* |
| Propósito | Integración rápida | QA formal, regresión |
| Quién lo usa | Desarrolladores | QA + stakeholders |
4.2 Subdominios TEST
| Servicio | Branch | Subdominio |
|---|---|---|
| nvito-api-test | test | test-api.nvito.mx |
| nvito-admin-test | test | test-admin.nvito.mx |
| nvito-invitations-test | test | test-inv.nvito.mx |
| nvito-pwa-test | test | test-app.nvito.mx |
| nvito-landing-test | test | test-landing.nvito.mx |
TEST como staging
El ambiente TEST funciona como staging. Todo cambio que llega aquí ya pasó por DEV y los tests automatizados. Las demos a stakeholders y las validaciones finales se hacen en TEST antes de promover a producción.
5. Ambiente PROD (Railway)
El ambiente de producción corre en Railway (actualmente plan Hobby, con upgrade a Pro planificado al lanzar). El proyecto nvito-prod contiene 5 servicios: 4 aplicaciones web + PostgreSQL, comunicados vía private networking.
5.1 Arquitectura de Producción
Arquitectura de Produccion
Cloudflare Edge
DNS + Proxy
WAF + DDoS + Rate Limiting
Cloudflare Edge
Worker Proxynvito-api-proxy (api.nvito.mx)
CF Accessadmin + docs
nvito-landingnvito.mx (CF Pages)
nvito-docsdocs.nvito.mx (CF Pages)
R2 CDNcdn.nvito.mx — 4 buckets PROD
Railway nvito-prod (Private Network)
nvito-invitationsNext.js :3001
nvito-pwaNext.js :3002
Railway nvito-prod (Private Network)
nvito-apiNestJS :3000
nvito-adminNext.js :5050
Railway nvito-prod (Private Network)
PostgreSQLRailway managed
Servicios Managed
Upstash Redis
Resend Emailsend.nvito.mx
Clerk AuthProd keys
5.2 Servicios en Railway
| Servicio | Custom Domain | Puerto | Dominio Railway generado | Estado |
|---|---|---|---|---|
| nvito-api | api.nvito.mx (vía Worker) | 3000 | nvito-api-production.up.railway.app | Creado (sin deploy) |
| nvito-admin | admin.nvito.mx | 5050 | — | Creado (sin deploy) |
| nvito-invitations | inv.nvito.mx | 3001 | — | Creado (sin deploy) |
| nvito-pwa | app.nvito.mx | 3002 | — | Creado (sin deploy) |
| PostgreSQL | — (private network) | 5432 | — | Creado (sin migraciones) |
Estado actual
Los 4 servicios están creados como "Empty Service" en Railway. Falta conectar los repositorios de GitLab para habilitar auto-deploy (tarea pendiente P3). Las variables de entorno de producción también están pendientes de configuración (tarea P1).
5.3 Private Networking
Railway ofrece una red privada interna entre servicios del mismo proyecto. Esto significa que:
- nvito-admin, nvito-invitations y nvito-pwa se comunican con nvito-api vía
http://nvito-api.railway.internal:3000(sin SSL overhead, sin internet) - PostgreSQL es accesible solo desde la red privada, no tiene IP pública
- nvito-api tiene un dominio público generado (
nvito-api-production.up.railway.app) que usa el Cloudflare Worker como origin - Los otros 3 servicios tienen custom domains directos (admin, inv, app)
- La latencia interna es inferior a 1ms
Railway Private Network
Internet
Usuarios
CF Workerapi.nvito.mx
Railway Private Network (nvito-prod)
nvito-api:3000
nvito-admin:5050
nvito-invitations:3001
nvito-pwa:3002
Railway Private Network (nvito-prod)
PostgreSQL:5432
5.4 Email en Producción
Nvito separa el correo corporativo del transaccional con dos dominios distintos:
Email en Produccion
nvito.mx — Correo Corporativo
Recibir: CF Email Routing→ nvito.hq@gmail.com
Enviar: Gmail "Enviar como"→ SMTP gmail.com
hola@ / soporte@ / contacto@
send.nvito.mx — Email Transaccional
nvito-api → Bull Queue→ Resend SMTP
Reply-To: hola@nvito.mx
noreply@ / eventos@
| Aspecto | Corporativo (nvito.mx) | Transaccional (send.nvito.mx) |
|---|---|---|
| Proveedor | Cloudflare Email Routing + Gmail | Resend |
| SMTP | smtp.gmail.com | smtp.resend.com:465 |
| Direcciones | hola@, soporte@, contacto@ | noreply@, eventos@ |
| Volumen | Bajo (manual) | Alto (automático, Bull queues) |
| Plan | Free | Free (3K/mes, 100/dia) |
5.5 R2 Buckets de Producción
| Bucket | Acceso público | Contenido |
|---|---|---|
nvito-uploads | Sí (vía cdn.nvito.mx) | Fotos de galería, avatares, logos |
nvito-assets | Sí | Assets estáticos de invitaciones |
nvito-templates | Sí | Templates HTML compilados |
nvito-private | No | Contratos, documentos internos |
CORS configurado para todos los subdominios *.nvito.mx.
5.6 Diferencias Clave con DEV/TEST
| Aspecto | DEV/TEST | PROD |
|---|---|---|
| Hosting | VPS + Coolify (self-managed) | Railway (managed) |
| Plan Railway | — | Hobby (upgrade a Pro al lanzar) |
| Base de datos | Neon Free (auto-suspend) | Railway PostgreSQL (always-on) |
| Mailtrap (testing) | Resend en send.nvito.mx (producción) | |
| API Proxy | Directo (A record a VPS) | CF Worker + CloudflareTokenGuard |
| Auth keys | Clerk pk_test_ / sk_test_ | Clerk pk_live_ / sk_live_ |
| R2 Buckets | {env}-nvito-* | nvito-* (sin prefijo, 4 buckets) |
| CF Access | Solo admin | admin + docs |
| SSL origin | CF Origin Certificate (15 años) | Railway auto-SSL |
| Landing | — | Astro 5.x en CF Pages (nvito.mx), SSR /join/[token] para deeplinks |
6. Tabla Comparativa de Ambientes
| Servicio | Local | DEV | TEST | PROD |
|---|---|---|---|---|
| Base de datos | PostgreSQL 15 (Docker) | Neon Free (nvito-dev) | Neon Free (nvito-test) | Railway PostgreSQL |
| Cache / Colas | Redis 7 (Docker) | Upstash Free (compartido) | Upstash Free (compartido) | Upstash Pro o Free |
| Storage (S3) | MinIO (Docker) | R2 Free (dev-nvito-*) | R2 Free (test-nvito-*) | R2 Free (nvito-*) |
| MailDev (Docker) | Mailtrap Free | Mailtrap Free | Resend ($20/mes o Free) | |
| Auth | Clerk Dev (cloud) | Clerk Dev (cloud) | Clerk Dev (cloud) | Clerk Prod (cloud) |
| Hosting apps | Procesos locales | Coolify + VPS | Coolify + VPS | Railway Pro |
| CDN | MinIO directo | R2 public URL | R2 public URL | cdn.nvito.mx (R2 custom domain) |
| Deploy | Manual | Auto (Coolify webhook) | Auto (Coolify webhook) | Auto (Railway git deploy) |
| SSL | — (HTTP) | CF Origin Certificate (15 años) | CF Origin Certificate (15 años) | Railway auto-SSL |
| Dominio | localhost:* | dev-*.nvito.mx | test-*.nvito.mx | *.nvito.mx |
7. Variables de Entorno por Ambiente
7.1 Variables Críticas
| Variable | Local | DEV | TEST | PROD |
|---|---|---|---|---|
NODE_ENV | development | production | production | production |
DATABASE_URL | postgresql://nvito:...@localhost:5432/nvito_dev | Neon pooled URL | Neon pooled URL | Railway private URL |
REDIS_URL | redis://localhost:6379 | rediss://...@upstash.io:6379 | misma Upstash DB | Upstash TLS URL |
CORS_ORIGINS | http://localhost:5050,... | https://dev-admin.nvito.mx,... | https://test-admin.nvito.mx,... | https://admin.nvito.mx,... |
FRONTEND_URL | http://localhost:3001 | https://dev-inv.nvito.mx | https://test-inv.nvito.mx | https://inv.nvito.mx |
CDN_URL | http://localhost:9000/nvito-uploads | R2 public URL (dev) | R2 public URL (test) | https://cdn.nvito.mx |
APP_DEEP_LINK_URL | http://localhost:4000 | https://dev-landing.nvito.mx | https://test-landing.nvito.mx | https://nvito.mx |
7.2 Variables de Autenticación
| Variable | Local | DEV/TEST | PROD |
|---|---|---|---|
CLERK_SECRET_KEY | sk_test_... | sk_test_... | sk_live_... |
CLERK_PUBLISHABLE_KEY | pk_test_... | pk_test_... | pk_live_... |
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY | pk_test_... | pk_test_... | pk_live_... |
7.3 Variables de Storage
| Variable | Local | DEV/TEST | PROD |
|---|---|---|---|
R2_ENDPOINT | http://localhost:9000 | — (usa R2_ACCOUNT_ID) | — |
R2_ACCOUNT_ID | — | Cloudflare Account ID | Cloudflare Account ID |
R2_ACCESS_KEY_ID | minioadmin | R2 API Token | R2 API Token |
R2_SECRET_ACCESS_KEY | minioadmin123 | R2 API Secret | R2 API Secret |
R2_BUCKET_UPLOADS | nvito-uploads | dev-nvito-uploads | nvito-uploads |
R2_BUCKET_ASSETS | nvito-assets | dev-nvito-assets | nvito-assets |
R2_BUCKET_PRIVATE | nvito-private | dev-nvito-private | nvito-private |
R2_BUCKET_TEMPLATES | nvito-templates | dev-nvito-templates | nvito-templates |
7.4 Variables de Email
| Variable | Local | DEV/TEST | PROD |
|---|---|---|---|
SMTP_HOST | localhost | sandbox.smtp.mailtrap.io | smtp.resend.com |
SMTP_PORT | 1025 | 2525 | 465 |
SMTP_USER | — (vacío) | Credenciales Mailtrap | resend |
SMTP_PASSWORD | — (vacío) | Credenciales Mailtrap | Resend API Key |
SMTP_FROM | nvito@localhost | test@nvito.mx | noreply@send.nvito.mx |
CF_API_TOKEN | — (no usado) | — (no usado) | Token secreto para CloudflareTokenGuard |
7.5 Archivos de Entorno por Proyecto
Cada proyecto tiene archivos .env específicos para ambientes remotos:
| Proyecto | Archivos | Variables actualizadas para *.nvito.mx |
|---|---|---|
| nvito-api | .env.dev-remote, .env.test-remote | FRONTEND_URL, ADMIN_URL, CORS_ORIGINS, INVITATIONS_WEBHOOK_URL, CDN_URL, CDN_ALLOWED_ORIGINS, APP_DEEP_LINK_URL |
| nvito-admin | next.config.ts | CSP img-src actualizado de cdn.nvito.com a cdn.nvito.mx |
| nvito-invitations | next.config.mjs | frame-ancestors actualizado con *.nvito.mx |
| nvito-pwa | .env.example | URLs actualizadas a *.nvito.mx |
| nvito-client | .env.example | URLs actualizadas a *.nvito.mx |
| nvito-landing | .env | PUBLIC_PWA_URL (URL de la PWA para fallback en smart link) |
Consistencia de URLs
Todas las variables de entorno que referencian subdominios de Nvito usan el patrón {env}-{service}.nvito.mx en DEV/TEST y {service}.nvito.mx en producción. Al agregar un nuevo servicio, actualizar todas las variables de CORS y URL en los archivos de entorno de cada proyecto.
7.7 Detección Automática de Storage
La configuración de storage (storage.config.ts en nvito-api) se adapta automáticamente al ambiente:
Deteccion Automatica de Storage
Inicializacion de StorageService
R2_ENDPOINT contiene localhost?
Si
Modo MinIO Local
Modo Cloudflare R2
URL: http://localhost:9000/{bucket}/{key}
URL: https://cdn.nvito.mx/{key}
7.8 Gestión de Secretos
| Ambiente | Almacenamiento | Herramienta |
|---|---|---|
| Local | Archivo .env (gitignored) | Opcionalmente bws CLI |
| DEV/TEST | Dashboard Coolify (por servicio) | Secretos críticos en Bitwarden SM |
| CI/CD | GitLab Variables (BWS_ACCESS_TOKEN) | bws run inyecta en runtime |
| PROD | Dashboard Railway (por servicio) | Bitwarden SM para rotación |
Nunca commitear secretos
Los archivos .env están en .gitignore. Las variables NEXT_PUBLIC_* son públicas por definición (se embeben en el JS del browser). Todo lo demás es secreto y debe gestionarse vía dashboard del proveedor o Bitwarden Secrets Manager.