Cómo conectar una app a la infraestructura central

Cuadrante 02_HOW_TO — pasos concretos para configurar DATABASE_URL, REDIS_URL y QDRANT_URL en cualquier vertical del monorepo. Para entender por qué la arquitectura es así → ../04_EXPLANATION/postgres-multitenancy.md Para la referencia completa de todas las variables → ../03_REFERENCE/services-catalog.md

Pre-requisitos

infra/core levantado (./manage.sh up infra-core)
.env de tu vertical copiado desde .env.example

1. Conectar al PostgreSQL multi-tenant

Cada vertical tiene su propio usuario y base de datos. Usa el container_name del postgres como host: timeliber-postgres.

Formato general:

postgresql+asyncpg://USUARIO:PASSWORD@timeliber-postgres:5432/NOMBRE_DB

⚠️ Siempre usar +asyncpg en backends FastAPI. El driver síncrono (postgresql://) bloquea el event loop bajo carga concurrente.

Por vertical — copiar directamente al .env de la app:

# apps/gastro/backend/.env
DATABASE_URL=postgresql+asyncpg://gastro_user:TU_GASTRO_PASS@timeliber-postgres:5432/gastro_db

# apps/travel/backend/.env
DATABASE_URL=postgresql+asyncpg://travel_user:TU_TRAVEL_PASS@timeliber-postgres:5432/travel_db

# apps/main/backend/.env
DATABASE_URL=postgresql+asyncpg://main_user:TU_MAIN_PASS@timeliber-postgres:5432/main_db

# apps/foveo/backend/.env
DATABASE_URL=postgresql+asyncpg://foveo_user:TU_FOVEO_PASS@timeliber-postgres:5432/foveo_db

Commerce separa migraciones y runtime para que RLS no pueda ser evitado por ownership:

DATABASE_MIGRATION_URL=postgresql+asyncpg://commerce_owner:TU_OWNER_PASS@timeliber-postgres:5432/commerce_db
DATABASE_URL=postgresql+asyncpg://commerce_runtime:TU_RUNTIME_PASS@timeliber-postgres:5432/commerce_db
DATABASE_APP_ROLE=commerce_app

En producción esas URLs no se escriben en .env: se montan como Docker secrets database_migration_url y database_url. Para un volumen existente, usar el procedimiento de ../../../apps/commerce/docs/02_HOW_TO/deploy-shared-infra.md.

TimeLiber Connect usa otra base dentro del mismo motor, porque el session store Shopify tiene un boundary y ciclo de migración diferentes a los datos tenant de Commerce:

DATABASE_URL=postgresql://commerce_connect_runtime:TU_RUNTIME_PASS@timeliber-postgres:5432/commerce_connect_db
# Sólo en el job Prisma Migrate:
DATABASE_MIGRATION_URL=postgresql://commerce_connect_owner:TU_OWNER_PASS@timeliber-postgres:5432/commerce_connect_db

Estas URLs también se montan desde archivos Docker secret. No se copian tokens Shopify a commerce_db.

Servicios de infra que usan driver síncrono (no son FastAPI):

# infra/whatsapp — n8n (variables separadas, no un DATABASE_URL)
DB_POSTGRESDB_HOST=timeliber-postgres
DB_POSTGRESDB_DATABASE=n8n_db
DB_POSTGRESDB_USER=n8n_user
DB_POSTGRESDB_PASSWORD=TU_N8N_PASS

# infra/whatsapp — Evolution API (URI completa sin asyncpg)
DATABASE_CONNECTION_URI=postgresql://evolution_user:TU_EVOLUTION_PASS@timeliber-postgres:5432/evolution_db

2. Conectar a Redis 8

Redis tiene 16 bases de datos internas (0-15). Cada vertical usa una distinta para evitar colisiones de claves.

Formato:

redis://:PASSWORD@timeliber-redis:6379/NUMERO_DB

Distribución por vertical:

DB #	Vertical	`.env` de la app
`0`	Travel	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/0`
`1`	Evolution API	`CACHE_REDIS_URI=redis://:TU_PASS@timeliber-redis:6379/1`
`2`	Gastro	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/2`
`3`	Main API	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/3`
`4`	Foveo	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/4`
`5`	AI Orchestrator	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/5`
`6`	RAG Studio	`REDIS_URL=redis://:TU_PASS@timeliber-redis:6379/6`

3. Conectar a Qdrant (solo módulo AI)

Requiere que ./manage.sh up infra-ai esté activo.

# apps/ai-orchestrator/.env  y  apps/tools/rag/.env
QDRANT_URL=http://timeliber-qdrant:6333
QDRANT_API_KEY=TU_QDRANT_API_KEY

Colecciones por vertical (prefijo obligatorio para evitar colisiones):

Vertical	Colección
Gastro	`gastro_menus`
Travel	`travel_properties`
RAG Studio	`rag_documents`

4. Llamar a n8n / Evolution desde otra app

Desde dentro de timeliber-net se accede por nombre de container:

# Disparar un webhook de n8n desde Travel o Gastro backend
http://timeliber-n8n:5678/webhook/TU_WEBHOOK_ID

# Llamar la API de Evolution desde el AI Orchestrator
http://timeliber-evolution:8080/instance/fetchInstances

5. Enviar telemetría a Grafana (solo producción)

Requiere que ./manage.sh up infra-observability esté activo.

# Añadir a cualquier backend FastAPI (.env)
OTEL_EXPORTER_OTLP_ENDPOINT=http://timeliber-alloy:4318
OTEL_SERVICE_NAME=gastro-api          # Cambiar por nombre del servicio
OTEL_RESOURCE_ATTRIBUTES=deployment.environment=production

6. Verificar que la conexión funciona

# Probar PostgreSQL desde fuera del contenedor
docker exec timeliber-postgres psql -U gastro_user -d gastro_db -c "SELECT 1;"

# Probar Redis
docker exec timeliber-redis redis-cli -a TU_REDIS_PASS -n 2 ping

# Probar Qdrant
curl -H "api-key: TU_QDRANT_KEY" http://localhost:6333/collections

Referencias

../03_REFERENCE/services-catalog.md — puertos, redes y healthchecks de todos los servicios
../04_EXPLANATION/postgres-multitenancy.md — por qué un usuario por vertical
../04_EXPLANATION/networks-architecture.md — cómo funciona el DNS interno de Docker
../../core/.env.example — todas las contraseñas de infra/core

Actualizado 2026-08-31 — Commerce y session store Shopify sobre infra compartida.