Variables de Entorno y Checklist de Deploy

Variables de Entorno y Checklist de Deploy

Referencia de las variables que necesita la API en producción (fuente: .env.example y apps/api/src/env.ts) y el checklist ordenado del primer despliegue.

Variables de la API en Producción

Obligatorias

Variable	Valor en producción
DATABASE_URL	Connection string pooled de Neon (…-pooler.…)
REDIS_URL	URL TLS rediss://… de Upstash
BETTER_AUTH_SECRET	Secreto aleatorio de ≥ 32 caracteres
BETTER_AUTH_URL	https://api.uunit9.com
APP_URL	https://api.uunit9.com
WEB_URL	https://app.uunit9.com
CRON_SECRET	Secreto aleatorio

Workflows

Variable	Valor en producción
WORKFLOW_TARGET_WORLD	@workflow/world-postgres — ya fijada en la imagen (Dockerfile.api)
WORKFLOW_POSTGRES_URL	Endpoint directo de Neon (sin -pooler): graphile-worker abre LISTEN/NOTIFY

Scheduler

Variable	Valor en producción
SCHEDULER_ENABLED	true en una sola réplica; false en las demás
INVENTORY_CHECK_INTERVAL_MINUTES	Intervalo del chequeo de inventario (default 30)

Modelos

Variable	Valor en producción
MODEL_PROVIDER	nim
NVIDIA_API_KEY	API key de NVIDIA NIM
NIM_BASE_URL	https://integrate.api.nvidia.com/v1
NIM_MODEL_CHAT / NIM_MODEL_REASONING / NIM_MODEL_EMBEDDING	Modelos NIM

Opcionales (vacías = feature deshabilitada con warning)

Variable	Valor en producción
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS / SMTP_FROM	Cualquier proveedor SMTP real (Resend, SES, Brevo, …)
TELEGRAM_BOT_TOKEN / TELEGRAM_BOT_USERNAME	Token del bot de Telegram
LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY / LANGFUSE_HOST	Observabilidad LLM
R2_ACCOUNT_ID / R2_ACCESS_KEY_ID / R2_SECRET_ACCESS_KEY / R2_BUCKET	Cloudflare R2 (imágenes de menú)

Recordatorio: los endpoints /api/cron/* exigen el header x-cron-secret con el valor de CRON_SECRET (ver apps/api/AGENTS.md).

Checklist del Primer Deploy

1. Neon: crear el proyecto → ejecutar CREATE EXTENSION IF NOT EXISTS vector; en la consola SQL → copiar ambas connection strings (pooled → DATABASE_URL, directa → WORKFLOW_POSTGRES_URL, ambas con sslmode=require y sin channel_binding=require) → aplicar el schema con drizzle-kit push desde packages/db (con la cadena directa) → seed demo opcional.

2. R2: crear el bucket uunit9-assets + API token + habilitar acceso público (r2.dev o dominio custom).

3. Upstash: crear la base de datos Redis (solo si se usará el bot de Telegram).

4. Bootstrap del world de workflows contra Neon:

   WORKFLOW_POSTGRES_URL=<neon-url-directa> pnpm --filter api exec bootstrap

   Crea los schemas workflow_drizzle y graphile_worker; es idempotente y se ejecuta una sola vez antes del primer arranque.

5. Railway: crear el servicio desde Dockerfile.api, cargar las variables, dejar una réplica con SCHEDULER_ENABLED=true y verificar:

   curl https://api.uunit9.com/api/health

6. Cloudflare: configurar el DNS de los tres subdominios (app, api, docs); desplegar la web (Workers Static Assets + el worker proxy de Infraestructura de Producción); desplegar el sitio de docs en Pages.

7. Telegram: configurar el token y registrar el webhook:

   https://api.telegram.org/bot<TOKEN>/setWebhook?url=https://api.uunit9.com/api/webhooks/telegram

8. Verificación end-to-end: login con las credenciales demo en https://app.uunit9.com y crear una orden POS de prueba.