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.example
• infra/.env.dev.example
• infra/.env.dev-sid
• infra/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 .env de 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
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

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
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_FORCE_DISABLE	Runtime override	Override operativo de emergencia para desactivar la whitelist IP persistida.	false

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_GPG_RECIPIENT	Prod / Dev	Destinatario GPG para cifrado de backups.	fingerprint o email
BACKUP_RCLONE_REMOTE	Prod / Dev	Destino rclone para offsite backup.	s3:bucket/path
BACKUP_ENCRYPTION_ENABLED	Runtime override	Switch interno o de smoke-test para comportamiento de cifrado de backup.	false
GEOIP_ENABLED	Prod / Dev	Activa controles de acceso basados en GeoIP.	false
GEOIP_DB_PATH	Prod / Dev	Ruta a la base de datos GeoIP de 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_SECRET y las credenciales SMTP como secretos que deben respaldarse de forma segura.
• Mantén los puertos solo-Compose y las variables frontend fuera del .env de 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 .env real con las plantillas del repositorio
• si trabajas con varios stacks locales, valida especialmente puertos, COMPOSE_PROJECT_NAME y VITE_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.