Doctor Diagnostics

Doctor Diagnostics

DOCSight includes a local doctor command for self-hosted setup and support checks.

Use it before collecting manual environment details when DOCSight does not start, does not collect data, or a support thread asks for a safe diagnostic summary.

Docker

Run the doctor inside the DOCSight container so it sees the same /data volume, environment variables, user permissions, and SQLite files as the application:

docker exec docsight python -m app.doctor

For support threads or issue templates, use JSON output:

docker exec docsight python -m app.doctor --json > docsight-doctor.json

If your container has a different name, replace docsight with that container name.

Native Python

For non-Docker installs, run the command from the DOCSight Python environment:

python -m app.doctor
python -m app.doctor --json

If DOCSight uses a non-default data directory, pass it explicitly:

python -m app.doctor --data-dir /path/to/docsight-data

What it checks

The default command is passive and local. It checks:

• DOCSight version, Python version, platform, and Docker/native runtime mode
• data directory presence, type, permissions, and available disk space
• config.json presence and parseability
• setup/demo state and known environment overrides
• local secret-file presence and non-empty state
• SQLite database readability, PRAGMA quick_check, journal mode, and table counts
• optional integration configuration state for Speedtest Tracker, BQM, Smokeping, MQTT/Home Assistant, Apprise, and PWA Web Push

The doctor separates core installation failures from optional integration warnings so support can tell whether DOCSight itself is unhealthy or only an add-on needs configuration.

What it does not do by default

The default doctor is offline and passive. It does not contact:

• your modem or router
• DNS servers
• MQTT brokers
• webhook targets
• Apprise sidecars
• Speedtest Tracker, ThinkBroadband BQM, Smokeping, GitHub, or other third-party services

It also does not upload diagnostic data or write probe files into the live data directory.

Redaction

Doctor output is redacted by default, but still review it before posting publicly.

It avoids printing raw secrets and masks or removes common private values such as:

• passwords, API tokens, cookies, private keys, admin password hashes, and session/config key material
• full webhook and Apprise URLs
• host-like values, IP addresses, MAC addresses, serial numbers, customer/account markers, and credential-bearing URLs

If in doubt, share the JSON output privately with maintainers first or paste only the relevant check block.