Backup and Restore

Backup & Restore

DOCSight can create full backups of all your monitoring data and restore them on a fresh instance. This protects months of collected ISP evidence against disk failures or accidental container removal.

What Gets Backed Up

A DOCSight backup is a .tar.gz archive containing:

File	Content
docsis_history.db	The full DOCSight SQLite database, including signal history, events, speedtest data, journal entries, attachments metadata, incidents, BQM data, BNetzA measurements, weather history, API tokens, segment utilization, and internal app metadata
config.json	All settings (modem type, URLs, credentials, integrations)
.config_key	Fernet encryption key for credential decryption
.session_key	Flask session signing key
connection_monitor.db	Connection Monitor targets, latency samples, and outage history
backup_meta.json	Backup metadata (timestamp, version, table row counts)

Demo-seeded rows are filtered out for the main demo-populated monitoring tables before the archive is created. User-created data remains in the backup. The exact filtered table list is implementation-defined, so this should be treated as "demo content is reduced where supported", not as a blanket guarantee that every future is_demo=1 row in every table is removed.

Manual Backup (Download)

1. Go to Settings > Backup
2. Click Download Backup
3. Save the .tar.gz file

The backup is created in-memory and streamed to your browser. The database is copied atomically using SQLite VACUUM INTO, so the backup is always consistent even while DOCSight is actively collecting data.

Scheduled Automatic Backups

DOCSight can automatically create backups on a schedule and store them in a directory.

Setup

1. Go to Settings > Backup
2. Enable Automatic Backups
3. Click Browse to select a backup directory (default: /backup)
4. Choose an interval: Daily (every 24h) or Weekly (every 168h)
5. Set Retention: how many backup files to keep (default: 5, older ones are deleted automatically)
6. Save

Docker Volume

For scheduled backups to persist, mount a volume to /backup:

services:
  docsight:
    image: ghcr.io/itsdnns/docsight:latest
    ports:
      - "8765:8765"
    volumes:
      - docsight_data:/data
      - docsight_backup:/backup

volumes:
  docsight_data:
  docsight_backup:

Or use a host bind mount if you want direct filesystem access:

    volumes:
      - docsight_data:/data
      - /path/to/backups:/backup

Trigger Manually

Click Backup Now in the Settings backup section to immediately create a backup in the configured directory (without waiting for the next scheduled run).

Backup Files

Backups are named docsight_backup_YYYY-MM-DD_HHMMSS.tar.gz and appear in the backup list in Settings. You can delete individual backups from there.

Restore from Backup

During Setup (Fresh Instance)

When you open DOCSight for the first time (or after removing the data volume), the setup wizard offers two options:

1. New Setup -- start fresh with the configuration wizard
2. Restore from Backup -- upload a .tar.gz backup file

Choosing restore:

1. Select your backup .tar.gz file
2. DOCSight validates the archive and shows metadata (creation date, version, table row counts)
3. Click Restore
4. If the backup contains a complete configuration, DOCSight redirects to the dashboard
5. If the backup has no configuration (e.g., from demo mode), the setup wizard continues so you can configure your modem

On an Existing Instance

Restoring on an existing instance overwrites all data. To do this:

1. Stop DOCSight
2. Remove the data volume contents
3. Start DOCSight (it will show the setup wizard)
4. Choose Restore from Backup and upload your file

Backup Settings

The backup module uses these configuration keys in Settings:

Key	Default	Description
backup_enabled	false	Enable scheduled automatic backups
backup_path	/backup	Directory for scheduled backups
backup_interval_hours	24	Backup interval in hours (24 = daily, 168 = weekly)
backup_retention	5	Number of backup files to keep

These are exposed through the Settings UI in the Backup section.

How It Works

Atomic Database Copy

DOCSight uses SQLite's VACUUM INTO command to create the database copy. This produces a fully consistent snapshot of the database without requiring any locks or downtime. The copy is independent of WAL (Write-Ahead Logging) state.

Demo Data Exclusion

DOCSight removes demo-seeded rows from the current set of known demo-populated monitoring tables before the database copy is archived. This keeps demo backups smaller and avoids shipping large amounts of generated example data. User-created entries are preserved.

Forward Compatibility

Each backup includes a format_version in its metadata. When restoring a backup from a newer DOCSight version:

• DOCSight logs a warning but attempts the restore anyway
• New database tables that DOCSight doesn't know about remain harmlessly in the database
• Missing columns are added automatically on startup via schema migration

Security

• The directory browser (used for selecting the backup path) only allows navigation within /backup and /data
• Path traversal attacks are blocked via os.path.realpath() checks
• Backup filenames are sanitized with secure_filename() before deletion
• Archive members are validated against a whitelist of expected filenames

Troubleshooting

"Permission denied" when saving scheduled backups

The /backup directory must be writable by the DOCSight process (runs as appuser, UID 1000). DOCSight's entrypoint automatically adjusts ownership of /backup on startup. If you use a host bind mount, ensure the directory is writable:

chmod 777 /path/to/backups
# or
chown 1000:1000 /path/to/backups

Backup file is very small

If the backup is only a few KB, the database may be empty or contain only demo data (which is excluded). Check that DOCSight has been running and collecting real data.

"Invalid backup file" during restore

• Make sure you're uploading the .tar.gz file directly, not a renamed or re-compressed version
• The file must contain backup_meta.json with the correct magic value
• Corrupt downloads can cause this -- try downloading the backup again