From a81737b2cec7f144ead1a71a15ad1dadee7db51c Mon Sep 17 00:00:00 2001
From: gru <gru@gitea.linuxiarz.pl>
Date: Mon, 28 Jul 2025 22:16:54 +0200
Subject: [PATCH] Update .env.example

---
 .env.example | 131 ++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 119 insertions(+), 12 deletions(-)

diff --git a/.env.example b/.env.example
index e9e2bf8..217aac8 100644
--- a/.env.example
+++ b/.env.example
@@ -1,29 +1,60 @@
-# Domyślny port aplikacji
+# APP_PORT:
+# Domyślny port, na którym uruchamiana jest aplikacja Flask
+# Domyślnie: 8000
 APP_PORT=8000
 
-# Klucz bezpieczeństwa Flask
+# SECRET_KEY:
+# Klucz używany przez Flask do zabezpieczenia sesji, tokenów i formularzy
+# Powinien być długi i trudny do odgadnięcia
 SECRET_KEY=supersekretnyklucz123
 
-# Hasło główne do systemu
+# SYSTEM_PASSWORD:
+# Hasło główne administratora systemowego, używane np. przy inicjalizacji
+# Domyślnie: admin
 SYSTEM_PASSWORD=admin
 
-# Domyślny admin (login i hasło)
+# DEFAULT_ADMIN_USERNAME:
+# Domyślna nazwa użytkownika administratora (tworzona przy starcie)
+# Domyślnie: admin
 DEFAULT_ADMIN_USERNAME=admin
+
+# DEFAULT_ADMIN_PASSWORD:
+# Domyślne hasło administratora
+# Domyślnie: admin123
 DEFAULT_ADMIN_PASSWORD=admin123
 
-# Katalog wgrywanych plików
+# UPLOAD_FOLDER:
+# Ścieżka (względna) do katalogu, gdzie zapisywane są wgrywane pliki
+# Domyślnie: uploads
 UPLOAD_FOLDER=uploads
 
-AUTHORIZED_COOKIE_VALUE=twoj_wlasny_hash
+# SESSION_TIMEOUT_MINUTES:
+# Czas bezczynności użytkownika (w minutach), po którym sesja wygasa
+# Domyślnie: 10080 (7 dni)
+SESSION_TIMEOUT_MINUTES=10080
 
-# czas zycia cookie
+# AUTH_COOKIE_MAX_AGE:
+# Czas życia ciasteczka autoryzacyjnego (w sekundach)
+# Domyślnie: 86400 (1 dzień)
 AUTH_COOKIE_MAX_AGE=86400
 
-# dla compose
-HEALTHCHECK_TOKEN=alamapsaikota123
+# AUTHORIZED_COOKIE_VALUE:
+# Wartość ciasteczka uprawniającego do dostępu (np. do zasobów zabezpieczonych)
+# Powinna być trudna do przewidzenia
+AUTHORIZED_COOKIE_VALUE=twoj_wlasny_hash
 
-# sesja zalogowanego usera (domyślnie 7 dni)
-SESSION_TIMEOUT_MINUTES=10080
+# SESSION_COOKIE_SECURE:
+# Określa, czy ciasteczko sesyjne (Flask session) ma mieć ustawiony atrybut "Secure".
+# Wymusza, by przeglądarka przesyłała je tylko przez HTTPS.
+# W środowisku deweloperskim (HTTP) ustaw na 0, by uniknąć błędu "secure cookie over insecure connection".
+# Zalecane: 1 w produkcji (HTTPS), 0 w dev.
+SESSION_COOKIE_SECURE=0
+
+
+# HEALTHCHECK_TOKEN:
+# Token wykorzystywany do sprawdzania stanu aplikacji (np. w Docker Compose)
+# Domyślnie: alamapsaikota123
+HEALTHCHECK_TOKEN=alamapsaikota123
 
 # Rodzaj bazy: sqlite, pgsql, mysql
 # Mozliwe wartosci: sqlite / pgsql / mysql
@@ -44,10 +75,86 @@ DB_ENGINE=sqlite
 # Wymaga kontenera z MySQL i uzytkownika z dostepem do bazy
 
 # Wspolne zmienne (dla pgsql, mysql)
-# DB_HOST = pgsql lub mysql zgondie z deployem (profil w docker-compose.yml)
+# DB_HOST = pgsql lub mysql zgodnie z deployem (profil w docker-compose.yml)
 
 DB_HOST=pgsql 
 DB_PORT=5432
 DB_NAME=myapp
 DB_USER=user
 DB_PASSWORD=pass
+
+# ========================
+# Nagłówki bezpieczeństwa
+# ========================
+
+# ENABLE_HSTS:
+# Wymusza HTTPS poprzez ustawienie nagłówka Strict-Transport-Security.
+# Zalecane (1) jeśli aplikacja działa za HTTPS. Ustaw 0, jeśli korzystasz z HTTP lokalnie.
+ENABLE_HSTS=1
+
+# ENABLE_XFO:
+# Ustawia nagłówek X-Frame-Options: DENY, który blokuje osadzanie strony w <iframe>.
+# Chroni przed atakami typu clickjacking. Ustaw 0, jeśli celowo korzystasz z osadzania.
+ENABLE_XFO=1
+
+# ENABLE_XCTO:
+# Ustawia nagłówek X-Content-Type-Options: nosniff, który zapobiega sniffowaniu MIME przez przeglądarkę.
+# Chroni przed błędną interpretacją typów plików (np. skrypt JS jako obraz). Zalecane: 1.
+ENABLE_XCTO=1
+
+# ENABLE_CSP:
+# Ustawia podstawową politykę Content-Security-Policy (CSP), która ogranicza wczytywanie zasobów tylko z własnej domeny.
+# Zalecane: 1. Ustaw 0, jeśli używasz zewnętrznych skryptów lub masz problemy z WebSocketami (w CSP: connect-src 'self').
+ENABLE_CSP=1
+
+# REFERRER_POLICY:
+# Ustawia nagłówek Referrer-Policy, który kontroluje, ile informacji o źródle (refererze)
+# jest przekazywane podczas nawigacji lub zapytań sieciowych.
+# Domyślnie: strict-origin-when-cross-origin — pełny URL tylko w obrębie tej samej domeny,
+# a przy przejściach między domenami tylko origin (np. https://example.com).
+# Zalecane ustawienie dla dobrej równowagi między prywatnością a funkcjonalnością.
+# Inne możliwe wartości: no-referrer, same-origin, origin, strict-origin, unsafe-url itd.
+
+REFERRER_POLICY="strict-origin-when-cross-origin"
+
+
+# DEBUG_MODE:
+# Czy uruchomić aplikację w trybie debugowania (z konsolą błędów i autoreloaderem)
+# Domyślnie: 1
+DEBUG_MODE=1
+
+# DISABLE_ROBOTS:
+# Czy zablokować indeksowanie przez roboty (serwuje robots.txt z Disallow: /)
+# Domyślnie: 0
+DISABLE_ROBOTS=0
+
+
+# ========================
+# Nagłówki cache
+# ========================
+
+# JS_CACHE_CONTROL:
+# Nagłówki Cache-Control dla plików JS (/static/js/)
+# Domyślnie: "no-cache, no-store, must-revalidate"
+JS_CACHE_CONTROL="no-cache, no-store, must-revalidate"
+
+# CSS_CACHE_CONTROL:
+# Nagłówki Cache-Control dla plików CSS (/static/css/)
+# Domyślnie: "public, max-age=3600"
+CSS_CACHE_CONTROL="public, max-age=3600"
+
+# LIB_JS_CACHE_CONTROL:
+# Nagłówki Cache-Control dla bibliotek JS (/static/lib/js/)
+# Domyślnie: "public, max-age=604800"
+LIB_JS_CACHE_CONTROL="public, max-age=604800"
+
+# LIB_CSS_CACHE_CONTROL:
+# Nagłówki Cache-Control dla bibliotek CSS (/static/lib/css/)
+# Domyślnie: "public, max-age=604800"
+LIB_CSS_CACHE_CONTROL="public, max-age=604800"
+
+# UPLOADS_CACHE_CONTROL:
+# Nagłówki Cache-Control dla wgrywanych plików (/uploads/)
+# Domyślnie: "public, max-age=2592000, immutable"
+UPLOADS_CACHE_CONTROL="public, max-age=2592000, immutable"
+