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 setup wizard opens automatically.
2. Enter your modem URL, username, and password. Test the connection.
3. Optionally configure MQTT broker for Home Assistant integration.
4. Set poll interval, history retention, and language.
5. Done. Monitoring starts immediately.

Access /settings at any time to change configuration, set an admin password, or toggle light/dark mode.

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
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
cm8200	Arris Touchstone CM8200A	https://192.168.100.1	Username + password
hitron	Hitron CODA-56	http://192.168.100.1	No auth required
sagemcom	Sagemcom F@st 3896	http://192.168.100.1	Username + password
sb6141	Arris/Motorola SB6141	http://192.168.100.1	No auth required
sb6190	Arris SB6190	https://192.168.100.1	Username + password
cgm4981	Technicolor CGM4981COM / Cox Panoramic Gateway PM8 / XB8	http://192.168.0.1	Username + password
generic	Generic Router (no DOCSIS)	--	No auth required

| 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)

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)

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	Show gaming quality badge in dashboard
BNETZ_ENABLED	true	Show BNetzA integration in sidebar and dashboard

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
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, or Apprise sidecar delivery. Provider-specific credentials should live in Apprise where possible. See Notifications for the Apprise sidecar split, 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

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. Modem -- Modem type, URL, credentials, ISP name
2. General -- Poll interval, history retention, timezone, language, admin password
3. Notifications -- Webhook, ntfy, Discord, Gotify, Apprise sidecar, severity filtering
4. Smart Capture -- Trigger events, guardrails, execution history (details)
5. Appearance -- Theme (dark/light), gaming quality index toggle, BNetzA integration toggle
6. Security -- Admin password, session settings
7. Extensions -- Module management

Integration tabs (Backup & Restore, BNetzA File Watcher, Connection Monitor, MQTT Broker, Speedtest Tracker, BQM Graphs, Smokeping, Weather) 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

• Passwords at rest: Modem password, MQTT password, and Speedtest Tracker token are encrypted with Fernet (AES-128-CBC). The encryption key is stored in .config_key inside the data volume.
• Admin password: Hashed with scrypt (via Werkzeug). The plaintext is never stored.
• Session: 24-hour persistent session cookies (HTTPOnly, SameSite=Strict).
• 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 return raw UTC timestamps -- clients are responsible for local conversion.

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

The speedtest card on the dashboard uses color coding to show how your actual speed compares to what you're 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".