Variables de Entorno

Referencia completa de todas las variables configurables. Las variables del servidor van en .env.server (desarrollo) o como secrets en Fly.io (producción). Las variables del cliente van en .env.client.

---

Variables del Servidor (.env.server)

Base de Datos

Variable	Obligatoria	Dev	Producción
DATABASE_URL	Solo si no usas wasp start db	Auto (Wasp lo configura)	Connection string de Neon

Ejemplo de producción:

DATABASE_URL=postgresql://user:pass@ep-xxx.us-east-2.aws.neon.tech/neondb?sslmode=require

Importante: Neon requiere ?sslmode=require al final. Sin esto, la conexión falla.

---

Autenticación

Variable	Obligatoria	Dev	Producción
JWT_SECRET	Sí (en producción)	Cualquier string	openssl rand -base64 32

Generar un JWT_SECRET seguro:

openssl rand -base64 32

---

Pagos — Stripe

Variable	Obligatoria	Dev	Producción
STRIPE_API_KEY	Sí	sk_test_... (Dashboard → Test mode)	sk_live_... (Dashboard → Live mode)
STRIPE_WEBHOOK_SECRET	Sí	whsec_... (Stripe CLI)	whsec_... (Dashboard → Webhooks)
PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID	Sí	price_test_monthly	price_live_...
PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID	Sí	price_test_annual	price_live_...
PAYMENTS_CREDITS_10_PLAN_ID	No	price_test_credits	price_live_...

Cómo obtener el STRIPE_WEBHOOK_SECRET en desarrollo:

stripe listen --forward-to localhost:3001/payments-webhook
# Imprime: Your webhook signing secret is whsec_...

Cómo obtener el STRIPE_WEBHOOK_SECRET en producción:

1. Stripe Dashboard → Developers → Webhooks
2. Crear endpoint: https://tu-app.fly.dev/payments-webhook
3. Copiar el Signing Secret

---

Pagos — Lemon Squeezy (alternativa a Stripe)

Variable	Obligatoria	Notas
LEMONSQUEEZY_API_KEY	Solo si usas Lemon Squeezy	Desde app.lemonsqueezy.com
LEMONSQUEEZY_STORE_ID	Solo si usas Lemon Squeezy	ID de tu store
LEMONSQUEEZY_WEBHOOK_SECRET	Solo si usas Lemon Squeezy	Definido al crear webhook

TalentBricksAI usa Stripe como procesador principal. Ver docs de Open SaaS para Lemon Squeezy.

---

Pagos — Polar (alternativa a Stripe)

Variable	Obligatoria	Notas
POLAR_ORGANIZATION_ACCESS_TOKEN	Solo si usas Polar	Desde dashboard de Polar
POLAR_WEBHOOK_SECRET	Solo si usas Polar	Definido al crear webhook
POLAR_SANDBOX_MODE	Solo si usas Polar	true en dev, false en producción

---

Autenticación Social

Variable	Obligatoria	Notas
GOOGLE_CLIENT_ID	Solo si usas Google OAuth	Desde Google Cloud Console
GOOGLE_CLIENT_SECRET	Solo si usas Google OAuth	Desde Google Cloud Console
GITHUB_CLIENT_ID	Solo si usas GitHub OAuth	Desde GitHub Developer Settings
GITHUB_CLIENT_SECRET	Solo si usas GitHub OAuth	Desde GitHub Developer Settings

Setup de Google OAuth: Ver Wasp docs — Google Auth

---

Email

Variable	Obligatoria	Dev	Producción
SENDGRID_API_KEY	En producción	No necesario (Dummy provider)	SG.... (obligatorio)

En desarrollo, los emails se imprimen en la consola del servidor — no se envían realmente.

Obtener API Key de SendGrid: app.sendgrid.com/settings/api_keys

Para configuración completa, ver Email y SendGrid.

---

Videos — Almacenamiento en la Nube

La variable STORAGE_PROVIDER controla qué proveedor usa la app (aws por defecto).

Variable	Obligatoria	Dev	Producción
STORAGE_PROVIDER	No (default: aws)	No necesario	aws o azure

Opción A: AWS S3 + CloudFront

Variable	Obligatoria	Dev	Producción
AWS_S3_IAM_ACCESS_KEY	Solo en producción	No necesario (YouTube en dev)	AKIA...
AWS_S3_IAM_SECRET_KEY	Solo en producción	No necesario	Secret del usuario IAM
AWS_S3_FILES_BUCKET	Solo en producción	No necesario	Nombre exacto del bucket
AWS_S3_REGION	Solo en producción	No necesario	Ej: us-east-1
CLOUDFRONT_DOMAIN	Solo en producción	No necesario	Ej: d1234abc.cloudfront.net
CLOUDFRONT_KEY_PAIR_ID	Solo en producción	No necesario	Key ID de CloudFront
CLOUDFRONT_PRIVATE_KEY	Solo en producción	No necesario	Contenido del .pem en una línea

Formato del CLOUDFRONT_PRIVATE_KEY (en una línea):

CLOUDFRONT_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIE...\n-----END RSA PRIVATE KEY-----"

Opción B: Azure Blob Storage

Variable	Obligatoria	Dev	Producción
AZURE_STORAGE_ACCOUNT_NAME	Solo en producción	No necesario	Nombre de la Storage Account
AZURE_STORAGE_ACCOUNT_KEY	Solo en producción	No necesario	Key de acceso (base64, ~88 chars)
AZURE_STORAGE_CONTAINER_NAME	Solo en producción	No necesario	Nombre del container (ej: videos)

---

Admin

Variable	Obligatoria	Dev	Producción
ADMIN_EMAILS	Sí	Tu email de prueba	Emails de todos los admins

ADMIN_EMAILS=admin@empresa.com,otro-admin@empresa.com

---

Redis (opcional)

Variable	Obligatoria	Dev	Producción
REDIS_URL	No	No necesario	redis:// o rediss:// (TLS)

Sin esta variable, el rate limiting usa memoria local — correcto para una sola instancia. Configúrala si escalas a múltiples réplicas del servidor.

REDIS_URL=redis://localhost:6379                       # Local / Railway
REDIS_URL=rediss://:password@host.upstash.io:6380     # Upstash (TLS)

Ver guía completa: Redis para Rate Limiting

---

OpenAI (opcional)

Variable	Obligatoria	Notas
OPENAI_API_KEY	No (solo si usas features de IA)	Desde platform.openai.com

---

Analytics (opcional)

Variable	Obligatoria	Notas
PLAUSIBLE_API_KEY	No	Desde tu cuenta de Plausible
PLAUSIBLE_SITE_ID	No	Ej: talentbricks.ai
PLAUSIBLE_BASE_URL	No	Default: https://plausible.io/api
GOOGLE_ANALYTICS_CLIENT_EMAIL	No	Service account de Google Cloud
GOOGLE_ANALYTICS_PRIVATE_KEY	No	Private key en base64
GOOGLE_ANALYTICS_PROPERTY_ID	No	ID de la propiedad GA4

---

URL del Cliente

Variable	Obligatoria	Dev	Producción
CLIENT_URL	En producción	Auto (Wasp configura localhost)	https://talentbricks.ai

---

Variables del Cliente (.env.client)

Las variables del cliente deben comenzar con REACT_APP_.

Variable	Obligatoria	Notas
REACT_APP_GOOGLE_ANALYTICS_ID	No	Ej: G-XXXXXXXXXX

---

Archivos de Entorno

Desarrollo

app/
├── .env.server          ← Variables del servidor (no subir a Git)
├── .env.server.example  ← Template con todas las variables
├── .env.client          ← Variables del cliente (no subir a Git)
└── .env.client.example  ← Template con todas las variables

Los archivos .env.server y .env.client están en .gitignore. Nunca subir valores reales a Git.

Producción (Fly.io)

# Configurar una variable
wasp deploy fly cmd --context server secrets set VARIABLE=valor

# Ver variables configuradas (solo nombres, no valores)
flyctl secrets list -a talentbricksai

# Verificar que una variable está configurada (en consola del servidor)
flyctl ssh console -a talentbricksai -C "env | grep NOMBRE_VARIABLE"

---

Validación en Startup

TalentBricksAI incluye validación automática de variables de entorno al iniciar el servidor. Esto previene despliegues con configuración incompleta.

Categorías de Variables

• REQUIRED: Obligatorias siempre en producción (ej: DATABASE_URL, STRIPE_API_KEY)
• CONDITIONAL: Obligatorias solo si una feature está habilitada (ej: AWS S3 para videos)
• OPTIONAL: Opcionales, con degradación graceful (ej: analytics, OpenAI)

Mensajes de Error

Si falta una variable REQUIRED, el servidor no iniciará y mostrará un error claro:

🚨 ENVIRONMENT VALIDATION FAILED

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 REQUIRED Variables Missing (3)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

❌ STRIPE_API_KEY
   Stripe API key for payment processing
   Get it: https://dashboard.stripe.com/apikeys

❌ SENDGRID_API_KEY
   SendGrid API key for email delivery
   Get it: https://app.sendgrid.com/settings/api_keys

❌ JWT_SECRET
   Secret for signing JWT tokens
   Get it: Run: openssl rand -base64 32

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📖 Complete reference: /operaciones/variables-entorno
🔧 Deployment checklist: /operaciones/checklist-produccion

Variables CONDITIONAL y OPTIONAL generarán advertencias (warnings) pero no detendrán el servidor.

Implementación

La validación está en app/src/server/envValidation.ts y se ejecuta automáticamente al importar app/src/server/utils.ts.

Ver también:

• Checklist de Producción - Lista completa para despliegue
• Migración de Variables - Rotar secrets y migrar plataformas

---

Checklist de Variables para Producción

□ DATABASE_URL (Neon, con ?sslmode=require)
□ JWT_SECRET (openssl rand -base64 32)
□ STRIPE_API_KEY (sk_live_*)
□ STRIPE_WEBHOOK_SECRET (del webhook de producción)
□ PAYMENTS_MONTHLY_SUBSCRIPTION_PLAN_ID (price_live_*)
□ PAYMENTS_ANNUAL_SUBSCRIPTION_PLAN_ID (price_live_*)
□ ADMIN_EMAILS (emails reales de admins)
□ SENDGRID_API_KEY (obligatorio para email)
□ CLIENT_URL (https://talentbricks.ai)
□ AWS_S3_IAM_ACCESS_KEY (para videos)
□ AWS_S3_IAM_SECRET_KEY (para videos)
□ AWS_S3_FILES_BUCKET (para videos)
□ AWS_S3_REGION (para videos)
□ CLOUDFRONT_DOMAIN (para videos)
□ CLOUDFRONT_KEY_PAIR_ID (para URLs firmadas)
□ CLOUDFRONT_PRIVATE_KEY (para URLs firmadas)

Opcionales según features habilitadas:

□ GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET (si usas Google OAuth)
□ GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET (si usas GitHub OAuth)
□ OPENAI_API_KEY (si usas features de IA)
□ PLAUSIBLE_API_KEY / PLAUSIBLE_SITE_ID (si usas Plausible Analytics)
□ REACT_APP_GOOGLE_ANALYTICS_ID (si usas Google Analytics)
□ REDIS_URL (si tienes múltiples réplicas del servidor)