Backup
Create, schedule, download, upload, restore and delete backups. Each backup is a tar.gz with the integrity-checked database, the password key and the session secret. The page also carries the Database maintenance card (retention, housekeeping, compaction).
On this page
Backups
Automatic database backups run nightly. They are verified before being kept — a backup that fails an integrity check is discarded rather than stored.
Configure on the Backup page (sidebar): time (default 04:00), retention
(default 14 days), folder (default /data/backups). Each backup is one
bgpvr-<date>.tar.gz holding the database plus the password-encryption
key and the admin session secret, so a restore needs nothing else. Old
bgpvr-*.db.gz files are marked DB ONLY.
Not included: recordings, VOD media, picons, generated HLS and the guide database
(epg.db). Media needs a separate filesystem backup; the guide is
re-fetched after a restore.
Restore from the Backup page. Do not swap database files by hand
unless the console is unreachable; if you must, delete the -wal and
-shm files alongside it, or SQLite replays a stale write-ahead log onto
the restored database — silent corruption.
In the console: Backup
Take a snapshot right now
Backup → "Backup now" in the Backups card header. The button shows "Backing up…", then a toast with the resulting size, and the table refreshes. Files are named bgpvr-YYYYMMDD-HHMMSS.tar.gz; older bgpvr-*.db.gz snapshots carry a DB ONLY badge. "Last backup" and its status (ok, or error: …) are shown under the header. A failed integrity check deletes the temp file and records the error instead of keeping a bad snapshot.
Set the schedule, retention and destination folder
Backup → Settings card: tick "Automatic daily backup" (on by default), set "Daily time (HH:MM)" (default 04:00), "Keep (days)" (default 14) and "Backup folder (on server)" (default /data/backups) → Save. The scheduler wakes every 60 seconds and runs once the clock has reached the target and today's backup has not run yet; a restart mid-day does not double-run.
Pull a snapshot off the box
Backup → Backups table → "Download" on the row. The file streams through your authenticated admin session into the browser. Do this before any risky upgrade — an on-box copy is worthless if the box itself dies.
Delete a snapshot
Backup → Backups table → the red trash button → confirm the browser prompt, which names the file.
Restore a backup
Download it first. Press "Restore" on the row and type RESTORE. The server stages the backup, keeps the current database as /data/backups/pre-restore-<ts>.db.gz, and restarts: all streams drop for about 20 s and you land on the login page.
Bring a dead server back
Fresh install → create the admin account → Backup → "Upload backup" (.tar.gz or .db.gz, verified on upload) → "Restore" on the uploaded row.
Keep the databases small
Backup → "Database maintenance" shows the Main database and the Guide database (epg.db) with size, write-ahead log and free space. "Retention (days, 0 = keep forever)" sets one rule per data type: guide 7, finished AI jobs 30, stream-health 30, key tests 90, watch history 90, portal device events 30, security events 30, promo telemetry 400, recording & VOD viewing history 400, recordings watch state 365, resolved tickets kept; plus one-day clean-ups of watch state and recording facts whose recording or account is gone. "Nightly housekeeping" runs them in the quiet window; "Compact files (VACUUM) when free space ≥" reclaims space when nothing is recording. Buttons: Preview / Clean now / Compact now / Save.
Watch out
- "Daily time" is only accepted if it matches exactly two digits, colon, two digits. Typing 4:00 instead of 04:00 is silently dropped by the backend while the toast still says "Settings saved" — the old time stays in force.
- The live DB runs in WAL mode. If the console is unreachable and you must swap a database file by hand, delete the old -wal/-shm files too, or SQLite replays the stale WAL onto the restored file — silent corruption.
- Retention prunes by file mtime across everything in the backup folder matching bgpvr-*.tar.gz and bgpvr-*.db.gz alike — a snapshot you deliberately kept for later is deleted once it ages past "Keep (days)".
- "Backup folder (on server)" is a container path. Point it somewhere outside a mounted volume and every snapshot vanishes when the container is rebuilt.
- A backup is config, clients, packages, channels and timer metadata plus the two secrets. Recordings, VOD files, picons and the guide database (epg.db) are not in it — restoring rewinds the database, not the media, and the guide is re-fetched.
- A legacy DB ONLY snapshot does not bring back pw_key: subscribers cannot sign in after restoring it unless the key file on the server is the same one.
- The "Off-site copy" line only shows a status when an off-box job reports to it; otherwise it reads "no report yet".
- "Lock storms" counts "database is locked" errors. Five or more in a minute sends one Telegram line and a console alert (then stays quiet for 10 minutes).
- Every backup and maintenance endpoint is admin_required, but the Backup nav item is not hidden from staff accounts. A staff user can open the page and just sees an empty table with default settings.