Operations
Referencia de variables de entorno
Referencia completa de variables de entorno de QuoteNode para produccion, desarrollo, Docker Compose, backup workers y tooling frontend.
Referencia de variables de entorno
Esta pagina consolida las variables de entorno que el proyecto QuoteNode usa actualmente.
La fuente principal de verdad sigue estando en las plantillas del repositorio de aplicacion:
infra/.env.prod.exampleinfra/.env.dev.exampleinfra/.env.dev-sidinfra/docker-compose.*.yml
Usa esta pagina como catalogo orientado a operacion. Para una puesta en marcha minima, consulta la Installation Guide. Para topologia de despliegue, consulta Deployment Options.
Como leer esta referencia
- Prod significa que la variable pertenece a un archivo
.envde produccion. - Dev significa stacks locales de desarrollo o demo.
- Compose significa variables de cableado del host Docker Compose, no necesariamente de la aplicacion.
- Un default vacio suele significar “define este valor explicitamente si necesitas la funcionalidad”.
Variables de Compose y pila local
Estas variables modelan el entorno local Docker Compose y el proxy del frontend en desarrollo.
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
COMPOSE_PROJECT_NAME |
Dev / Compose | Evita colisiones de nombres de contenedor entre varias pilas locales. | quotenode-dev, quotenode-dev-sid |
POSTGRES_PORT |
Dev / Compose | Puerto del host asignado a PostgreSQL. | 5433, 5434 |
PG_JIT |
Dev / Compose | Compilación JIT de PostgreSQL. Desactivada por defecto — rara vez ayuda con esta carga OLTP. Pon on para activarla. |
off |
MAILPIT_PORT |
Dev / Compose | Puerto del host para la UI de Mailpit. | 8025, 8026 |
BACKEND_PORT |
Dev / Compose | Puerto del host para la API backend. | 8091, 8092 |
FRONTEND_PORT |
Dev / Compose | Puerto del host para el frontend. | 5174, 5175 |
VITE_PUBLIC_API_BASE |
Dev / Frontend | URL base visible por el navegador para la API en pilas locales. | http://localhost:8091, http://localhost:8092 |
APP_VERSION |
Prod / Dev / Compose | Tag de imagen Docker seleccionado por Compose. | latest, 1.0.0 |
PROXY_MODE |
Prod / Dev / Compose | Decide si Caddy corre dentro de la pila (internal) o detras de un proxy externo (external). |
internal, external |
DOMAIN |
Prod / Compose | Dominio publico usado por Caddy y URLs publicas cuando el modo proxy interno esta activo. | quotenode.example.com |
SECURITY_TRUSTED_PROXIES |
Prod / Dev / Compose | Normalmente vacío — la IP del cliente se detecta automáticamente tras proxies internos (rangos privados/loopback) y CDNs como Cloudflare (vía CF-Connecting-IP). Las cabeceras de reenvío de un par directo (no interno) se ignoran. Defínelo solo para un proxy inusual cuyo par de transporte sea una dirección pública. |
vacío, 203.0.113.5/32 |
Base de datos y runtime principal
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
DB_URL |
Prod / Dev | Cadena JDBC de PostgreSQL. | jdbc:postgresql://postgres:5432/quotenode |
DB_USERNAME |
Prod / Dev | Usuario de base de datos. | quotenode, app |
DB_PASSWORD |
Prod / Dev | Contrasena de base de datos. | 32+ caracteres aleatorios en prod |
DB_NAME |
Prod / Dev / Compose | Nombre de la base usado por app y Compose. | quotenode, app |
DB_AUTO_MIGRATE |
Prod / Dev | Migración automática de versión mayor de PostgreSQL al iniciar (usada por stack-up.sh). Desactivada por defecto; si es true, un volumen de datos más antiguo se respalda y migra antes de arrancar la pila. |
false |
SPRING_PROFILES_ACTIVE |
Prod / Dev | Perfil Spring activo. | prod, dev |
CORS_ALLOWED_ORIGINS |
Prod / Dev | Origenes de navegador permitidos para la API. Evita * en produccion. |
https://yourdomain.com |
LOG_LEVEL |
Prod / Dev | Nivel base de logs de la aplicacion. | ERROR, INFO, DEBUG |
Rotacion de logs Docker y diagnostico de soporte
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
DOCKER_LOG_MAX_SIZE |
Prod / Compose | Tamano maximo de un fichero de log antes de rotarlo. | 10m |
DOCKER_LOG_MAX_FILE |
Prod / Compose | Numero de ficheros rotados que se conservan. | 5 |
SUPPORT_LOGS_BUFFER_SIZE |
Prod | Tamano del buffer de vista previa de logs en soporte. | 4000 |
SUPPORT_LOGS_PREVIEW_RATE_LIMIT_PER_MINUTE |
Prod | Rate limit para peticiones de preview de logs. | 30 |
SUPPORT_LOGS_LOG_LEVEL_DEFAULT_TTL_MINUTES |
Prod | Tiempo de auto-reversion para cambios temporales de nivel de log. | 15 |
SUPPORT_LOGS_LOG_LEVEL_MAX_TTL_MINUTES |
Prod | Ventana maxima permitida para escalado temporal de logs. | 30 |
SUPPORT_LOGS_LOG_LEVEL_ALLOWED_SCOPES |
Prod | Paquetes a los que se permite escalado temporal de logging. | dev.quotenode,... |
Seguridad de autenticacion y sesion
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
DB_ENCRYPTION_KEY |
Prod / Dev | Clave principal de cifrado de capa aplicacion para datos sensibles. | 64 caracteres hex en prod |
TIMING_TOKEN_SECRET |
Prod / Dev | Secreto HMAC para proteccion antibt basada en timing. | 32+ caracteres aleatorios |
PUBLIC_LINK_PASSWORD_SESSION_SECRET |
Prod / Dev | Secreto de sesion para enlaces publicos protegidos. | 32+ caracteres aleatorios |
AUTH_PASSWORD_MIN_LENGTH |
Prod / Dev | Longitud minima de contrasena. | 12 en prod, 8 en dev |
AUTH_PASSWORD_COMPLEXITY_LEVEL |
Prod / Dev | Nivel de complejidad exigido por la politica de contrasena. | 2 en prod, 1 en dev |
AUTH_SESSION_IDLE_TIMEOUT_MIN |
Prod / Dev | Timeout de inactividad de sesion. | 30, 480 |
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H |
Prod / Dev | Vida maxima absoluta de sesion. | 12, 24 |
SECURITY_MAX_FAILED_LOGINS_SOFT |
Prod / Dev | Umbral de intentos fallidos para advertencia suave. | 5, 10 |
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK |
Prod / Dev | Umbral de intentos fallidos para bloqueo temporal. | 10, 20 |
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK |
Prod / Dev | Umbral de intentos fallidos para bloqueo duro. | 20, 50 |
SECURITY_TEMP_LOCK_MINUTES |
Prod / Dev | Duracion del bloqueo temporal. | 30, 5 |
FEATURE_2FA_ENABLED |
Prod / Dev | Interruptor general para 2FA. | true, false |
SECURITY_REQUIRE_2FA_ROLES |
Prod / Dev | Roles obligados a enrolarse en 2FA. | ADMIN |
SECURITY_BOT_DETECTION_ENABLED |
Prod / Dev | Activa la capa de deteccion de bots. | true, false |
SECURITY_BOT_SCORE_WARN_THRESHOLD |
Prod / Dev | Umbral de score para solo advertir. | 30 |
SECURITY_BOT_SCORE_BLOCK_THRESHOLD |
Prod / Dev | Umbral de score para bloquear. | 70 |
SECURITY_IP_WHITELIST |
Prod / Dev | Lista blanca de IP impuesta por el operador (IP/CIDR literales separados por comas). Cuando se activa, la lista blanca protege toda la superficie de administración — inicio de sesión, el desafío 2FA y cada ruta de administración autenticada — dejando accesibles solo los endpoints de salud/infraestructura y los públicos para clientes. Cuando se establece, prevalece sobre la lista blanca del tenant en la aplicación y es de solo lectura en la interfaz; una lista del operador se aplica al arrancar sin auto-reversión, así que confirma que tu propia dirección está incluida. Vacío = se aplica el ajuste del tenant (si lo hay). Resuelve clientes mediante SECURITY_TRUSTED_PROXIES. |
vacío, 203.0.113.10,198.51.100.0/24 |
SECURITY_IP_WHITELIST_FORCE_DISABLE |
Runtime override | Anulación operativa de emergencia que desactiva la aplicación de la whitelist IP persistida (se comprueba antes de cualquier análisis de la lista, por lo que también recupera de una lista almacenada inválida — y, como la whitelist ahora protege el inicio de sesión, restaura la capacidad de acceder). Requiere reinicio; solo ENV, nunca desde la interfaz. Desactiva únicamente la whitelist IP — no GeoIP, detección de bots ni rate limiting. | false |
SECURITY_IP_WHITELIST_CONFIRMATION_WINDOW_SECONDS |
Prod / Dev | Cuánto tiempo una activación/restricción de la whitelist en la aplicación queda pendiente de reconfirmación antes de revertirse automáticamente a la lista anterior (seguridad ante bloqueos). La sesión que edita confirma automáticamente cuando su dirección actual está incluida. | 120 |
CRM, archivos, importaciones y media de producto
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
CRM_DEDUP_NAME_SIMILARITY_THRESHOLD |
Prod / Dev | Umbral pg_trgm para advertencias de empresas duplicadas. |
0.8 |
CRM_DEDUP_EMAIL_DOMAIN_WARN |
Prod / Dev | Advierte cuando el dominio del email coincide con registros existentes. | true |
CRM_ATTACHMENT_MAX_SIZE_MB |
Prod / Dev | Tamano maximo de adjuntos CRM. | 25, 10 |
CRM_ATTACHMENT_ALLOWED_TYPES |
Prod / Dev | Extensiones permitidas para adjuntos CRM. | pdf,doc,docx,... |
CSV_IMPORT_MAX_ROWS |
Prod / Dev | Limite de filas en importaciones CSV. | 5000 |
STORAGE_PATH |
Prod / Dev | Directorio raiz para archivos subidos. | /data/uploads, ./data/uploads |
PIM_MEDIA_MAX_SIZE_MB |
Prod / Dev | Tamano maximo de una imagen de producto. | 5, 10 |
PIM_MEDIA_MAX_PER_PRODUCT |
Prod / Dev | Numero maximo de recursos multimedia por producto. | 5, 10 |
PIM_MEDIA_THUMBNAIL_WIDTH |
Prod / Dev | Ancho de miniatura usado en procesamiento de imagen. | 300 |
PIM_MEDIA_ALLOWED_TYPES |
Prod / Dev | Extensiones permitidas para media de producto. | jpg,jpeg,png,webp,svg |
IMPORT_ZIP_MAX_SIZE_MB |
Prod / Dev | Tamano maximo de ZIP para importacion masiva de imagenes. | 100 |
IMPORT_ZIP_MAX_IMAGES |
Prod / Dev | Numero maximo de imagenes dentro del ZIP. | 1000 |
IMPORT_IMAGE_MAX_SIZE_MB |
Prod / Dev | Tamano maximo de cada imagen importada. | 5 |
IMPORT_IMAGE_FUZZY_THRESHOLD |
Prod / Dev | Umbral para emparejamiento difuso entre nombre de fichero y producto. | 0.82 |
Shipping, FX y valores por defecto de ofertas
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR |
Prod / Dev | Divisor de peso volumetrico usado por los calculos de envio. | 4000 |
SHIPPING_OVERRIDE_REQUIRES_REASON |
Prod / Dev | Exige justificacion cuando se sobrescribe el coste de envio. | true |
FX_PROVIDER |
Prod / Dev | Fuente del tipo de cambio. | NBP, MOCK, ECB, CUSTOM |
FX_PROVIDER_URL |
Prod / Dev | URL de proveedor custom de FX. | vacio salvo con CUSTOM |
FX_REFRESH_INTERVAL_MIN |
Prod / Dev | Cadencia de refresco automatico de FX. | 60, 0 |
FX_DEFAULT_MARGIN_PERCENT |
Prod / Dev | Margen porcentual aplicado sobre la cotizacion del proveedor. | 0 |
FX_DEVIATION_WARN_PERCENT |
Prod / Dev | Umbral de advertencia para ajustes FX manuales. | 3 |
FX_DEVIATION_BLOCK_PERCENT |
Prod / Dev | Umbral de bloqueo para ajustes FX manuales. | 8 |
OFFER_NUMBER_PREFIX |
Prod / Dev | Prefijo usado al numerar ofertas. | OF |
Email, enlaces publicos y notificaciones
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
SMTP_HOST |
Prod / Dev | Host SMTP usado para envio de ofertas y notificaciones. | hostname del proveedor, localhost |
SMTP_PORT |
Prod / Dev | Puerto SMTP. | 587, 1025, 1026 |
SMTP_USERNAME |
Prod / Dev | Usuario SMTP. | cuenta del proveedor |
SMTP_PASSWORD |
Prod / Dev | Contrasena SMTP. | secreto del proveedor |
SMTP_AUTH |
Prod / Dev | Activa autenticacion SMTP. | true, false |
SMTP_STARTTLS |
Prod / Dev | Activa negociacion STARTTLS. | true, false |
PUBLIC_LINK_TOKEN_BYTES |
Prod / Dev | Entropia usada para generar tokens de enlace publico. | 32 |
PUBLIC_LINK_DEFAULT_EXPIRY_DAYS |
Prod / Dev | Ventana de validez por defecto de los enlaces publicos. | 0 sin expiracion |
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR |
Prod / Dev | Limite horario para abrir endpoints publicos de oferta. | 60, 999 |
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR |
Prod / Dev | Limite horario para acciones publicas como aceptar o rechazar. | 5, 999 |
TRACKING_IP_ANONYMIZE |
Prod / Dev | Activa el anonimizado de IP en datos de tracking. | false |
TRACKING_IP_ANONYMIZE_AFTER_DAYS |
Prod / Dev | Retardo antes de anonimizar IP de tracking. | 0 |
TRACKING_RETENTION_DAYS |
Prod / Dev | Ventana de retencion de datos de tracking de enlaces publicos. | 365 |
CLIENT_CONFIRM_EMAIL_ENABLED |
Prod / Dev | Envia un correo de confirmacion al cliente tras aceptar. | false |
NOTIFICATIONS_ENABLED |
Prod / Dev | Activa el subsistema de notificaciones. | true |
NOTIFICATIONS_EMAIL_ENABLED |
Prod / Dev | Activa la entrega por email de notificaciones. | true, false |
NOTIFICATIONS_PUBLIC_PREFERENCES_URL |
Prod | URL publica para gestion de preferencias de notificaciones. | https://yourdomain.com/notifications/preferences |
NOTIFICATIONS_PREFERENCE_TOKEN_TTL_DAYS |
Prod | Validez de los enlaces de preferencias de notificacion. | 30 |
NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS |
Prod / Dev | Dias antes de expiracion en los que se envian recordatorios. | 7,2 |
NOTIFICATIONS_LICENSE_EXPIRY_WARN_DAYS |
Prod / Dev | Dias antes de expirar la licencia en los que se avisa. | 30,14,7,1 |
REMINDERS_JOB_INTERVAL_MINUTES |
Prod / Dev | Cadencia de polling del job de recordatorios. | 5 |
Generacion de PDF
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
PDF_ENABLED |
Prod / Dev | Activa la generacion de PDF. | true, false |
PDF_GOTENBERG_URL |
Prod / Dev | URL interna del servicio Gotenberg. | http://gotenberg:3000 |
PDF_SYNC_TIMEOUT_MS |
Prod / Dev | Timeout para peticiones PDF sincronas. | 10000, 5000 |
PDF_SYNC_MAX_ITEMS |
Prod / Dev | Maximo de lineas de oferta gestionadas en modo sincrono. | 50 |
PDF_STORAGE_PATH |
Prod / Dev | Ruta del filesystem donde se guardan PDFs generados. | /data/pdfs, ./data/pdfs |
PDF_RETENTION_DAYS |
Prod / Dev | Retencion de PDFs generados. | 365 |
PDF_RETRY_BACKOFF_SECONDS |
Prod / Dev | Plan de reintentos para jobs PDF asincronos. | 30,120,600 |
PDF_WORKER_CONCURRENCY |
Prod / Dev | Concurrencia de workers PDF. | 2 |
PDF_WORKER_POLL_INTERVAL_MS |
Prod / Dev | Intervalo de polling para jobs PDF. | 2000 |
Licencias, reportes y mantenimiento
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
LICENSE_SKIP_SIGNATURE_CHECK |
Prod / Dev | Salta la validacion de firma de licencia. Nunca lo actives en produccion. | false, true |
LICENSE_EXPIRY_CHECK_INTERVAL_H |
Prod / Dev | Cadencia de comprobacion de expiracion de licencia. | 24 |
REPORTS_DEFAULT_PERIOD_DAYS |
Prod / Dev | Periodo por defecto en reportes. | 30 |
REPORTS_EXPORT_MAX_ROWS |
Prod / Dev | Limite de filas al exportar reportes. | 10000 |
Backups, GeoIP y operaciones de privacidad
| Variable | Ambito | Proposito | Valor tipico |
|---|---|---|---|
BACKUP_ENABLED |
Prod / Dev | Activa backups programados. | true, false |
BACKUP_CRON |
Prod / Dev | Expresion cron para backups automaticos. | 0 0 2 * * * |
BACKUP_RETENTION_DAILY |
Prod / Dev | Numero de backups diarios a conservar. | 7 |
BACKUP_RETENTION_WEEKLY |
Prod / Dev | Numero de backups semanales a conservar. | 4 |
BACKUP_RETENTION_MONTHLY |
Prod / Dev | Numero de backups mensuales a conservar. | 12 |
BACKUP_LOCAL_DIR |
Runtime / Compose | Directorio local usado por scripts y workers de backup. | /app/data/backups |
BACKUP_ARCHIVE_ENCRYPTION_MODE |
Prod / Dev | Cifrado de archivo: AGE_RECIPIENT (recomendado) o NONE. |
AGE_RECIPIENT |
BACKUP_AGE_RECIPIENT |
Prod / Dev | Destinatario público age (age1...) para archivos cifrados. |
age1... |
BACKUP_DATABASE_PAYLOAD_MODE |
Prod / Dev | Modo de base de datos: APP_ENCRYPTED (predeterminado) o PII_DECRYPTED. |
APP_ENCRYPTED |
JOBS_MODE |
Prod / Dev / Compose | Qué trabajos programados ejecuta el planificador de la JVM: all (web + backups en un solo contenedor), web (solo web — combínalo con un worker backup-only), backup-only (worker de backup dedicado). |
all |
BACKUP_RUNTIME_PROFILE |
Prod / Dev | Etiqueta de perfil de ejecución registrada en los logs/manifiestos de backup: WORKER, WEB_MAINTENANCE, ONE_SHOT, OFFLINE_MAINTENANCE. Combina WEB_MAINTENANCE con JOBS_MODE=all (sin worker separado); combina WORKER con JOBS_MODE=web + un worker backup-only. |
WORKER |
BACKUP_RCLONE_REMOTE |
Prod / Dev | Destino rclone para offsite backup. | s3:bucket/path |
GEOIP_ENABLED |
Prod / Dev | Solo interruptor de aplicación por país (también interruptor de emergencia). La base se carga y actualiza de forma independiente — ver GEOIP_AUTO_UPDATE. |
false |
GEOIP_DB_PATH |
Prod / Dev | Ruta a la base de datos GeoIP (se descarga automáticamente al arrancar; DB-IP sin clave por defecto, MaxMind vía MAXMIND_*). |
/app/data/geoip/... |
SECURITY_GEOIP_ALLOWED_COUNTRIES |
Prod / Dev | Allowlist ISO de paises para validaciones GeoIP. | vacio o PL,DE,CZ |
MAXMIND_ACCOUNT_ID |
Prod | Cuenta MaxMind para descargar GeoLite. | account ID |
MAXMIND_LICENSE_KEY |
Prod | Clave MaxMind. | secreto |
GEOIP_EDITION_ID |
Prod | Edicion MaxMind. | GeoLite2-Country |
GDPR_ANONYMIZE_AUTO_AFTER_DAYS |
Prod / Dev | Horizonte de anonimizado automatico para workflows de privacidad. | 0 |
Guia practica
- Empieza desde la plantilla de produccion en despliegues reales y desde la plantilla de desarrollo para trabajo local.
- Trata
DB_ENCRYPTION_KEY,TIMING_TOKEN_SECRET,PUBLIC_LINK_PASSWORD_SESSION_SECRETy las credenciales SMTP como secretos que deben respaldarse de forma segura. - Mantén los puertos solo-Compose y las variables frontend fuera del
.envde produccion salvo que tu modelo de despliegue los necesite expresamente. - Si solo necesitas el setup minimo viable, la Installation Guide es intencionadamente mas corta que esta referencia.
Recomendaciones operativas
Esta pagina es larga porque separa variables que a menudo terminan mezcladas en despliegues reales. Conviene leerla por bloques:
- si estas desplegando por primera vez, empieza por database, seguridad y correo
- si estas afinando operacion, revisa logs, backups y PDF
- si estas depurando incidentes, compara primero el
.envreal con las plantillas del repositorio - si trabajas con varios stacks locales, valida especialmente puertos,
COMPOSE_PROJECT_NAMEyVITE_PUBLIC_API_BASE
No todas las variables deben usarse en todos los entornos. La referencia existe para explicar que soporta el sistema y en que capa vive cada ajuste.