Infraestructura y Ambientes

1. Mapa de Infraestructura por Ambiente

Nvito opera en tres ambientes. Local se ejecuta en la maquina del desarrollador via Docker Compose. DEV y TEST corren en un VPS con Coolify, conectandose a servicios managed gratuitos en la nube.

Cada ambiente replica la misma arquitectura de servicios con proveedores distintos. En Local todo es autocontenido via Docker. En DEV/TEST los servicios de datos son managed en la nube (free tier), mientras que las aplicaciones corren como contenedores Docker en Coolify.

2. Proveedores por Servicio

2.1 Neon (PostgreSQL Remoto)

• Proyectos: 2 independientes (nvito-dev y nvito-test), cada uno con su connection string.
• Connection Pooler: PgBouncer integrado en modo Transaction, compatible con Prisma.
• URLs: Dos por proyecto: DATABASE_URL (pooled, para la app) y DIRECT_URL (directa, para migraciones).
• Limitación: Auto-suspend tras 5 min de inactividad; primer query al despertar tarda 3-5s.

2.2 Upstash (Redis Remoto)

• Database: 1 sola compartida DEV+TEST (free tier permite solo 1).
• Justificación: Redis almacena datos efímeros (cache + Bull queues); sin riesgo de colisión.
• Protocolo: rediss:// (TLS), soportado nativamente por Bull e ioredis.

2.3 Cloudflare R2 (Storage Remoto)

• Buckets: 8 en total (4 por ambiente): {dev|test}-nvito-{uploads,assets,private,templates}.
• Acceso público: Habilitado en uploads, assets y templates. Deshabilitado en private.
• CORS: Configurado por ambiente con los origenes correspondientes.

2.4 Cloudflare Pages (Sitios Estaticos)

Los sitios estáticos como nvito-landing (landing page) y nvito-docs (documentación) se despliegan directamente en Cloudflare Pages, sin pasar por Coolify/VPS. Esto permite:

• Despliegue automático al push a main
• CDN global con edge caching
• SSL automático
• $0 en hosting

3. Docker Compose Local

El archivo docker-compose.yml en nvito-api/ define 6 servicios que replican localmente la infraestructura managed remota.

3.1 Servicios y Puertos

3.2 Configuración Clave

PostgreSQL — Usuario nvito, password nvito_dev_password, DB nvito_dev. Incluye healthcheck con pg_isready y scripts de inicialización en ./docker/postgres/init/.

Redis — Persistencia con appendonly yes. Healthcheck via redis-cli ping.

MinIO — Credenciales minioadmin/minioadmin123. Console web en :9001. El servicio minio-client espera a que MinIO este healthy y luego crea los buckets nvito-uploads, nvito-assets, nvito-private y nvito-templates, configurando acceso público en los tres primeros.

MailDev — SMTP en :1025 sin autenticación. UI web para ver emails en http://localhost:1080.

3.3 Red y Volumenes

Todos los servicios comparten la red nvito-network (bridge). Los volumenes son externos y deben crearse antes del primer uso:

docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data

3.4 Uso Diario

cd nvito-api
docker compose up -d          # Iniciar infraestructura
docker compose ps             # Verificar estado
docker compose logs -f redis  # Logs de un servicio
docker compose down           # Detener (datos persisten)
docker compose down -v        # Detener + eliminar datos

4. Coolify — Hosting Remoto

4.1 Plataforma

4.2 Los 8 Servicios Docker

4.3 Flujo de Deploy

1. GitLab CI/CD ejecuta quality checks (lint, tests) y migraciones de BD si hay cambios en prisma/migrations/.
2. Coolify detecta el push via webhook, construye la imagen Docker y despliega el contenedor.
3. Traefik rutea el trafico al nuevo contenedor con SSL automático.

4.4 Conexión con GitLab

Coolify v4 no tiene integración nativa con GitLab. Se usa deploy keys: una SSH key generada en Coolify se agrega como Deploy Key en cada repo de GitLab. Cada servicio se configura como "Private Repository (with Deploy Key)".

4.5 Sin Suspension

Docker en VPS no duerme los contenedores. Esto es critico: nvito-api usa Bull queues con Redis para procesar emails, WhatsApp y jobs asincronos. Si el backend se suspende, los jobs en cola no se procesan.

5. Variables de Entorno por Ambiente

5.1 Variables Requeridas (env.validation.ts)

5.2 Diferencias Clave entre Ambientes

5.3 Storage: Detección Local vs Remoto

La configuración de storage (storage.config.ts) se adapta automáticamente. En Local se usa R2_ENDPOINT apuntando a MinIO. En DEV/TEST se usa R2_ACCOUNT_ID y el SDK construye la URL de R2. La detección de MinIO usa R2_ENDPOINT.includes('localhost') para decidir como construir URLs públicas.

5.4 Email: SMTP Unificado

Todos los ambientes usan SMTP via nodemailer. Local: MailDev sin auth (:1025). DEV/TEST: Mailtrap con auth (:2525). El transporte solo agrega auth si SMTP_USER tiene valor.

5.5 Gestión de Secretos

• Local: Archivo .env (excluido de git), opcionalmente via Bitwarden Secrets Manager (bws).
• DEV/TEST: Variables configuradas en Coolify por servicio. Secretos criticos en Bitwarden.
• CI/CD: GitLab variables + bws run para inyectar secretos de BD en migraciones.

6. Topologia de Red

6.1 Flujo de un Request

1. El usuario accede a https://dev-admin.nvito.mx.
2. DNS resuelve a la IP del VPS Contabo.
3. Traefik termina SSL y rutea al contenedor correcto según el dominio.
4. nvito-admin-dev renderiza la página (Next.js SSR) y llama a dev-api.nvito.mx.
5. nvito-api-dev valida JWT (Clerk), consulta Neon, lee/escribe Upstash y accede a R2.
6. La respuesta viaja de regreso por la misma ruta.

6.2 Registros DNS

Todos los subdominios apuntan a la misma IP. Traefik rutea por dominio:

dev-api.nvito.mx      A    <VPS_IP>
test-api.nvito.mx     A    <VPS_IP>
dev-admin.nvito.mx    A    <VPS_IP>
test-admin.nvito.mx   A    <VPS_IP>
dev.nvito.mx          A    <VPS_IP>
test.nvito.mx         A    <VPS_IP>
dev-app.nvito.mx      A    <VPS_IP>
test-app.nvito.mx     A    <VPS_IP>

6.3 Costos Mensuales

7. Versionado y Badge de Ambiente

7.1 Mapeo Formal de Ramas a Ambientes

Cada ambiente de Nvito está asociado a una rama específica de Git:

La rama test funciona como puente fijo: las ramas release/X.Y.Z se mergean a test para triggear el deploy automático sin reconfigurar Coolify.

Para más detalles sobre el flujo completo de ramas y releases, consulta la guía de Versionado y Gitflow.

7.2 Variables de Ambiente para Identificación

Dos variables controlan la identificación visual del ambiente en el dashboard admin:

7.3 Badge de Ambiente en el Admin

El componente EnvironmentBadge se muestra en el header del dashboard admin. Solo es visible en ambientes no productivos (LOCAL, DEV, TEST) y se oculta automáticamente en producción.

Al hacer clic en el badge se despliega un popover con información extendida: versión, ambiente y URL del API.