Infraestructura y Ambientes

Tabla de Contenidos

1. Mapa de Infraestructura por Ambiente
2. Proveedores por Servicio
3. Docker Compose Local
4. Coolify — Hosting Remoto
5. Variables de Entorno por Ambiente
6. Topologia de Red

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).
• Limitacion: 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).
• Justificacion: Redis almacena datos efimeros (cache + Bull queues); sin riesgo de colision.
• 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 publico: Habilitado en uploads, assets y templates. Deshabilitado en private.
• CORS: Configurado por ambiente con los origenes correspondientes.

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 Configuracion Clave

PostgreSQL — Usuario nvito, password nvito_dev_password, DB nvito_dev. Incluye healthcheck con pg_isready y scripts de inicializacion 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 publico en los tres primeros.

MailDev — SMTP en :1025 sin autenticacion. 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 6 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 automatico.

4.4 Conexion con GitLab

Coolify v4 no tiene integracion 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: Deteccion Local vs Remoto

La configuracion de storage (storage.config.ts) se adapta automaticamente. 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 deteccion de MinIO usa R2_ENDPOINT.includes('localhost') para decidir como construir URLs publicas.

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 Gestion 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 segun el dominio.
4. nvito-admin-dev renderiza la pagina (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>

6.3 Costos Mensuales