Skip to content

Speakr is a personal, self-hosted web application designed for transcribing audio recordings

Python

Document the auto-generated SECRET_KEY behavior and the new security-header/CSP/HSTS env toggles in the env examples

Murtaza Nasir016e5aa78da9
diff --git a/config/env.asr.example b/config/env.asr.example
index bcea4492..ee8f7869 100644
--- a/config/env.asr.example
+++ b/config/env.asr.example
@@ -131,17 +131,30 @@ CHAT_MAX_TOKENS=5000
# EVENT_MAX_TOKENS=3000
# --- Session Security ---
-# Flask secret key used to sign session cookies and email/security tokens.
-# STRONGLY RECOMMENDED in production: set this to a long random value (e.g.
-# `python -c "import secrets; print(secrets.token_hex(32))"`). If left unset
-# the app falls back to a publicly-known built-in dev key, which is insecure
-# (session cookies could be forged), so always set it in production.
+# Flask secret key: signs session cookies and email/password-reset tokens. It
+# does NOT encrypt stored data, so a lost key means a one-time re-login for
+# everyone, never data loss. If unset, the app auto-generates a strong key and
+# persists it under the instance directory (captured by a normal data-volume
+# backup); the old publicly-known built-in default is refused at startup. Set
+# this explicitly for multi-host deployments or to control key rotation:
+# `python -c "import secrets; print(secrets.token_hex(32))"`.
# SECRET_KEY=change-me-to-a-long-random-string
-# Only send the session cookie over HTTPS. Set to true in HTTPS production
-# deployments. Default: false (so plain-HTTP local setups keep working).
+# Only send the session cookie over HTTPS. STRONGLY recommended (true) for any
+# HTTPS deployment. Default: false so plain-HTTP LAN setups keep working.
# SESSION_COOKIE_SECURE=false
+# --- Security headers ---
+# The app sets X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+# Permissions-Policy, a Content-Security-Policy, and (over HTTPS) HSTS, so a
+# deployment without a hardening proxy is still protected. Set
+# SECURITY_HEADERS_ENABLED=false only if your proxy already sets all of these.
+# Override the CSP wholesale with CONTENT_SECURITY_POLICY, or tune HSTS with
+# HSTS_HEADER (empty disables it, e.g. if your proxy already sends HSTS).
+# SECURITY_HEADERS_ENABLED=true
+# CONTENT_SECURITY_POLICY=
+# HSTS_HEADER=max-age=63072000; includeSubDomains
+
# Number of trusted reverse-proxy hops in front of the app (X-Forwarded-For/
# Proto). Default: 1 (one proxy, e.g. nginx/Traefik). Increase if you chain
# additional proxies/load balancers so client IPs and HTTPS detection are read
diff --git a/config/env.transcription.example b/config/env.transcription.example
index 298d5f52..82942d85 100644
--- a/config/env.transcription.example
+++ b/config/env.transcription.example
@@ -266,17 +266,30 @@ ALLOW_REGISTRATION=false
REGISTRATION_ALLOWED_DOMAINS=
# --- Session Security ---
-# Flask secret key used to sign session cookies and email/security tokens.
-# STRONGLY RECOMMENDED in production: set this to a long random value (e.g.
-# `python -c "import secrets; print(secrets.token_hex(32))"`). If left unset
-# the app falls back to a publicly-known built-in dev key, which is insecure
-# (session cookies could be forged), so always set it in production.
+# Flask secret key: signs session cookies and email/password-reset tokens. It
+# does NOT encrypt stored data, so a lost key means a one-time re-login for
+# everyone, never data loss. If unset, the app auto-generates a strong key and
+# persists it under the instance directory (captured by a normal data-volume
+# backup); the old publicly-known built-in default is refused at startup. Set
+# this explicitly for multi-host deployments or to control key rotation:
+# `python -c "import secrets; print(secrets.token_hex(32))"`.
# SECRET_KEY=change-me-to-a-long-random-string
-# Only send the session cookie over HTTPS. Set to true in HTTPS production
-# deployments. Default: false (so plain-HTTP local setups keep working).
+# Only send the session cookie over HTTPS. STRONGLY recommended (true) for any
+# HTTPS deployment. Default: false so plain-HTTP LAN setups keep working.
# SESSION_COOKIE_SECURE=false
+# --- Security headers ---
+# The app sets X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+# Permissions-Policy, a Content-Security-Policy, and (over HTTPS) HSTS, so a
+# deployment without a hardening proxy is still protected. Set
+# SECURITY_HEADERS_ENABLED=false only if your proxy already sets all of these.
+# Override the CSP wholesale with CONTENT_SECURITY_POLICY, or tune HSTS with
+# HSTS_HEADER (empty disables it, e.g. if your proxy already sends HSTS).
+# SECURITY_HEADERS_ENABLED=true
+# CONTENT_SECURITY_POLICY=
+# HSTS_HEADER=max-age=63072000; includeSubDomains
+
# Number of trusted reverse-proxy hops in front of the app (X-Forwarded-For/
# Proto). Default: 1 (one proxy, e.g. nginx/Traefik). Increase if you chain
# additional proxies/load balancers so client IPs and HTTPS detection are read
diff --git a/config/env.whisper.example b/config/env.whisper.example
index d83a14a8..50e5bdf7 100644
--- a/config/env.whisper.example
+++ b/config/env.whisper.example
@@ -114,17 +114,30 @@ CHAT_MAX_TOKENS=5000
# EVENT_MAX_TOKENS=3000
# --- Session Security ---
-# Flask secret key used to sign session cookies and email/security tokens.
-# STRONGLY RECOMMENDED in production: set this to a long random value (e.g.
-# `python -c "import secrets; print(secrets.token_hex(32))"`). If left unset
-# the app falls back to a publicly-known built-in dev key, which is insecure
-# (session cookies could be forged), so always set it in production.
+# Flask secret key: signs session cookies and email/password-reset tokens. It
+# does NOT encrypt stored data, so a lost key means a one-time re-login for
+# everyone, never data loss. If unset, the app auto-generates a strong key and
+# persists it under the instance directory (captured by a normal data-volume
+# backup); the old publicly-known built-in default is refused at startup. Set
+# this explicitly for multi-host deployments or to control key rotation:
+# `python -c "import secrets; print(secrets.token_hex(32))"`.
# SECRET_KEY=change-me-to-a-long-random-string
-# Only send the session cookie over HTTPS. Set to true in HTTPS production
-# deployments. Default: false (so plain-HTTP local setups keep working).
+# Only send the session cookie over HTTPS. STRONGLY recommended (true) for any
+# HTTPS deployment. Default: false so plain-HTTP LAN setups keep working.
# SESSION_COOKIE_SECURE=false
+# --- Security headers ---
+# The app sets X-Frame-Options, X-Content-Type-Options, Referrer-Policy,
+# Permissions-Policy, a Content-Security-Policy, and (over HTTPS) HSTS, so a
+# deployment without a hardening proxy is still protected. Set
+# SECURITY_HEADERS_ENABLED=false only if your proxy already sets all of these.
+# Override the CSP wholesale with CONTENT_SECURITY_POLICY, or tune HSTS with
+# HSTS_HEADER (empty disables it, e.g. if your proxy already sends HSTS).
+# SECURITY_HEADERS_ENABLED=true
+# CONTENT_SECURITY_POLICY=
+# HSTS_HEADER=max-age=63072000; includeSubDomains
+
# Number of trusted reverse-proxy hops in front of the app (X-Forwarded-For/
# Proto). Default: 1 (one proxy, e.g. nginx/Traefik). Increase if you chain
# additional proxies/load balancers so client IPs and HTTPS detection are read