Referencja zmiennych środowiskowych

Ta strona zbiera zmienne środowiskowe używane obecnie w projekcie QuoteNode.

Główne źródła prawdy w repozytorium aplikacji to:

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

Traktuj tę stronę jako katalog operatorski. Minimalną konfigurację startową znajdziesz w Instalacji, a topologię wdrożeń w Opcjach wdrożenia.

Jak czytać tę referencję

• Prod oznacza zmienne do pliku .env dla środowiska produkcyjnego.
• Dev oznacza lokalny development lub stack demonstracyjny.
• Compose oznacza host-side wiring Dockera, a nie sam backend.
• Puste wartości domyślne zwykle znaczą: “ustaw tylko wtedy, gdy naprawdę używasz tej funkcji”.

Zmienne Compose i lokalnego stacku

Te zmienne sterują lokalnym środowiskiem Docker Compose i konfiguracją proxy/API dla frontendu.

Zmienna	Zakres	Cel	Typowa wartość
COMPOSE_PROJECT_NAME	Dev / Compose	Chroni przed kolizją nazw kontenerów między wieloma stackami lokalnymi.	quotenode-dev, quotenode-dev-sid
POSTGRES_PORT	Dev / Compose	Port hosta mapowany do PostgreSQL.	5433, 5434
MAILPIT_PORT	Dev / Compose	Port hosta dla UI Mailpit.	8025, 8026
BACKEND_PORT	Dev / Compose	Port hosta dla backend API.	8091, 8092
FRONTEND_PORT	Dev / Compose	Port hosta dla frontendu.	5174, 5175
VITE_PUBLIC_API_BASE	Dev / Frontend	Widoczny w przeglądarce base URL API używany przez frontend Vite lokalnie.	http://localhost:8091, http://localhost:8092
APP_VERSION	Prod / Dev / Compose	Tag obrazu Dockera wybierany przez Compose.	latest, v0.9.0-alpha, v1.0.0
APP_CHANNEL	Prod / Dev / Compose	Kanał wydania produktu osadzany w build metadata i etykietach UI.	alpha, stable
VITE_RELEASE_CHECK_ENABLED	Prod / Dev / Frontend	Włącza operatorski check dostępności nowszego release w panelu admina.	true, false
VITE_RELEASE_MANIFEST_URL	Prod / Dev / Frontend	Publiczny URL manifestu JSON używanego do checku nowszych wydań.	https://quotenode.dev/releases/latest.json
PROXY_MODE	Prod / Dev / Compose	Określa, czy Caddy działa wewnątrz stacka (internal), czy używany jest zewnętrzny reverse proxy (external).	internal, external
DOMAIN	Prod / Compose	Publiczna domena używana przez Caddy i URL-e publiczne przy internal.	quotenode.example.com

Uwaga operatorska: QuoteNode rozdziela check runtime reloadu frontendu (/app-version.json) od checku nowszego upstream release (https://quotenode.dev/releases/latest.json). Powiadomienie o nowym wydaniu pojawia się tylko w uwierzytelnionym obszarze administracyjnym, nie wymusza natychmiastowego reloadu i można je wyłączyć przez VITE_RELEASE_CHECK_ENABLED=false.

Baza danych i podstawowy runtime

Zmienna	Zakres	Cel	Typowa wartość
DB_URL	Prod / Dev	JDBC connection string do PostgreSQL.	jdbc:postgresql://postgres:5432/quotenode
DB_USERNAME	Prod / Dev	Użytkownik bazy danych.	quotenode, app
DB_PASSWORD	Prod / Dev	Hasło bazy danych.	losowe 32+ znaków w prod
DB_NAME	Prod / Dev / Compose	Nazwa bazy używana przez aplikację i Compose.	quotenode, app
SPRING_PROFILES_ACTIVE	Prod / Dev	Aktywny profil Spring.	prod, dev
CORS_ALLOWED_ORIGINS	Prod / Dev	Dozwolone originy przeglądarkowe dla API. W prod unikaj *.	https://twojadomena.pl
LOG_LEVEL	Prod / Dev	Bazowy poziom logowania aplikacji.	ERROR, INFO, DEBUG

Rotacja logów Dockera i diagnostyka supportowa

Zmienna	Zakres	Cel	Typowa wartość
DOCKER_LOG_MAX_SIZE	Prod / Compose	Maksymalny rozmiar pojedynczego pliku logu kontenera przed rotacją.	10m
DOCKER_LOG_MAX_FILE	Prod / Compose	Liczba zachowywanych zrotowanych plików logów kontenera.	5
SUPPORT_LOGS_BUFFER_SIZE	Prod	Rozmiar bufora podglądu logów w panelu supportowym.	4000
SUPPORT_LOGS_PREVIEW_RATE_LIMIT_PER_MINUTE	Prod	Rate limit dla podglądu logów supportowych.	30
SUPPORT_LOGS_LOG_LEVEL_DEFAULT_TTL_MINUTES	Prod	Czas auto-revertu po tymczasowym podniesieniu poziomu logów.	15
SUPPORT_LOGS_LOG_LEVEL_MAX_TTL_MINUTES	Prod	Maksymalne okno czasowe dla tymczasowej eskalacji logowania.	30
SUPPORT_LOGS_LOG_LEVEL_ALLOWED_SCOPES	Prod	Zakresy pakietów, którym wolno tymczasowo podnieść poziom logów.	dev.quotenode,...

Uwierzytelnianie i bezpieczeństwo sesji

Zmienna	Zakres	Cel	Typowa wartość
DB_ENCRYPTION_KEY	Prod / Dev	Główny klucz szyfrowania danych w warstwie aplikacji.	64 znaki hex w prod
TIMING_TOKEN_SECRET	Prod / Dev	Sekret HMAC dla tokenów ochrony timing-based.	32+ losowe znaki
PUBLIC_LINK_PASSWORD_SESSION_SECRET	Prod / Dev	Sekret sesji dla chronionych hasłem linków publicznych.	32+ losowe znaki
AUTH_PASSWORD_MIN_LENGTH	Prod / Dev	Minimalna długość hasła.	12 w prod, 8 w dev
AUTH_PASSWORD_COMPLEXITY_LEVEL	Prod / Dev	Poziom złożoności hasła.	2 w prod, 1 w dev
AUTH_SESSION_IDLE_TIMEOUT_MIN	Prod / Dev	Timeout bezczynności sesji.	30, 480
SECURITY_SESSION_ABSOLUTE_TIMEOUT_H	Prod / Dev	Maksymalny czas życia sesji niezależnie od aktywności.	12, 24
SECURITY_MAX_FAILED_LOGINS_SOFT	Prod / Dev	Próg nieudanych logowań dla miękkiego ostrzeżenia.	5, 10
SECURITY_MAX_FAILED_LOGINS_TEMP_LOCK	Prod / Dev	Próg nieudanych logowań dla blokady czasowej.	10, 20
SECURITY_MAX_FAILED_LOGINS_HARD_LOCK	Prod / Dev	Próg nieudanych logowań dla twardej blokady.	20, 50
SECURITY_TEMP_LOCK_MINUTES	Prod / Dev	Czas trwania blokady czasowej.	30, 5
FEATURE_2FA_ENABLED	Prod / Dev	Globalny przełącznik dla 2FA.	true, false
SECURITY_REQUIRE_2FA_ROLES	Prod / Dev	Role, które muszą mieć włączone 2FA.	ADMIN
SECURITY_BOT_DETECTION_ENABLED	Prod / Dev	Włącza warstwę bot-detection.	true, false
SECURITY_BOT_SCORE_WARN_THRESHOLD	Prod / Dev	Próg score dla ostrzeżenia.	30
SECURITY_BOT_SCORE_BLOCK_THRESHOLD	Prod / Dev	Próg score dla blokady.	70
SECURITY_IP_WHITELIST_FORCE_DISABLE	Runtime override	Awaryjny override operatora wyłączający egzekwowanie zapisanej whitelisty IP.	false

CRM, pliki, importy i media produktów

Zmienna	Zakres	Cel	Typowa wartość
CRM_DEDUP_NAME_SIMILARITY_THRESHOLD	Prod / Dev	Próg podobieństwa pg_trgm dla ostrzeżeń o duplikatach firm.	0.8
CRM_DEDUP_EMAIL_DOMAIN_WARN	Prod / Dev	Ostrzega przy zgodności domen e-mail z istniejącymi rekordami.	true
CRM_ATTACHMENT_MAX_SIZE_MB	Prod / Dev	Maksymalny rozmiar załącznika CRM.	25, 10
CRM_ATTACHMENT_ALLOWED_TYPES	Prod / Dev	Dozwolone rozszerzenia załączników CRM.	pdf,doc,docx,...
CSV_IMPORT_MAX_ROWS	Prod / Dev	Limit wierszy dla importów CSV.	5000
STORAGE_PATH	Prod / Dev	Główny katalog uploadów.	/data/uploads, ./data/uploads
PIM_MEDIA_MAX_SIZE_MB	Prod / Dev	Maksymalny rozmiar pojedynczego obrazu produktu.	5, 10
PIM_MEDIA_MAX_PER_PRODUCT	Prod / Dev	Maksymalna liczba mediów dla jednego produktu.	5, 10
PIM_MEDIA_THUMBNAIL_WIDTH	Prod / Dev	Szerokość miniatur w pikselach.	300
PIM_MEDIA_ALLOWED_TYPES	Prod / Dev	Dozwolone rozszerzenia mediów produktowych.	jpg,jpeg,png,webp,svg
IMPORT_ZIP_MAX_SIZE_MB	Prod / Dev	Maksymalny rozmiar ZIP dla batch importu obrazów.	100
IMPORT_ZIP_MAX_IMAGES	Prod / Dev	Maksymalna liczba obrazów w jednym ZIP-ie.	1000
IMPORT_IMAGE_MAX_SIZE_MB	Prod / Dev	Maksymalny rozmiar pojedynczego obrazu w imporcie ZIP.	5
IMPORT_IMAGE_FUZZY_THRESHOLD	Prod / Dev	Próg fuzzy matchingu nazwy pliku do produktu.	0.82

Dostawy, FX i ustawienia ofert

Zmienna	Zakres	Cel	Typowa wartość
SHIPPING_DEFAULT_VOLUMETRIC_DIVISOR	Prod / Dev	Dzielnik wagi wolumetrycznej w kalkulacji dostawy.	4000
SHIPPING_OVERRIDE_REQUIRES_REASON	Prod / Dev	Wymaga uzasadnienia przy ręcznej zmianie kosztu dostawy.	true
FX_PROVIDER	Prod / Dev	Źródło kursów FX.	NBP, MOCK, ECB, CUSTOM
FX_PROVIDER_URL	Prod / Dev	Nadpisanie URL-a dla własnego providera FX.	puste, jeśli nie CUSTOM
FX_REFRESH_INTERVAL_MIN	Prod / Dev	Częstotliwość automatycznego odświeżania kursów.	60, 0
FX_DEFAULT_MARGIN_PERCENT	Prod / Dev	Domyślna marża procentowa nakładana na kurs providera.	0
FX_DEVIATION_WARN_PERCENT	Prod / Dev	Próg ostrzeżenia dla ręcznie korygowanych kursów.	3
FX_DEVIATION_BLOCK_PERCENT	Prod / Dev	Próg blokady dla ręcznie korygowanych kursów.	8
OFFER_NUMBER_PREFIX	Prod / Dev	Prefiks numeracji ofert.	OF

E-mail, linki publiczne i powiadomienia

Zmienna	Zakres	Cel	Typowa wartość
SMTP_HOST	Prod / Dev	Host SMTP do wysyłki ofert i powiadomień.	host dostawcy, localhost
SMTP_PORT	Prod / Dev	Port SMTP.	587, 1025, 1026
SMTP_USERNAME	Prod / Dev	Login SMTP.	konto dostawcy
SMTP_PASSWORD	Prod / Dev	Hasło SMTP.	sekret dostawcy
SMTP_AUTH	Prod / Dev	Włącza uwierzytelnianie SMTP.	true, false
SMTP_STARTTLS	Prod / Dev	Włącza negocjację STARTTLS.	true, false
PUBLIC_LINK_TOKEN_BYTES	Prod / Dev	Entropia dla tokenów linków publicznych.	32
PUBLIC_LINK_DEFAULT_EXPIRY_DAYS	Prod / Dev	Domyślny czas ważności linków publicznych.	0 = bez terminu
PUBLIC_RATE_LIMIT_OPEN_PER_HOUR	Prod / Dev	Limit godzinowy dla otwierania publicznych endpointów oferty.	60, 999
PUBLIC_RATE_LIMIT_ACTION_PER_HOUR	Prod / Dev	Limit godzinowy dla akcji publicznych, np. akceptacji/odrzucenia.	5, 999
TRACKING_IP_ANONYMIZE	Prod / Dev	Włącza anonimizację IP w danych trackingowych.	false
TRACKING_IP_ANONYMIZE_AFTER_DAYS	Prod / Dev	Opóźniona anonimizacja IP po określonej liczbie dni.	0
TRACKING_RETENTION_DAYS	Prod / Dev	Okres retencji dla danych śledzenia linków publicznych.	365
CLIENT_CONFIRM_EMAIL_ENABLED	Prod / Dev	Wysyła klientowi e-mail potwierdzający po akceptacji.	false
NOTIFICATIONS_ENABLED	Prod / Dev	Włącza subsystem powiadomień.	true
NOTIFICATIONS_EMAIL_ENABLED	Prod / Dev	Włącza dostarczanie powiadomień e-mailem.	true, false
NOTIFICATIONS_PUBLIC_PREFERENCES_URL	Prod	Publiczny URL do zarządzania preferencjami powiadomień.	https://twojadomena.pl/notifications/preferences
NOTIFICATIONS_PREFERENCE_TOKEN_TTL_DAYS	Prod	Czas ważności tokenu preferencji powiadomień.	30
NOTIFICATIONS_OFFER_EXPIRY_WARN_DAYS	Prod / Dev	Harmonogram przypomnień przed wygaśnięciem ofert.	7,2
NOTIFICATIONS_LICENSE_EXPIRY_WARN_DAYS	Prod / Dev	Harmonogram przypomnień przed wygaśnięciem licencji.	30,14,7,1
REMINDERS_JOB_INTERVAL_MINUTES	Prod / Dev	Częstotliwość wykonywania joba przypomnień.	5

Generowanie PDF

Zmienna	Zakres	Cel	Typowa wartość
PDF_ENABLED	Prod / Dev	Włącza generowanie PDF.	true, false
PDF_GOTENBERG_URL	Prod / Dev	Wewnętrzny URL usługi Gotenberg.	http://gotenberg:3000
PDF_SYNC_TIMEOUT_MS	Prod / Dev	Timeout dla synchronicznego generowania PDF.	10000, 5000
PDF_SYNC_MAX_ITEMS	Prod / Dev	Maksymalna liczba pozycji oferty nadal obsługiwana synchronicznie.	50
PDF_STORAGE_PATH	Prod / Dev	Ścieżka do katalogu przechowującego wygenerowane PDF-y.	/data/pdfs, ./data/pdfs
PDF_RETENTION_DAYS	Prod / Dev	Czas retencji wygenerowanych PDF-ów.	365
PDF_RETRY_BACKOFF_SECONDS	Prod / Dev	Harmonogram retry dla async PDF jobs.	30,120,600
PDF_WORKER_CONCURRENCY	Prod / Dev	Współbieżność workera PDF.	2
PDF_WORKER_POLL_INTERVAL_MS	Prod / Dev	Interwał odpytywania workerów PDF.	2000

Licencjonowanie, raporty i utrzymanie

Zmienna	Zakres	Cel	Typowa wartość
LICENSE_SKIP_SIGNATURE_CHECK	Prod / Dev	Omija walidację podpisu licencji. Nigdy nie włączaj w produkcji.	false, true
LICENSE_EXPIRY_CHECK_INTERVAL_H	Prod / Dev	Częstotliwość kontroli wygaśnięcia licencji.	24
REPORTS_DEFAULT_PERIOD_DAYS	Prod / Dev	Domyślny zakres dat dla raportów.	30
REPORTS_EXPORT_MAX_ROWS	Prod / Dev	Limit wierszy dla eksportów raportów.	10000

Backupy, GeoIP i operacje prywatności

Zmienna	Zakres	Cel	Typowa wartość
BACKUP_ENABLED	Prod / Dev	Włącza zaplanowane backupy.	true, false
BACKUP_CRON	Prod / Dev	Harmonogram cron dla automatycznych backupów.	0 0 2 * * *
BACKUP_RETENTION_DAILY	Prod / Dev	Liczba backupów dziennych do zachowania.	7
BACKUP_RETENTION_WEEKLY	Prod / Dev	Liczba backupów tygodniowych do zachowania.	4
BACKUP_RETENTION_MONTHLY	Prod / Dev	Liczba backupów miesięcznych do zachowania.	12
BACKUP_LOCAL_DIR	Runtime / Compose	Lokalny katalog używany przez skrypty backupu i kontenery backup-workera.	/app/data/backups
BACKUP_GPG_RECIPIENT	Prod / Dev	Odbiorca GPG do szyfrowania backupów.	fingerprint lub e-mail
BACKUP_RCLONE_REMOTE	Prod / Dev	Cel rclone dla offsite backupów.	s3:bucket/path
BACKUP_ENCRYPTION_ENABLED	Runtime override	Wewnętrzny lub smoke-testowy przełącznik zachowania szyfrowania backupów.	false
GEOIP_ENABLED	Prod / Dev	Włącza kontrolę dostępu opartą o GeoIP.	false
GEOIP_DB_PATH	Prod / Dev	Ścieżka do bazy MaxMind GeoIP.	/app/data/geoip/...
SECURITY_GEOIP_ALLOWED_COUNTRIES	Prod / Dev	Allowlista krajów ISO dla GeoIP.	puste lub PL,DE,CZ
MAXMIND_ACCOUNT_ID	Prod	Konto MaxMind do pobierania GeoLite.	account ID
MAXMIND_LICENSE_KEY	Prod	Klucz licencyjny MaxMind.	sekret
GEOIP_EDITION_ID	Prod	Identyfikator edycji MaxMind.	GeoLite2-Country
GDPR_ANONYMIZE_AUTO_AFTER_DAYS	Prod / Dev	Horyzont automatycznej anonimizacji w workflow prywatności.	0

Praktyczne wskazówki

• Dla realnych wdrożeń startuj od szablonu produkcyjnego, a dla pracy lokalnej od szablonu developerskiego.
• DB_ENCRYPTION_KEY, TIMING_TOKEN_SECRET, PUBLIC_LINK_PASSWORD_SESSION_SECRET i dane SMTP traktuj jako sekrety, które trzeba bezpiecznie backupować.
• Compose-only porty i zmienne frontendu trzymaj poza produkcyjnym .env, chyba że Twój model wdrożenia wyraźnie ich wymaga.
• Jeśli potrzebujesz tylko najmniejszego sensownego zestawu ustawień dla startu, Instalacja jest celowo krótsza od tej referencji.