Environment Variables Reference

This page consolidates the environment variables currently used by the QuoteNode project.

The main source of truth is the application repository templates:

• infra/.env.prod.example
• infra/.env.dev.example
• infra/.env.dev-sid
• infra/docker-compose.*.yml

Use this page as an operator-oriented catalog. For a minimal getting-started setup, see the Installation Guide. For deployment topology, see Deployment Options.

How to read this reference

• Prod means a variable belongs in a production .env file.
• Dev means local development or demo stacks.
• Compose means Docker Compose host-side wiring rather than the application itself.
• Empty defaults usually mean “set this explicitly when you need the feature”.

Compose and local stack variables

These variables shape the local Docker Compose environment and frontend dev proxy wiring.

Variable	Scope	Purpose	Typical value
COMPOSE_PROJECT_NAME	Dev / Compose	Prevents container-name collisions between multiple local stacks.	quotenode-dev, quotenode-dev-sid
POSTGRES_PORT	Dev / Compose	Host port mapped to PostgreSQL.	5433, 5434
MAILPIT_PORT	Dev / Compose	Host port for Mailpit UI.	8025, 8026
BACKEND_PORT	Dev / Compose	Host port for backend API.	8091, 8092
FRONTEND_PORT	Dev / Compose	Host port for frontend app.	5174, 5175
VITE_PUBLIC_API_BASE	Dev / Frontend	Browser-visible API base URL used by the Vite frontend in local stacks.	http://localhost:8091, http://localhost:8092
APP_VERSION	Prod / Dev / Compose	Docker image tag selected by Compose.	latest, v0.9.0-alpha, v1.0.0
APP_CHANNEL	Prod / Dev / Compose	Product release channel embedded into build metadata and UI labels.	alpha, stable
VITE_RELEASE_CHECK_ENABLED	Prod / Dev / Frontend	Enables the admin-only upstream release availability check.	true, false
VITE_RELEASE_MANIFEST_URL	Prod / Dev / Frontend	Public JSON manifest URL used for upstream release checks.	https://quotenode.dev/releases/latest.json
PROXY_MODE	Prod / Dev / Compose	Chooses whether Caddy runs inside the stack (internal) or an external reverse proxy is used (external).	internal, external
DOMAIN	Prod / Compose	Public domain used by Caddy and public URLs when internal proxy mode is enabled.	quotenode.example.com

Operator note: QuoteNode keeps runtime refresh checks (/app-version.json) separate from upstream release checks (https://quotenode.dev/releases/latest.json). The upstream notice is admin-only, never forces a reload, and can be disabled with VITE_RELEASE_CHECK_ENABLED=false.

Database and core runtime

Variable	Scope	Purpose	Typical value
DB_URL	Prod / Dev	JDBC connection string for PostgreSQL.	jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME	Prod / Dev	Database user.	quotenode, app
DB_PASSWORD	Prod / Dev	Database password.	random 32+ chars in prod
DB_NAME	Prod / Dev / Compose	Database name used by app and Compose.	quotenode, app
SPRING_PROFILES_ACTIVE	Prod / Dev	Activates the Spring profile.	prod, dev
CORS_ALLOWED_ORIGINS	Prod / Dev	Allowed browser origins for the API. Avoid * in production.	https://yourdomain.com
LOG_LEVEL	Prod / Dev	Baseline application log verbosity.	ERROR, INFO, DEBUG

Docker log rotation and support diagnostics

Variable	Scope	Purpose	Typical value
DOCKER_LOG_MAX_SIZE	Prod / Compose	Maximum size of a single container log file before rotation.	10m
DOCKER_LOG_MAX_FILE	Prod / Compose	Number of rotated container log files to retain.	5
SUPPORT_LOGS_BUFFER_SIZE	Prod	Size of the in-app support log preview buffer.	4000
SUPPORT_LOGS_PREVIEW_RATE_LIMIT_PER_MINUTE	Prod	Rate limit for support log preview requests.	30
SUPPORT_LOGS_LOG_LEVEL_DEFAULT_TTL_MINUTES	Prod	Auto-revert timeout for temporary log-level changes.	15
SUPPORT_LOGS_LOG_LEVEL_MAX_TTL_MINUTES	Prod	Maximum allowed temporary log-level escalation window.	30
SUPPORT_LOGS_LOG_LEVEL_ALLOWED_SCOPES	Prod	Package scopes that may be temporarily escalated for diagnostics.	dev.quotenode,...

Auth and session security

Variable	Scope	Purpose	Typical value
DB_ENCRYPTION_KEY	Prod / Dev	Main application-layer encryption key for sensitive data.	64 hex chars in prod
TIMING_TOKEN_SECRET	Prod / Dev	HMAC secret for timing-token based bot protection.	32+ random chars
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Prod / Dev	Session secret for password-protected public offer links.	32+ random chars
AUTH_PASSWORD_MIN_LENGTH	Prod / Dev	Minimum password length policy.	12 in prod, 8 in dev
AUTH_PASSWORD_COMPLEXITY_LEVEL	Prod / Dev	Password complexity tier enforced by auth policy.	2 in prod, 1 in dev
AUTH_SESSION_IDLE_TIMEOUT_MIN	Prod / Dev	Idle timeout for authenticated sessions.	30, 480
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H	Prod / Dev	Absolute maximum session lifetime.	12, 24
SECURITY_MAX_FAILED_LOGINS_SOFT	Prod / Dev	Failed login threshold for soft warnings.	5, 10
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK	Prod / Dev	Failed login threshold for temporary lockout.	10, 20
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK	Prod / Dev	Failed login threshold for hard lockout.	20, 50
SECURITY_TEMP_LOCK_MINUTES	Prod / Dev	Duration of temporary lockout.	30, 5
FEATURE_2FA_ENABLED	Prod / Dev	Master switch for two-factor authentication flows.	true, false
SECURITY_REQUIRE_2FA_ROLES	Prod / Dev	Roles that must enroll in 2FA.	ADMIN
SECURITY_BOT_DETECTION_ENABLED	Prod / Dev	Enables the bot-detection layer.	true, false
SECURITY_BOT_SCORE_WARN_THRESHOLD	Prod / Dev	Bot score threshold for warning-only action.	30
SECURITY_BOT_SCORE_BLOCK_THRESHOLD	Prod / Dev	Bot score threshold for blocking action.	70
SECURITY_IP_WHITELIST_FORCE_DISABLE	Runtime override	Emergency operator override that disables stored IP whitelist enforcement.	false

CRM, files, imports, and product media

Variable	Scope	Purpose	Typical value
CRM_DEDUP_NAME_SIMILARITY_THRESHOLD	Prod / Dev	pg_trgm similarity threshold for duplicate-company warnings.	0.8
CRM_DEDUP_EMAIL_DOMAIN_WARN	Prod / Dev	Warn when business email domains match existing records.	true
CRM_ATTACHMENT_MAX_SIZE_MB	Prod / Dev	Maximum CRM attachment size.	25, 10
CRM_ATTACHMENT_ALLOWED_TYPES	Prod / Dev	Allowed CRM attachment extensions.	pdf,doc,docx,...
CSV_IMPORT_MAX_ROWS	Prod / Dev	Row limit for CSV imports.	5000
STORAGE_PATH	Prod / Dev	Root directory for uploaded files.	/data/uploads, ./data/uploads
PIM_MEDIA_MAX_SIZE_MB	Prod / Dev	Maximum size for a single product image.	5, 10
PIM_MEDIA_MAX_PER_PRODUCT	Prod / Dev	Maximum media items attached to one product.	5, 10
PIM_MEDIA_THUMBNAIL_WIDTH	Prod / Dev	Thumbnail width used during image processing.	300
PIM_MEDIA_ALLOWED_TYPES	Prod / Dev	Allowed product media extensions.	jpg,jpeg,png,webp,svg
IMPORT_ZIP_MAX_SIZE_MB	Prod / Dev	Maximum ZIP size for batch image import.	100
IMPORT_ZIP_MAX_IMAGES	Prod / Dev	Maximum image count inside a ZIP import.	1000
IMPORT_IMAGE_MAX_SIZE_MB	Prod / Dev	Maximum size of one imported image inside ZIP batches.	5
IMPORT_IMAGE_FUZZY_THRESHOLD	Prod / Dev	Threshold for fuzzy filename-to-product matching.	0.82

Shipping, FX, and offer defaults

Variable	Scope	Purpose	Typical value
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR	Prod / Dev	Volumetric-weight divisor used by shipping calculations.	4000
SHIPPING_OVERRIDE_REQUIRES_REASON	Prod / Dev	Requires a justification when shipping cost is overridden manually.	true
FX_PROVIDER	Prod / Dev	FX rate source.	NBP, MOCK, ECB, CUSTOM
FX_PROVIDER_URL	Prod / Dev	Custom provider URL override.	empty unless CUSTOM
FX_REFRESH_INTERVAL_MIN	Prod / Dev	Automatic FX refresh cadence.	60, 0
FX_DEFAULT_MARGIN_PERCENT	Prod / Dev	Default percentage margin applied on top of provider rates.	0
FX_DEVIATION_WARN_PERCENT	Prod / Dev	Warn threshold for manually adjusted FX rates.	3
FX_DEVIATION_BLOCK_PERCENT	Prod / Dev	Block threshold for manually adjusted FX rates.	8
OFFER_NUMBER_PREFIX	Prod / Dev	Prefix used when numbering offers.	OF

Email, public links, and notifications

Variable	Scope	Purpose	Typical value
SMTP_HOST	Prod / Dev	SMTP hostname used for offer sending and notifications.	provider hostname, localhost
SMTP_PORT	Prod / Dev	SMTP port.	587, 1025, 1026
SMTP_USERNAME	Prod / Dev	SMTP auth username.	provider account
SMTP_PASSWORD	Prod / Dev	SMTP auth password.	provider secret
SMTP_AUTH	Prod / Dev	Enables SMTP authentication.	true, false
SMTP_STARTTLS	Prod / Dev	Enables STARTTLS negotiation.	true, false
PUBLIC_LINK_TOKEN_BYTES	Prod / Dev	Entropy used for generated public-link tokens.	32
PUBLIC_LINK_DEFAULT_EXPIRY_DAYS	Prod / Dev	Default validity window for public links.	0 for no expiry
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR	Prod / Dev	Hourly limit for opening public offer endpoints.	60, 999
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR	Prod / Dev	Hourly limit for public actions such as accept/reject.	5, 999
TRACKING_IP_ANONYMIZE	Prod / Dev	Enables IP anonymization for tracking data.	false
TRACKING_IP_ANONYMIZE_AFTER_DAYS	Prod / Dev	Delayed anonymization period for tracking IPs.	0
TRACKING_RETENTION_DAYS	Prod / Dev	Retention window for public-link tracking data.	365
CLIENT_CONFIRM_EMAIL_ENABLED	Prod / Dev	Sends a confirmation email to the client after acceptance.	false
NOTIFICATIONS_ENABLED	Prod / Dev	Enables the notifications subsystem.	true
NOTIFICATIONS_EMAIL_ENABLED	Prod / Dev	Enables email delivery for notifications.	true, false
NOTIFICATIONS_PUBLIC_PREFERENCES_URL	Prod	Public URL for notification preference management.	https://yourdomain.com/notifications/preferences
NOTIFICATIONS_PREFERENCE_TOKEN_TTL_DAYS	Prod	Token validity for notification-preference links.	30
NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS	Prod / Dev	Days-before-expiry reminder schedule for offers.	7,2
NOTIFICATIONS_LICENSE_EXPIRY_WARN_DAYS	Prod / Dev	Days-before-expiry reminder schedule for licenses.	30,14,7,1
REMINDERS_JOB_INTERVAL_MINUTES	Prod / Dev	Polling cadence for reminder jobs.	5

PDF generation

Variable	Scope	Purpose	Typical value
PDF_ENABLED	Prod / Dev	Enables PDF generation flows.	true, false
PDF_GOTENBERG_URL	Prod / Dev	Internal URL of the Gotenberg service.	http://gotenberg:3000
PDF_SYNC_TIMEOUT_MS	Prod / Dev	Timeout for synchronous PDF requests.	10000, 5000
PDF_SYNC_MAX_ITEMS	Prod / Dev	Maximum offer-item count still handled synchronously.	50
PDF_STORAGE_PATH	Prod / Dev	Filesystem path where generated PDFs are stored.	/data/pdfs, ./data/pdfs
PDF_RETENTION_DAYS	Prod / Dev	Retention period for generated PDFs.	365
PDF_RETRY_BACKOFF_SECONDS	Prod / Dev	Retry schedule for async PDF jobs.	30,120,600
PDF_WORKER_CONCURRENCY	Prod / Dev	Worker concurrency for PDF processing.	2
PDF_WORKER_POLL_INTERVAL_MS	Prod / Dev	Polling interval for PDF jobs.	2000

Licensing, reports, and maintenance

Variable	Scope	Purpose	Typical value
LICENSE_SKIP_SIGNATURE_CHECK	Prod / Dev	Bypasses license signature validation. Never enable in production.	false, true
LICENSE_EXPIRY_CHECK_INTERVAL_H	Prod / Dev	Reload cadence for license-expiry checks.	24
REPORTS_DEFAULT_PERIOD_DAYS	Prod / Dev	Default reporting date range.	30
REPORTS_EXPORT_MAX_ROWS	Prod / Dev	Row cap for report exports.	10000

Backups, GeoIP, and privacy operations

Variable	Scope	Purpose	Typical value
BACKUP_ENABLED	Prod / Dev	Enables scheduled backups.	true, false
BACKUP_CRON	Prod / Dev	Cron schedule for automated backups.	0 0 2 * * *
BACKUP_RETENTION_DAILY	Prod / Dev	Number of daily backups to retain.	7
BACKUP_RETENTION_WEEKLY	Prod / Dev	Number of weekly backups to retain.	4
BACKUP_RETENTION_MONTHLY	Prod / Dev	Number of monthly backups to retain.	12
BACKUP_LOCAL_DIR	Runtime / Compose	Local directory used by backup scripts and backup-worker containers.	/app/data/backups
BACKUP_GPG_RECIPIENT	Prod / Dev	GPG recipient for backup encryption.	fingerprint or email
BACKUP_RCLONE_REMOTE	Prod / Dev	rclone destination for offsite backups.	s3:bucket/path
BACKUP_ENCRYPTION_ENABLED	Runtime override	Internal or smoke-test switch for backup encryption behavior.	false
GEOIP_ENABLED	Prod / Dev	Enables GeoIP-based access controls.	false
GEOIP_DB_PATH	Prod / Dev	Path to the MaxMind GeoIP database.	/app/data/geoip/...
SECURITY_GEOIP_ALLOWED_COUNTRIES	Prod / Dev	ISO country allowlist for GeoIP checks.	empty or PL,DE,CZ
MAXMIND_ACCOUNT_ID	Prod	MaxMind account for GeoLite downloads.	account ID
MAXMIND_LICENSE_KEY	Prod	MaxMind license key.	secret
GEOIP_EDITION_ID	Prod	MaxMind edition identifier.	GeoLite2-Country
GDPR_ANONYMIZE_AUTO_AFTER_DAYS	Prod / Dev	Automatic anonymization horizon for privacy workflows.	0

Practical guidance

• Start from the production template for real deployments and from the development template for local work.
• Treat DB_ENCRYPTION_KEY, TIMING_TOKEN_SECRET, PUBLIC_LINK_PASSWORD_SESSION_SECRET, and SMTP credentials as secrets that must be backed up securely.
• Keep Compose-only ports and frontend variables out of production .env files unless your deployment model explicitly needs them.
• If you need only the smallest viable production setup, the Installation Guide is intentionally shorter than this reference.