Configuration

Configuration

Configuration is stored in config.json inside the Docker volume and persists across restarts. Environment variables override config.json values.

Via Web UI (recommended)

1. Start the container. The first-run page offers a demo, the setup wizard, or a backup restore.
2. In the wizard, choose your modem, enter its URL and credentials, and test the connection.
3. Set the poll interval and time zone.
4. Done. Monitoring starts immediately.

Access /settings at any time to change configuration, set an admin password, configure integrations, or adjust appearance. See First-Time Setup.

Via Environment Variables

Copy .env.example to .env and edit:

Modem

Variable	Default	Description
MODEM_TYPE	fritzbox	Modem driver (see table below). The generic driver requires no credentials and works with any router (fiber, DSL, satellite) but collects no DOCSIS channel data.

Supported modem types:

Type	Modem	Default URL	Auth
fritzbox	AVM FRITZ!Box	http://192.168.178.1	Username + password
tc4400	Technicolor TC4400	http://192.168.100.1	HTTP Basic Auth
ultrahub7	Vodafone Ultra Hub 7	--	Password only
vodafone_station	Vodafone Station (CGA/TG)	http://192.168.0.1	Username + password
ch7465	Compal CH7465 (Connect Box)	http://192.168.100.1	Username + password
ch7465_play	Compal CH7465 (Play/UPC)	http://192.168.0.1	Password only
cm1000	Netgear CM1000	http://192.168.100.1	Username + password
cm3000	Netgear CM3000	http://192.168.100.1	Username + password
cm3500	Arris CM3500B	https://192.168.100.1	Username + password
surfboard	Arris SURFboard (S33/S34/SB8200)	https://192.168.100.1	Username + password
sb8200_cbn	Arris SURFboard SB8200 (CBN firmware)	https://192.168.100.1	Username + password
cm8200	Arris Touchstone CM8200A	https://192.168.100.1	Username + password
hitron	Hitron CODA-56	http://192.168.100.1	No auth required
hitron_coda_4680	Hitron CODA-4680	http://192.168.100.1	Username + password
sagemcom	Sagemcom F@st 3896	http://192.168.100.1	Username + password
f3896lg	Sagemcom F3896LG (Virgin Media Hub 5 / Liberty Global)	https://192.168.100.1	No auth required
pyur_fast3896	PYUR FAST3896-15 (experimental, main only)	http://192.168.100.1	Password only
sb6141	Arris/Motorola SB6141	http://192.168.100.1	No auth required
sb6183	Arris SB6183	http://192.168.100.1	No auth required
sb6190	Arris SB6190	https://192.168.100.1	Username + password
sercom_dm1000	Sercom DM1000	http://192.168.100.1	Username (technician) + password
cgm4981	Technicolor CGM4981COM / Cox Panoramic Gateway PM8 / XB8	http://192.168.0.1	Username + password
generic	Generic Router (no DOCSIS)	--	No auth required

Community driver modules add their manifest id as an additional modem type on main; see Driver Modules.

| MODEM_URL | http://192.168.178.1 | Modem URL | | MODEM_USER | | Modem username | | MODEM_PASSWORD | | Modem password |

ISP_NAME is stored through the setup wizard or Settings in config.json; it is not an environment variable in the current release.

General

Variable	Default	Description
POLL_INTERVAL	900	Polling interval in seconds (60--14400)
HISTORY_DAYS	0	Snapshot retention in days (0 = unlimited)
WEB_PORT	8765	Internal web UI port. For Docker, usually leave this at 8765 and change the host-side port mapping, for example 9876:8765.
ADMIN_PASSWORD		Web UI password protection (hashed with scrypt, optional)
LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, ERROR)
DOCSIGHT_AUDIT_JSON		Set to 1 to emit audit log entries as structured JSON instead of plain text
DEMO_MODE	false	Enable demo mode with synthetic data (no real modem needed)
DATA_DIR	/data	Directory for config.json, databases, and keys
MODULES_DIR	/data/modules	Search path for community modules and themes
SESSION_LIFETIME_DAYS	30	Rolling admin session lifetime in days (1--365)
UPDATE_CHECK_ENABLED	false	Opt in to checking GitHub for a newer release

Integer settings must be whole numbers. Saving a value such as 1500.5 for an integer setting fails with <setting> must be a whole number (main); a stored value that cannot be read falls back to the setting's default.

Reverse Proxy

Variable	Default	Description
REVERSE_PROXY		Exact number of trusted proxy hops for the forwarded client address and protocol. Enables secure, HTTPS-only session cookies.
BASE_PATH		External path prefix that the proxy strips before forwarding, for example /docsight. Leave empty when DOCSight runs at the root of its address.
REVERSE_PROXY_PREFIX	0	Exact number of trusted proxy hops that set X-Forwarded-Prefix. Separate from REVERSE_PROXY; neither enables the other.

See Reverse Proxy for both prefix modes and proxy examples.

MQTT / Home Assistant

Variable	Default	Description
MQTT_HOST		MQTT broker host (optional, enables HA integration)
MQTT_PORT	1883	MQTT broker port (8883 enables TLS automatically)
MQTT_USER		MQTT username (optional)
MQTT_PASSWORD		MQTT password (optional)
MQTT_TLS_INSECURE	false	Disable TLS certificate verification (for self-signed certs)
MQTT_TOPIC_PREFIX	docsight	MQTT topic prefix for sensor data
MQTT_DISCOVERY_PREFIX	homeassistant	Home Assistant MQTT discovery prefix
PUBLIC_URL		Public URL for HA device link (e.g. https://docsight.example.com). Only used for the MQTT discovery link; it does not set a path prefix (see BASE_PATH).

Integrations

Variable	Default	Description
SPEEDTEST_TRACKER_URL		Speedtest Tracker URL (optional)
SPEEDTEST_TRACKER_TOKEN		Speedtest Tracker API token (optional)
SPEEDTEST_TLS_INSECURE	false	Disable TLS certificate verification for self-signed Speedtest Tracker HTTPS (optional)
BOOKED_DOWNLOAD	0	Your booked download speed in Mbit/s (for speedtest color coding)
BOOKED_UPLOAD	0	Your booked upload speed in Mbit/s (for speedtest color coding)
BQM_URL		ThinkBroadband BQM share URL (CSV preferred, PNG legacy fallback, optional)
GAMING_QUALITY_ENABLED	true	Enable the Gaming Quality Index view and Home badge
SEGMENT_UTILIZATION_ENABLED	true	Collect cable segment utilization on FRITZ!Box modems
WEATHER_ENABLED, WEATHER_LATITUDE, WEATHER_LONGITUDE		Outdoor temperature from Open-Meteo for the Weather overlay
METRICS_REQUIRE_TOKEN	false	Require a Bearer API token for /metrics
MODULE_REGISTRY_URL	docsight-modules registry	Registry used by Settings > Extensions to browse community modules
BNETZ_ENABLED	true	Show BNetzA integration in the navigation and on Home

Notifications

Variable	Default	Description
NOTIFY_WEBHOOK_URL		Webhook URL for alerts (optional, enables notifications)
NOTIFY_WEBHOOK_TOKEN		Webhook auth token (optional)
NOTIFY_APPRISE_ENABLED	false	Enable the optional Apprise API delivery channel
NOTIFY_APPRISE_URL		Apprise API base URL, for example http://apprise:8000
NOTIFY_APPRISE_KEY		Optional Apprise persistent config key
NOTIFY_APPRISE_TOKEN		Optional Bearer token for protected Apprise API servers
NOTIFY_APPRISE_TAG		Optional comma-separated Apprise tags for route selection
NOTIFY_MIN_SEVERITY	warning	Minimum severity to trigger alerts (info, warning, critical)
NOTIFY_COOLDOWN	3600	Cooldown between repeated alerts in seconds
NOTIFY_COOLDOWNS	{}	Per-event cooldown overrides as a JSON object
NOTIFY_PWA_PUSH_ENABLED	false	Enable PWA Web Push delivery
NOTIFY_PWA_PUSH_VAPID_PUBLIC_KEY		VAPID public key for browser subscriptions
NOTIFY_PWA_PUSH_VAPID_PRIVATE_KEY		VAPID private key (secret, encrypted at rest)
NOTIFY_PWA_PUSH_VAPID_SUBJECT	mailto:admin@example.com	Contact URI sent to push services
HEALTH_HYSTERESIS	0	Consecutive polls required before confirming a health state change (0 = instant)

DOCSight applies severity filters, per-event toggles, and cooldowns before any direct webhook, Discord webhook, Apprise sidecar, or Web Push delivery. Provider-specific credentials should live in Apprise where possible. See Notifications for the Apprise sidecar, Web Push setup, target examples, and privacy notes.

Smart Capture

Variable	Default	Description
SC_ENABLED	false	Enable Smart Capture (requires Speedtest Tracker)
SC_TRIGGER_MODULATION	true	Trigger on QAM modulation downgrades
SC_TRIGGER_SNR	false	Trigger on SNR degradation
SC_TRIGGER_ERROR_SPIKE	false	Trigger on uncorrectable error spikes
SC_TRIGGER_HEALTH	false	Trigger on health state changes
SC_GLOBAL_COOLDOWN	300	Minimum seconds between any two captures
SC_TRIGGER_COOLDOWN	900	Minimum seconds between same-trigger captures
SC_MAX_ACTIONS_PER_HOUR	4	Maximum speedtest triggers per hour
SC_FLAPPING_WINDOW	3600	Time window in seconds for flapping detection
SC_FLAPPING_THRESHOLD	3	Trigger matches within flapping window before blocking

Further Smart Capture variables (packet loss trigger, trigger details, Speedtest limits) are listed in Smart Capture.

BNetzA File Watcher

Variable	Default	Description
BNETZ_WATCH_ENABLED	false	Auto-import measurement files from a watched directory
BNETZ_WATCH_DIR	/data/bnetz	Directory to watch for BNetzA measurement files

Settings Sections

The settings page is organized into sections:

1. Connection -- Modem type, URL, credentials, ISP name
2. General -- Poll interval, history retention, timezone, language, temperature unit, update check
3. Notifications -- Webhook, Discord, Apprise sidecar, PWA Web Push, severity filtering, per-event toggles and cooldowns, health hysteresis
4. Smart Capture -- Trigger events, guardrails, execution history (details)
5. Appearance -- Dark mode, system font, and the theme gallery (details)
6. Security -- Admin password, session settings, API tokens
7. Extensions -- Feature toggles (Gaming Quality Index, BNetzA, Segment Utilization) and module management
8. About and Support

Integration tabs (Backup & Restore, BNetzA File Watcher, Connection Monitor, MQTT Broker, Speedtest Tracker, BQM Graphs, Smokeping, Weather, and other modules with settings) appear below the main sections. Guided setup dialogs for Speedtest, BQM, and Smokeping link to the matching module panels and use the Settings validation path instead of claiming success inside the setup dialog.

Security

• Secrets at rest: Modem password, MQTT password, Speedtest Tracker token, Apprise credentials, the VAPID private key, and module-declared secrets are encrypted with Fernet (AES-128-CBC). The encryption key is stored in .config_key inside the data volume. Secret fields are masked in Settings.
• Admin password: Hashed with scrypt (via Werkzeug). The plaintext is never stored.
• Session: HTTPOnly cookies with a rolling 30-day lifetime (SESSION_LIFETIME_DAYS, 1--365 days) and SameSite=Lax. Behind REVERSE_PROXY, cookies are also marked Secure. Changing the admin password invalidates existing sessions.
• Legacy migration: Old fritz_* config keys and FRITZ_* environment variables are automatically migrated to modem_* on startup.

Timezone

DOCSight stores all timestamps internally as UTC with Z-suffix (YYYY-MM-DDTHH:MM:SSZ). The configured timezone is used to convert UTC to local time for display in the web UI, charts, and reports.

API responses are not uniform: many read endpoints (for example events, trends, channel history, and the channel status matrix) convert timestamps to the configured timezone and return local time without a Z suffix, while values that end in Z are UTC. Treat a timestamp without Z as local time in the configured timezone.

Main branch (latest): the web UI formats dates and times in the selected UI language and places timestamps and chart data in the configured DOCSight timezone, even when the browser runs in a different timezone. The Before/After Comparison date fields are the exception and use the browser's local time.

DOCSight uses IANA timezones (e.g. Europe/Berlin, America/New_York) which correctly handle daylight saving time. The timezone dropdown in Setup and Settings only shows IANA names -- POSIX abbreviations like CET or EST are excluded because they do not support DST transitions.

How timezone is determined (in order of priority):

1. Timezone selected in the DOCSight UI (stored in config.json)
2. System timezone discovered from /etc/localtime
3. IANA-style container TZ environment variable as a fallback

The current release does not support a separate TIMEZONE environment variable. Use the UI setting for DOCSight itself, or set container TZ only as a fallback. If your container uses a POSIX abbreviation (e.g. TZ=CET), DOCSight shows a warning in Settings prompting you to select a proper IANA timezone. This prevents clock drift during summer time.

Migration from older versions: On first startup after upgrading to v2026-02-22.4+, DOCSight automatically converts existing naive local timestamps to UTC using the configured timezone. A safety backup of the database (docsis_history.db.pre_utc_migration) is created before conversion. The migration runs once and is recorded in the _docsight_meta table.

Speedtest Color Coding

Speed figures on Home and in the Speedtest view use color coding to show how your actual speed compares to what you are paying for:

Ratio	Color	Meaning
≥ 80%	🟢 Green	Getting what you pay for
50-80%	🟡 Yellow	Below expected performance
< 50%	🔴 Red	Significantly below booked speed

DOCSight automatically uses your modem's connection info to determine the booked speed (where supported). You can also set it manually in Settings under "Booked Download" and "Booked Upload".