Variables de Entorno

Guía completa de referencia de todas las variables de entorno utilizadas en Floutic.

Backend

Variable	Obligatoria	Descripción
DATABASE_URL	✅	Cadena completa de conexión (postgresql+asyncpg). Alternativamente definir POSTGRES_* individualmente.
POSTGRES_HOST / POSTGRES_PORT / POSTGRES_DB / POSTGRES_USER / POSTGRES_PASSWORD	⚠️	Solo necesarios si no se usa DATABASE_URL.
REDIS_URL	✅	URL de Redis usada para sesiones, rate limiting, cache.
JWT_SECRET	✅	Secreto para firmar JWT (mínimo 32 caracteres). Generar con openssl rand -hex 64.
JWT_ALGORITHM	⚠️	Algoritmo (HS256 por defecto).
JWT_ACCESS_EXPIRE_MINUTES	⚠️	Duración del token de acceso.
JWT_REFRESH_EXPIRE_DAYS	⚠️	Duración del refresh token.
STRIPE_SECRET_KEY	✅	Clave secreta del backend de Stripe (sk_live_…).
STRIPE_WEBHOOK_SECRET	✅	Secreto para verificar webhooks (whsec_…).
STRIPE_CONNECT_CLIENT_ID	⚠️	Necesario si se usa Stripe Connect Express.
STRIPE_CONNECT_RETURN_URL / STRIPE_CONNECT_REFRESH_URL	⚠️	URLs de onboarding para Stripe Connect.
STRIPE_CONNECT_ACCOUNT_COUNTRY	⚠️	País por defecto para cuentas Connect.
GHL_API_KEY	⚠️	API key de GoHighLevel (Private Integration token).
GHL_API_URL	⚠️	URL base de GHL (por defecto https://services.leadconnectorhq.com).
GHL_LOCATION_ID	⚠️	ID de la ubicación principal en GHL.
GHL_WEBHOOK_SECRET	⚠️	Secreto para validar webhooks entrantes desde GHL.
N8N_WEBHOOK_URL	⚠️	Endpoint n8n que orquesta automatizaciones.
N8N_API_KEY	⚠️	API key si se autentican llamadas contra n8n.
SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASSWORD	⚠️	Credenciales del servidor de correo.
EMAIL_FROM_NAME / EMAIL_FROM_ADDRESS	⚠️	Identidad del remitente en emails transaccionales.
FRONTEND_URL	✅	URL del frontend para construir enlaces y CORS.
CORS_ORIGINS	✅	Lista separada por comas con orígenes permitidos.
ENVIRONMENT	✅	development, staging o production.
LOG_LEVEL	⚠️	Nivel de log (INFO/DEBUG/WARN...).
DEBUG	⚠️	Activa trazas adicionales (habitualmente false en producción).
RATE_LIMIT_PER_MINUTE	⚠️	Límite de peticiones por minuto.
MAX_CONCURRENT_SESSIONS	⚠️	Sesiones simultáneas permitidas por usuario.
TERMS_VERSION	✅	Versión vigente de los Términos y Condiciones.
OPENOBSERVE_URL	⚠️	URL de OpenObserve para observabilidad.
OPENOBSERVE_USER	⚠️	Usuario de OpenObserve.
OPENOBSERVE_PASSWORD	⚠️	Contraseña de OpenObserve.

Notas backend:

• La configuración unificada aplica por defecto cabeceras CSP, Trusted Host, sesiones, rate limiting y blacklist de tokens
• Si despliegas con Docker Compose, los hostnames suelen coincidir con los nombres de servicio (postgres, redis)
• Stripe Connect requiere definir los RETURN_URL/REFRESH_URL públicos en el dashboard de Stripe

Frontend (Astro/Vite)

⚠️ Importante: Las variables con prefijos VITE_ o PUBLIC_ se embeben en el bundle. No coloques información sensible en ellas.

Variable	Obligatoria	Descripción
VITE_API_BASE_URL / VITE_API_URL	✅	URL del backend que consumen los clientes (REST).
PUBLIC_API_BASE_URL	⚠️	Variante pública utilizada en componentes Astro/Svelte.
VITE_STRIPE_PUBLISHABLE_KEY	✅	Clave pública (pk_live...) para inicializar Stripe.js.
VITE_STRIPE_DASHBOARD_URL_BASE	⚠️	URL base opcional para enlaces al dashboard de Stripe.
SITE / PUBLIC_SITE_URL	✅	URL canónica del frontend para generar rutas absolutas.
PUBLIC_WS_URL	⚠️	Endpoint WebSocket si se requiere personalizar.
PUBLIC_TERMS_VERSION	✅	Versión pública mostrada en los formularios. Debe estar sincronizada con TERMS_VERSION.
VITE_OPENOBSERVE_URL / PUBLIC_OPENOBSERVE_URL	⚠️	URL pública de OpenObserve accesible desde el navegador.
VITE_OPENOBSERVE_CLIENT_TOKEN / PUBLIC_OPENOBSERVE_CLIENT_TOKEN	⚠️	OBLIGATORIO para SDK oficial de OpenObserve RUM.
VITE_OPENOBSERVE_APPLICATION_ID / PUBLIC_OPENOBSERVE_APPLICATION_ID	⚠️	Identificador de la aplicación (opcional, por defecto: floutic-web).
VITE_OPENOBSERVE_SAMPLE_RATE / PUBLIC_OPENOBSERVE_SAMPLE_RATE	⚠️	Tasa de muestreo para eventos RUM (0.0 a 1.0, default: 1.0).

Notas frontend:

• Usa frontend/.env.production.example como plantilla
• La clave pública de Stripe debe sincronizarse con la usada en backend
• Si el frontend se sirve desde un dominio distinto al backend, asegúrate de que las URLs coincidan

Generación de Secretos

JWT Secret

openssl rand -hex 64

Webhook Secrets

python -c "import secrets; print(secrets.token_urlsafe(48))"

Matriz de Responsabilidad por Entorno

Variable	Desarrollo	Staging	Producción	Notas
DATABASE_URL	Opcional	...@postgres:5432/floutic_dev (contenedor propio)	✅	Staging tiene su propio PostgreSQL aislado
REDIS_URL	Opcional	redis://redis:6379/0 (contenedor propio)	✅	Staging tiene su propio Redis aislado
JWT_SECRET	Demo (auto)	✅ (DISTINTO al de producción)	✅	Rotar y documentar
STRIPE_SECRET_KEY	sk_test_*	sk_test_* (SIEMPRE test)	sk_live_*	Revisar dashboard tras cada despliegue
STRIPE_WEBHOOK_SECRET	Local (Stripe CLI)	✅	✅	Uno por entorno
GHL_API_KEY	Opcional	staging-placeholder	✅	Staging no interactúa con GHL real
FRONTEND_URL / VITE_API_BASE_URL	http://localhost	https://dev.floutic.com	✅	Debe coincidir con el reverse proxy
CORS_ORIGINS	http://localhost:*	https://dev.floutic.com	✅	Incluir dominios exactos
ENVIRONMENT	development	staging	production	Controla banderas de seguridad
TERMS_VERSION / PUBLIC_TERMS_VERSION	✅ (demo)	✅	✅	Deben actualizarse cuando los textos legales cambien

:::warning Aislamiento de staging Staging tiene sus propios contenedores de PostgreSQL y Redis, completamente independientes de producción. El JWT_SECRET de staging debe ser distinto al de producción para evitar fugas de sesión entre entornos. GHL y N8N usan valores staging-placeholder para evitar interacción con servicios reales. :::

Buenas Prácticas

• Mantén los secretos fuera del repositorio (Vault, AWS SSM, Doppler, etc.)
• Registra la fecha de creación y rotación de cada clave
• Automatiza la inyección mediante docker compose --env-file o gestores de secretos
• No exportar manualmente en shell scripts de producción

Más Información

• Despliegue con Docker
• Checklist de Deployment
• Configuración de Stripe
• Configuración de GoHighLevel