Ambientes

Tabla de Contenidos

Vision General
Ambiente Local (Docker Compose)
Ambiente DEV (VPS + Coolify)
Ambiente TEST (VPS + Coolify)
Ambiente PROD (Railway Pro)
Tabla Comparativa de Ambientes
Variables de Entorno por Ambiente

Nvito opera en 4 ambientes que reflejan el ciclo de vida del codigo desde el desarrollo hasta produccion. Cada ambiente tiene su propia infraestructura de datos (BD, Redis, Storage, Email) y subdominios independientes.

Ambiente	Branch	Proposito	Usuarios	Hosting
Local	cualquiera	Desarrollo individual, debugging, iteracion rapida	Desarrolladores	Docker Compose (maquina local)
DEV	`develop`	Integracion continua, validacion de features	Desarrolladores	VPS Contabo + Coolify
TEST	`test`	QA formal, pruebas de regresion, demos a stakeholders	QA + stakeholders	VPS Contabo + Coolify
PROD	`main`	Produccion real con usuarios finales	Todos	Railway Pro + Cloudflare

2. Ambiente Local (Docker Compose)

El ambiente local replica toda la infraestructura de Nvito en la maquina del desarrollador usando Docker Compose. Permite trabajar sin conexion a internet y con iteraciones rapidas.

2.1 Arquitectura Local

2.2 Servicios Docker y Puertos

Servicio	Imagen	Puerto(s)	Funcion	Datos persisten
postgres	`postgres:15-alpine`	`5432`	Base de datos principal (Prisma ORM)	Si (volumen externo)
redis	`redis:7-alpine`	`6379`	Cache, Bull queues, rate limiting	Si (volumen externo, AOF)
minio	`minio/minio:latest`	`9000` (API), `9001` (Console)	Storage S3-compatible (reemplaza R2)	Si (volumen externo)
minio-client	`minio/mc:latest`	—	Crea 4 buckets automaticamente al iniciar	N/A
maildev	`maildev/maildev:latest`	`1080` (Web UI), `1025` (SMTP)	Servidor SMTP local (reemplaza Mailtrap)	No (efimero)
adminer	`adminer:latest`	`8080`	UI web para gestion de PostgreSQL	No (efimero)

2.3 Aplicaciones Locales y Puertos

Aplicacion	Puerto	Comando	Descripcion
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-docs	3333	`npm run dev`	Hub de documentacion

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 estan healthy
docker compose ps

# 4. Aplicar migraciones de BD
npx prisma migrate deploy

# 5. Iniciar la aplicacion
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 automaticamente 4 buckets al iniciar:

Bucket	Acceso publico	Contenido
`nvito-uploads`	Si	Fotos de galeria, avatares, logos
`nvito-assets`	Si	Assets estaticos de invitaciones
`nvito-private`	No	Contratos, documentos internos
`nvito-templates`	Si	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 unico servicio externo obligatorio.

3. Ambiente DEV (VPS + Coolify)

El ambiente DEV refleja la rama develop y se usa para integracion continua. Los desarrolladores ven aqui sus cambios desplegados automaticamente despues 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	Gestion de contenedores Docker
Reverse Proxy	Traefik	Integrado en Coolify, SSL Let's Encrypt
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-*`
Email	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

3.3 Flujo de Deploy

3.4 Limitaciones del Ambiente DEV

Limitacion	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 efimeros (cache + queues), sin colision en la practica
Mailtrap 100/mes	Limite 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 produccion. Su estructura es identica a DEV con la unica 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-*`
Proposito	Integracion rapida	QA formal, regresion
Quien 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`

TEST como staging

El ambiente TEST funciona como staging. Todo cambio que llega aqui ya paso por DEV y los tests automatizados. Las demos a stakeholders y las validaciones finales se hacen en TEST antes de promover a produccion.

5. Ambiente PROD (Railway Pro)

El ambiente de produccion esta planeado para correr en Railway Pro, aprovechando su private networking, auto-deploy, y escalado vertical sin overhead de gestion de servidores.

5.1 Arquitectura de Produccion

5.2 Servicios en Railway

Servicio	Custom Domain	Tipo	Estimacion de recursos
nvito-api	`api.nvito.mx` (via Worker)	Web Service	512 MB RAM, 1 vCPU
nvito-admin	`admin.nvito.mx`	Web Service	256 MB RAM, 0.5 vCPU
nvito-invitations	`inv.nvito.mx`	Web Service	256 MB RAM, 0.5 vCPU
nvito-pwa	`app.nvito.mx`	Web Service	256 MB RAM, 0.5 vCPU
PostgreSQL	— (private network)	Database	1 GB RAM, 10 GB storage

5.3 Private Networking

Railway Pro 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 via http://nvito-api.railway.internal:3000 (sin SSL overhead, sin internet)
PostgreSQL es accesible solo desde la red privada, no tiene IP publica
La latencia interna es de menos de 1ms

5.4 Diferencias Clave con DEV/TEST

Aspecto	DEV/TEST	PROD
Hosting	VPS + Coolify (self-managed)	Railway Pro (managed)
Base de datos	Neon Free (auto-suspend)	Railway PostgreSQL (always-on)
Email	Mailtrap (testing)	Resend (produccion)
API Proxy	Directo (A record a VPS)	Cloudflare Worker (oculta origin)
Auth keys	Clerk `pk_test_` / `sk_test_`	Clerk `pk_live_` / `sk_live_`
R2 Buckets	`{env}-nvito-*`	`nvito-*` (sin prefijo)
CF Access	Solo admin	admin + docs
SSL origin	Let's Encrypt (Coolify)	Railway auto-SSL

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-*`)
Email	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)	Let's Encrypt (Traefik)	Let's Encrypt (Traefik)	Railway auto-SSL
Dominio	`localhost:*`	`dev-*.nvito.mx`	`test-*.nvito.mx`	`*.nvito.mx`

7. Variables de Entorno por Ambiente

7.1 Variables Criticas

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`

7.2 Variables de Autenticacion

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`	— (vacio)	Credenciales Mailtrap	`resend`
`SMTP_PASSWORD`	— (vacio)	Credenciales Mailtrap	Resend API Key
`SMTP_FROM`	`nvito@localhost`	`test@nvito.mx`	`noreply@nvito.mx`

7.5 Deteccion Automatica de Storage

La configuracion de storage (storage.config.ts en nvito-api) se adapta automaticamente al ambiente:

7.6 Gestion de Secretos

Ambiente	Almacenamiento	Herramienta
Local	Archivo `.env` (gitignored)	Opcionalmente `bws` CLI
DEV/TEST	Dashboard Coolify (por servicio)	Secretos criticos en Bitwarden SM
CI/CD	GitLab Variables (`BWS_ACCESS_TOKEN`)	`bws run` inyecta en runtime
PROD	Dashboard Railway (por servicio)	Bitwarden SM para rotacion

Nunca commitear secretos

Los archivos .env estan en .gitignore. Las variables NEXT_PUBLIC_* son publicas por definicion (se embeben en el JS del browser). Todo lo demas es secreto y debe gestionarse via dashboard del proveedor o Bitwarden Secrets Manager.