backup-tool/docs/runbooks/operator-console.md

Operator console guide

Use the Backup Tool console for routine v2 operator work. It is served by the same Compose deployment as the API, normally at http://127.0.0.1:8080.

Before you begin

1. Start and check the deployment as described in the project quick start.
2. On a new installation, open the console and create the first administrator. Production setup should be protected with BACKUP_TOOL_BOOTSTRAP_SECRET.
3. Sign in with an active administrator account. If the session expires, the console returns to sign-in; sign in again and reopen the saved URL.

Typical backup workflow

1. Repositories — Create a repository. Choose its compression and encryption policy carefully: it is immutable after creation. Use Inspect repository to check its recorded policy.
2. Sources — Create a local source with an allowed root, or an SSH source. SSH requires a stored private-key secret, hostname, username, exact host key, and uses a forced-SFTP chroot at /. Probe the source before creating a job.
3. Jobs & schedules — Create a job with the source and repository IDs, exclusions, and backup mode. Add a cron schedule or use Run now for a one-off execution. Disable a job before changing its operational use.
4. Executions — Select an execution to watch its state. The page consumes live updates and polls while reconnecting. Only running/queued executions can be cancelled; only failed ones can be retried.
5. Backups — Verify committed backups. Review a deletion impact preview before using the CLI procedure for deletion. Test restores as dry runs first; an overwrite restore requires typing the exact destination.
6. Notifications — Create webhook or email subscriptions, choose event filters, test the selected subscription, and rotate webhook signing keys when needed. Treat signing secrets as write-only.

Administration and safety boundaries

The Administration page can store write-only secrets, create a token (copy it immediately), and change a known user's state. Do not paste secret values into issue trackers, URLs, browser storage, or logs.

Some high-risk actions deliberately remain outside the browser:

• Recovery bundle export, validation, import, passphrases, and key material use the recovery-bundle runbook.
• Backup deletion is CLI-only after its browser impact preview.
• User/token inventory and subscription state changes that require ETags are not offered until their authenticated list/header API contracts are available.

Troubleshooting

• Use the in-page retry control for transient API failures.
• A permission response means the signed-in account/token lacks the required scope; use an administrator account rather than retrying.
• For SSH probe failures, confirm the exact host key, private-key secret, forced-SFTP account, and source root with the SSH source runbook.
• For delivery failures, inspect delivery attempts, then follow the notification runbook.

For deployment health, metrics, alerts, upgrades, or recovery, use the linked runbooks rather than treating the console as a substitute for incident procedures.