###########################################################################
#                                                                         #
#              Technitium DNS Companion Configuration File                #
#                                                                         #
#        Copy this file to .env and edit the variables as needed.         #
#                                                                         #
###########################################################################

### Minimal working configuration - only 2 variables per node for clusters! ###

## Authentication note (as of v1.2.1)
#
# Preferred (recommended): Technitium-backed session authentication
#   - v1.2.x: enable with AUTH_SESSION_ENABLED=true (migration/stop-gap)
#   - v1.4+: interactive UI requires session auth (Technitium login/RBAC)
#   - Future (direction): the AUTH_SESSION_ENABLED toggle may be removed
#   - Users log in with their Technitium DNS credentials
#   - Companion stores Technitium session tokens server-side; browser gets an HttpOnly cookie
#   - Run over HTTPS (either enable Companion HTTPS directly, or terminate TLS in a reverse proxy + TRUST_PROXY=true)
#
# Legacy (still supported): env-token mode
#   - Intended only for legacy Technitium DNS deployments (< v14) and migration.
#   - Anyone who can reach the Companion UI effectively inherits the privileges of those tokens.
#   - Roadmap: starting in v1.4, the UI will require Technitium login/RBAC (session auth).

## Node Name Configuration - REQUIRED
#
#  Node names within this companion app do NOT have to match what you have
#  configured on your Technitium DNS nodes, but it's recommended to keep
#  them consistent for easier identification.
#
#  Note: Node names here are independent from Technitium DNS cluster
#  node names.
TECHNITIUM_NODES=node1,node2

## API Token Configuration - REQUIRED
#
#  How to generate an API token (legacy env-token mode):
#    1. Access Technitium DNS web interface
#    2. Go to: Administration -> Sessions -> Create Token
#    3. Select the user whose permissions you want the Companion to have
#    4. Copy the generated token
#
#  ⚠️  Warning: Keep your API tokens secure! They are credentials.
#  For most deployments as of v1.2.1, prefer session auth instead of long-lived admin tokens.
#
#  For CLUSTERED nodes (legacy env-token mode): Use TECHNITIUM_CLUSTER_TOKEN
#  When you create an API token on any node in a Technitium DNS cluster,
#  that token is automatically valid for ALL nodes in the cluster.
#
#  DEPRECATION NOTE: Deprecated as of v1.3.0. Planned removal: v1.4.
#  - Prefer Technitium-backed login sessions for interactive UI (AUTH_SESSION_ENABLED=true)
#    and TECHNITIUM_BACKGROUND_TOKEN for background jobs.
#  - Per-node TECHNITIUM_<NODE>_TOKEN is legacy-only (Technitium DNS < v14) and is NOT the
#    recommended configuration for v14+.
#
#  If you still need it (legacy env-token mode), simply create the token once on your primary node and use it here:
TECHNITIUM_CLUSTER_TOKEN=your-shared-cluster-token

#  Legacy only (Technitium DNS < v14): Per-node tokens
#  If you have older standalone nodes (or mixed legacy environments), you can use:
#    TECHNITIUM_<NODE>_TOKEN
#  Note: starting in v1.4, the UI will require Technitium login/RBAC; env-token mode is
#  intended only for legacy/migration.

## Docker Secrets / File-based Secrets Support - OPTIONAL
#
#  For sensitive environment variables, you can use the `_FILE` suffix pattern
#  common in Docker containers. When `VAR_FILE` is set, the application reads
#  the secret value from that file path instead of expecting `VAR` directly.
#
#  This is useful for:
#    - Docker Swarm secrets (mounted at /run/secrets/)
#    - Kubernetes secrets (mounted as files)
#    - Any file-based secrets management
#
#  Supported variables:
#    TECHNITIUM_CLUSTER_TOKEN_FILE     -> reads TECHNITIUM_CLUSTER_TOKEN from file
#    TECHNITIUM_BACKGROUND_TOKEN_FILE  -> reads TECHNITIUM_BACKGROUND_TOKEN from file
#    TECHNITIUM_<NODE>_TOKEN_FILE      -> reads per-node token from file
#
#  Example (Docker Swarm):
#    TECHNITIUM_CLUSTER_TOKEN_FILE=/run/secrets/technitium_cluster_token
#    TECHNITIUM_BACKGROUND_TOKEN_FILE=/run/secrets/technitium_background_token
#
#  The _FILE variant takes precedence if both are set.

## Base URL for each node - REQUIRED
#
#  For BASE_URL, use the URL including port number that you use to access
#  the Technitium DNS web interface.
#
#  Default Technitium DNS ports:
#    HTTP:  5380
#    HTTPS: 53443
#
#  Variable Key Format:
#    TECHNITIUM_<Uppercase_Node_Name>_BASE_URL=http://192.168.1.10:5380
#
#  Simple cluster example (2 nodes, 1 shared token):
TECHNITIUM_NODE1_BASE_URL=http://192.168.1.10:5380
TECHNITIUM_NODE2_BASE_URL=http://192.168.1.11:5380

#  Legacy only: Override token for a specific node (optional)
#  If one legacy node needs a different token, you can override the cluster token:
# TECHNITIUM_NODE2_TOKEN=different-token-for-node2

## Session-based Authentication (recommended for interactive UI) - OPTIONAL
#
# When enabled, the Companion uses `/api/auth/login` to create a server-side session
# (HttpOnly cookie) and stores Technitium `/api/user/login` session tokens server-side.
#
# Preferred as of v1.2.1: enable this for interactive UI access.
# v1.2.x: this is a migration toggle.
# v1.4+: interactive UI requires session auth (Technitium login/RBAC).
# Future (direction): this flag may be removed.
#
# IMPORTANT: When AUTH_SESSION_ENABLED=true, you should run the Companion UI/API over HTTPS
# to protect credentials and session cookies.
#
# If you terminate TLS in a reverse proxy (recommended for many deployments), enable:
#   TRUST_PROXY=true
# so the backend can detect HTTPS via `X-Forwarded-Proto`.
#
# In session-auth mode, TECHNITIUM_*_TOKEN / TECHNITIUM_CLUSTER_TOKEN are OPTIONAL.
# If you leave env tokens blank (recommended for v1.3-style deployments), the app will be usable only after login.
# Background jobs (scheduled sync, PTR warming) will require TECHNITIUM_BACKGROUND_TOKEN.
#
# AUTH_SESSION_ENABLED=true

# Reverse proxy configuration (OPTIONAL)
# Only enable if the backend is behind a trusted reverse proxy that sets X-Forwarded-* headers.
# WARNING: Do not enable if the backend is directly exposed to untrusted clients.
#
# TRUST_PROXY=true
# TRUST_PROXY_HOPS=1

# What is TRUST_PROXY_HOPS?
# - It's the number of trusted proxy hops in front of the Companion.
# - This lets the backend correctly interpret X-Forwarded-Proto (HTTPS detection) and X-Forwarded-For (client IP).
# - Set to 1 for: reverse proxy (nginx/Traefik/Caddy) -> Companion
# - Set to 2 for: CDN/LB (e.g., Cloudflare) -> reverse proxy -> Companion
# - Do NOT enable TRUST_PROXY unless you control/trust the proxy chain; otherwise clients can spoof forwarded headers.

## Background Token (read-only, for background jobs) - OPTIONAL
#
# NOTE (planned change): As of v1.3, TECHNITIUM_BACKGROUND_TOKEN is expected to be REQUIRED
# for background features (e.g., PTR hostname warming, scheduled sync) since background jobs
# do not have a user session context.
#
# When AUTH_SESSION_ENABLED=true, background timers do not have a user session context.
# If you want background features like PTR hostname warming, set a read-only token here.
# The backend will validate the token on startup and will disable background PTR warming
# if the token is too privileged (Modify/Delete/Admin) or lacks required permissions.
#
# IMPORTANT: This should be a token for a low-privilege Technitium user (read-only).
# Do NOT reuse a full admin token.
#
# TECHNITIUM_BACKGROUND_TOKEN=your-readonly-token

## SQLite Rolling Query Logs Storage (optional, improves accuracy for "Last 24h")
#
# When enabled, the backend continuously ingests query logs into a local SQLite DB
# and serves "stored" endpoints used by the Logs UI in paginated mode.
# Tail mode remains live (reads directly from Technitium nodes).
#
# IMPORTANT (session-auth mode): If AUTH_SESSION_ENABLED=true, background timers do not
# have a user session token. To keep the DB up-to-date, you must set TECHNITIUM_BACKGROUND_TOKEN
# to a least-privilege token that can read query logs.
#
# QUERY_LOG_SQLITE_ENABLED=true
# QUERY_LOG_SQLITE_PATH=/data/query-logs.sqlite
# QUERY_LOG_SQLITE_RETENTION_HOURS=24
# QUERY_LOG_SQLITE_POLL_INTERVAL_MS=10000
# QUERY_LOG_SQLITE_OVERLAP_SECONDS=60
# QUERY_LOG_SQLITE_MAX_ENTRIES_PER_POLL=20000

## DNS Filtering History (snapshots) storage (optional)
#
# DNS Filtering History stores snapshot JSON files on the backend filesystem.
# This enables quick rollback for Built-in Blocking and Advanced Blocking changes.
#
# Defaults:
# - Directory: `/data/dns-filtering-snapshots` (in Docker) or a local project/tmp dir in dev.
# - Retention: 20 snapshots per method per node (unpinned). Pinned snapshots are not pruned.
#
# To persist snapshots across container restarts, keep the `/data` volume mount and either:
# - set `DNS_FILTERING_SNAPSHOT_DIR=/data/dns-filtering-snapshots`, or
# - leave it unset (the service will try sensible defaults).
#
# DNS_FILTERING_SNAPSHOT_DIR=/data/dns-filtering-snapshots
# DNS_FILTERING_SNAPSHOT_RETENTION=20

#  Legacy only (Technitium DNS < v14 / migration): per-node env tokens
#  If you're running older non-clustered nodes, you can use per-node tokens:
# TECHNITIUM_NODE1_TOKEN=token-for-node1
# TECHNITIUM_NODE2_TOKEN=token-for-node2

## Node display names (defaults to node ID if not set) - OPTIONAL
# TECHNITIUM_NODE1_NAME="Primary Server"
# TECHNITIUM_NODE2_NAME="Secondary Server"

## HTTPS for >Companion< backend API - OPTIONAL
## Backend API defaults to HTTP on port 3000 if these are not set
# HTTPS_ENABLED=true
# HTTPS_PORT=3443
# HTTPS_CERT_PATH=/path/to/fullchain.pem
# HTTPS_KEY_PATH=/path/to/privkey.pem
# HTTPS_CA_PATH=/path/to/ca.pem  # Optional, for self-signed certs

## >Companion< Custom query logger - OPTIONAL
## Only if using custom logger app
# TECHNITIUM_NODE1_QUERY_LOGGER_APP_NAME=MySQLLogger
# TECHNITIUM_NODE1_QUERY_LOGGER_CLASS_PATH=MySQLLogger.Logger

## Cache directory - OPTIONAL (for domain lists caching)
## Defaults to /data/domain-lists-cache
# CACHE_DIR=/custom/cache/path

## CORS - OPTIONAL (only needed for cross-origin development)
# CORS_ORIGINS=https://localhost:5174,https://example.com