backup and restore

Backup and restore

KeepPeek can create and validate a configuration bundle while recording continues. A format-3 ZIP contains exactly config.toml and plaintext secrets.toml; it contains no database or media.

For a step-by-step walkthrough, see Export and import configuration.

Open Settings → Backup and restore as an Administrator. Export ZIP downloads the two files directly. Select a Configuration ZIP, confirm replacement, and choose Apply configuration. After the upload succeeds, choose Restart to apply.

The HTTP surface is GET /config/export for download and POST /config/apply for a ZIP upload. There are no retained server backups, upload reservations, or separate dry-run requests. The old /api/backups routes are retired.

Secrets and media

The ZIP includes the complete file-backed secrets.toml in plaintext. It may contain camera passwords, access keys, MQTT credentials, webhook URLs, and notification-provider destinations. Restrict the ZIP like the live secrets file and delete copies that are no longer needed. Environment secret overrides are not copied into the bundle.

The catalog, MP4 recordings, thumbnail JPEGs, sessions, caches, audit activity, and in-memory notification/MQTT work are excluded. The target recorder retains its named volumes, placement, and metadata authority during restore. Private root references stay in configuration; the uploaded secrets must resolve them to the same target owners. Conflicting or missing references reject the apply before mutation. Finish or cancel a pending metadata handoff before importing configuration. Protect all owned volume roots with a separate archive policy when they need recovery.

What survives a restart

State	Persistence and recovery boundary
Camera settings, access credentials and grants, dashboards and selections, templates, notification rules, MQTT settings	Durable configuration in config.toml; included in a configuration ZIP.
File-backed secrets	Durable sibling secrets.toml; included in plaintext. Environment overrides remain outside the ZIP.
Recording metadata, events, coverage and maintenance intent	Recording catalog data; recover with a consistent catalog and media archive.
MP4 recordings and event images	Files in configured storage locations; not part of a configuration ZIP.
Evidence-export history and artifacts	History belongs to the metadata volume; artifacts belong to export volumes, with separate expiry; not part of the ZIP.
Diagnostic log filter	The existing sibling log-filter file persists separately and is not in the two-TOML ZIP.
Notification delivery jobs, retries, inbox/history, cooldowns and delivery counters	Runtime memory; reset on restart. Saved rule drafts and active rules remain.
MQTT pending publications, retries and deduplication history	Runtime memory; reset on restart. Stored source events are not an automatic replay queue.
Access audit, credential last-use activity and active sessions	Runtime memory; reset on restart. Durable identities and grants remain.
Browser sign-in key, media handles and active wake lock	Page/browser runtime state; reload or reconnect as required. Saved dashboard wake-lock intent remains configuration.

Restart is therefore a recording interruption and a runtime-state reset, even when every saved setting returns correctly. Collect required audit and delivery evidence before restart. A queue that was pending before shutdown is not proof of later provider delivery.

See Recording archive recovery for consistent offline copies and recovery rehearsals, and Upgrades and migrations for version changes.

Safe activation

Apply accepts a current format-3 ZIP, including its manifest comment, and validates paths, checksums, both TOMLs, permissions, and capacity before staging. It returns 202 with RESTORE_STATE_AWAITING_RESTART; this is not an immediate replacement of the live files.

Staging writes owner-only copies beside both target files. Recovery runs before configuration or databases open, and completion requires successful configuration, HTTP, and camera-worker startup. KeepPeek restores the prior pair automatically if startup health fails. A pending apply blocks a second upload from replacing it; a healthy completed restore can be superseded by the next apply. To return to an older configuration, apply a ZIP exported before the change.

Do not edit .backups/restore-journal.json or its staging files manually. The detailed HTTP, limit, crash-recovery, and CLI contract is in the backup and restore engineering guide.

Automation

The keeppeek config commands call the same Administrator-only HTTP endpoints. Commands print machine-readable JSON to stdout. Supply remote authentication only through KEEPPEEK_ACCESS_KEY; never put it in a URL or command argument.

CLI exports create a new private file before writing archive bytes. On Unix, the file mode is 0600. On Windows, a protected access list permits the current user, SYSTEM, and Administrators; the CLI verifies that protection before writing. A destination that cannot provide this protection is rejected. Existing files and Windows alternate data streams are not export destinations. Browser downloads use the browser's destination permissions; restrict those copies separately.

keeppeek config --server http://localhost:8081 export --output keeppeek-config.zip
keeppeek config --server http://localhost:8081 apply keeppeek-config.zip --confirm

Use your recorder's configured port if it differs from the default 8081. Export does not overwrite an existing file. Apply does not restart the recorder automatically; check its exit status and RESTORE_STATE_AWAITING_RESTART result before restarting. Exit code 2 means invalid CLI usage, 3 means a stable server 4xx rejection, and 4 means a transport, protocol, or server failure.

Keep --server explicit in automation: the config CLI currently uses port 3000 if it is omitted, which differs from a new recorder's default listener port.