From e9ceaeffed8fd7823a995352a90864c978acef17 Mon Sep 17 00:00:00 2001 From: Alex Blank Date: Fri, 31 Jul 2026 18:15:58 +0200 Subject: [PATCH] docs(operators): add console workflow guide --- docs/README.md | 2 + docs/release/m18-operator-guide-evidence.md | 12 ++++ docs/runbooks/operator-console.md | 61 +++++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 docs/release/m18-operator-guide-evidence.md create mode 100644 docs/runbooks/operator-console.md diff --git a/docs/README.md b/docs/README.md index c1b0612..06a9ecc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,6 +7,7 @@ This index points operators and contributors to the authoritative v2.0 procedure ## Start here - [Project quick start](../README.md) +- [Operator console guide](runbooks/operator-console.md) - [Upgrade and rollback](runbooks/upgrade.md) - [Observability and alert response](runbooks/observability.md) - [Disaster recovery](runbooks/disaster-recovery.md) @@ -15,6 +16,7 @@ This index points operators and contributors to the authoritative v2.0 procedure | Need | Authoritative guide | | --- | --- | +| Operator console | [operator console](runbooks/operator-console.md) | | Repository lifecycle | [repositories](runbooks/repositories.md) | | Metadata protection | [metadata](runbooks/metadata.md) | | Master and repository keys | [keys](runbooks/keys.md) | diff --git a/docs/release/m18-operator-guide-evidence.md b/docs/release/m18-operator-guide-evidence.md new file mode 100644 index 0000000..f9d8813 --- /dev/null +++ b/docs/release/m18-operator-guide-evidence.md @@ -0,0 +1,12 @@ +# M18 operator guide evidence + +- Added `docs/runbooks/operator-console.md`, a task-oriented guide for first setup, + repositories, sources, jobs, executions, backups/restores, notifications, and + administration. +- Linked the guide from the documentation index without removing the existing + operator-UI-plan entry. +- Documents write-only-secret handling and CLI-only recovery/deletion boundaries. + +Verification: `make check` passed (107 unit/contract, 73 integration with one +skipped, 15 fault, and 33 security tests; lint, typecheck, and frontend build +passed). diff --git a/docs/runbooks/operator-console.md b/docs/runbooks/operator-console.md new file mode 100644 index 0000000..0dbd113 --- /dev/null +++ b/docs/runbooks/operator-console.md @@ -0,0 +1,61 @@ +# 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](../../README.md). +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](recovery-bundle.md). +- 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](ssh-sources.md). +- For delivery failures, inspect delivery attempts, then follow the + [notification runbook](notifications.md). + +For deployment health, metrics, alerts, upgrades, or recovery, use the linked +runbooks rather than treating the console as a substitute for incident +procedures.