feat(backup): restore at first-run setup, restore --in-place, docs lead with the UI (#5818, #5819)

#5818 "First-run setup: Restore from a backup, by upload": beside creating
the first admin, setup offers "Or restore from a backup". Only while no
user exists; the upload is checked (a newer backup or one whose key can't
open its secrets is refused and not kept), then restored with no safety
backup (nothing to keep), and Steward restarts into the backup's users.

#5819 "Docs and CI": backups.md leads with restoring from Settings →
Backups and from setup; `steward restore --in-place` does the same-schema
restore from the shell, and CI's image check now uses it with a real
pg_restore: a changed setting comes back and the audit log stays.

Also exempts errors/restoring.html from the breadcrumb guard, as with
the other whole-app error pages: it replaces every page while a restore
runs, so there is nowhere to trail back to.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

steward/auth/csrf.py

@@ -53,6 +53,7 @@ def rotate() -> None:
 UPLOAD_LIMITS: dict[str, int] = {
     "/settings/backups/check/file/": 512 * 1024 * 1024,
     "/settings/backups/restore/file/": 512 * 1024 * 1024,
+    "/setup/restore": 512 * 1024 * 1024,
 }
 
 

steward/auth/routes.py

@@ -295,6 +295,50 @@ async def setup_post():
     return redirect(url_for("dashboard.index"))
 
 
+
+@auth_bp.post("/setup/restore")
+@public_route("first-run setup's restore (refuses once a user exists)")
+async def setup_restore():
+    """Bring a new Steward up from a backup instead of an empty start (#5818):
+    only while no user exists, so there is nothing here to lose and no
+    safety backup to take. The upload's size limit is raised in
+    auth/csrf.py UPLOAD_LIMITS. The restore then runs as from Settings →
+    Backups (backup/restoring.py) and Steward restarts into the backup's
+    users."""
+    import shutil
+    from pathlib import Path
+
+    from quart import current_app
+    from steward.backup import job, restoring
+    from steward.backup.dump import BackupError
+    if await get_user_count(current_app) > 0:
+        return redirect(url_for("auth.login"))
+
+    async def refused(error: str):
+        return await render_template("auth/setup.html", default_url=request.host_url.rstrip("/"),
+                                     restore_error=error), 400
+
+    upload = (await request.files).get("file")
+    if upload is None or not upload.filename:
+        return await refused("Choose a backup file to restore.")
+    name = Path(upload.filename).name
+    held = restoring.stage()
+    await upload.save(held.path)
+    try:
+        report = await job.check_file(current_app._get_current_object(), held.path, name)
+    except BackupError as exc:
+        shutil.rmtree(held.dir, ignore_errors=True)
+        return await refused(str(exc))
+    if report.schema == "newer" or not report.ok:
+        shutil.rmtree(held.dir, ignore_errors=True)
+        return await refused("This Steward is older than the one that made the backup; update Steward, "
+                             "then restore it." if report.schema == "newer" else report.summary())
+    if not restoring.start_restore(current_app._get_current_object(), held.path, name,
+                                   username="first-run setup", replace_all=report.schema == "older",
+                                   owned_dir=held.dir, safety=False):
+        return await refused("A restore is already under way.")
+    return redirect(url_for("auth.setup"))
+
 # ── Invites (milestone 496) ──────────────────────────────────────────────────
 
 _INVITE_GONE = ("This invite link has expired, been used or been withdrawn. "

steward/backup/restoring.py

@@ -70,22 +70,24 @@ def is_restoring() -> bool:
 
 
 def start_restore(app, path: Path, name: str, *, username: str, replace_all: bool = False,
-                  owned_dir: Path | None = None) -> bool:
+                  owned_dir: Path | None = None, safety: bool = True) -> bool:
     """Start restoring `path` in the background; False if a restore is already
-    under way. `owned_dir`, when given, is removed once it is over."""
+    under way. `owned_dir`, when given, is removed once it is over. `safety`
+    False skips the safety backup: first-run setup has nothing to keep."""
     if STATE.active or STATE.restart_requested:
         return False
     STATE.active, STATE.name, STATE.by = True, name, username
     STATE.since, STATE.step, STATE.error = datetime.now(timezone.utc), "Reading the backup", ""
     task = asyncio.get_running_loop().create_task(
-        _run(app, path, name, username=username, replace_all=replace_all, owned_dir=owned_dir))
+        _run(app, path, name, username=username, replace_all=replace_all, owned_dir=owned_dir,
+             safety=safety))
     _tasks.add(task)
     task.add_done_callback(_tasks.discard)
     return True
 
 
 async def _run(app, path: Path, name: str, *, username: str, replace_all: bool,
-               owned_dir: Path | None) -> None:
+               owned_dir: Path | None, safety: bool = True) -> None:
     from steward.core.audit import log_audit
 
     from .dump import BackupError
@@ -97,8 +99,10 @@ async def _run(app, path: Path, name: str, *, username: str, replace_all: bool,
         if pinned and pinned != key:
             raise BackupError("STEWARD_SECRET_KEY is set and differs from the backup's key; "
                               "set it to the backup's key first, or its passwords and keys can't be read.")
-        STATE.step = "Saving a safety backup of Steward as it stands"
-        safety = await _safety_backup(app)
+        safety_name = ""
+        if safety:
+            STATE.step = "Saving a safety backup of Steward as it stands"
+            safety_name = await _safety_backup(app)
         STATE.step = "Restoring"
         plugin_dirs = [Path(d) for d in app.config["PLUGIN_DIRS"]]
         if replace_all:
@@ -114,7 +118,7 @@ async def _run(app, path: Path, name: str, *, username: str, replace_all: bool,
         if done.secret_key != app.config["SECRET_KEY"] and not pinned:
             _write_key(done.secret_key)
         await log_audit(app, None, username, "backup.restored", entity_type="backup",
-                        entity_id=name, detail=detail | {"safety_backup": safety})
+                        entity_id=name, detail=detail | ({"safety_backup": safety_name} if safety else {}))
         logger.warning("Restored %s (%s); restarting", name, detail["mode"])
         STATE.step = "Restored. Steward is restarting; sign in again when it is back"
         _restart_soon()

steward/cli.py

@@ -125,24 +125,37 @@ def check_backup_command(ctx: click.Context, backup_file: Path) -> None:
 @click.argument("backup_file", type=click.Path(exists=True, dir_okay=False, path_type=Path))
 @click.option("--wipe", is_flag=True, default=False,
               help="Drop everything in the database first. Without it the database must be empty.")
+@click.option("--in-place", "in_place", is_flag=True, default=False,
+              help="Replace what the backup carries in a database of the same schema, keeping "
+                   "the audit log and history (what Settings → Backups does).")
 @click.pass_context
-def restore_command(ctx: click.Context, backup_file: Path, wipe: bool) -> None:
+def restore_command(ctx: click.Context, backup_file: Path, wipe: bool, in_place: bool) -> None:
     """Bring Steward back from a backup file into its (empty) database, and
     put the backup's secret key in place. Start Steward afterwards: it runs
-    any migrations the backup is behind on."""
+    any migrations the backup is behind on. With --in-place, the database
+    keeps its history and only what the backup carries is replaced."""
     from .backup.dump import BackupError
-    from .backup.restore import restore
+    from .backup.restore import restore, restore_in_place
     from .config import _SECRET_KEY_FILE, _env, load_bootstrap
 
+    if wipe and in_place:
+        raise click.UsageError("--wipe and --in-place don't go together.")
     boot = load_bootstrap(Path(ctx.obj["config"]))
+    plugin_dirs = [Path(d) for d in boot["plugin_dirs"]]
     try:
-        done = asyncio.run(restore(backup_file, boot["database_url"], wipe=wipe,
-                                   plugin_dirs=[Path(d) for d in boot["plugin_dirs"]]))
+        if in_place:
+            done = asyncio.run(restore_in_place(backup_file, boot["database_url"], plugin_dirs=plugin_dirs))
+        else:
+            done = asyncio.run(restore(backup_file, boot["database_url"], wipe=wipe, plugin_dirs=plugin_dirs))
     except BackupError as exc:
         raise click.ClickException(str(exc)) from None
     made = done.manifest.get("created_at", "?")
     click.echo(f"Restored the backup made {made} (Steward {done.manifest.get('steward_version', '?')}).")
-    if done.fixed:
+    if in_place:
+        click.echo(f"Replaced {len(done.tables)} tables ({done.rows} rows); the audit log and history stayed.")
+        if done.fixed:
+            click.echo(f"Put right {done.fixed} rows that pointed at something the backup doesn't have.")
+    elif done.fixed:
         click.echo(f"Cleared {done.fixed} references to rows a backup leaves out (e.g. Ansible runs).")
     env_key = _env("SECRET_KEY")
     if env_key:
@@ -155,4 +168,5 @@ def restore_command(ctx: click.Context, backup_file: Path, wipe: bool) -> None:
         _SECRET_KEY_FILE.write_text(done.secret_key)
         _SECRET_KEY_FILE.chmod(0o600)
         click.echo(f"Wrote the backup's secret key to {_SECRET_KEY_FILE}.")
-    click.echo("Start Steward now; it brings the database up to date on start.")
+    click.echo("Restart Steward now so it loads them." if in_place
+               else "Start Steward now; it brings the database up to date on start.")

steward/templates/auth/setup.html

@@ -1,3 +1,5 @@
+{# auth/setup.html — first-run setup: create the first admin, or restore a
+   backup instead (#5818). Only shown while no user exists. #}
 {% extends "base.html" %}
 {% block title %}First-Run Setup — Steward{% endblock %}
 {% block content %}
@@ -32,5 +34,19 @@
             <button type="submit" class="btn">Create Admin Account</button>
         </form>
     </div>
+
+    {# Or come back from a backup (#5818): its users, settings and key. #}
+    <div class="card" style="margin-top:1.25rem;">
+        <h2 class="section-title" style="margin-bottom:0.5rem;">Or restore from a backup</h2>
+        <p class="field-hint" style="margin-bottom:1rem;">Moving Steward, or bringing it back? Upload a
+            <code>steward-&lt;time&gt;.tar</code> instead of creating an account: its users, settings, hosts,
+            monitors and key come back, and you sign in as one of its users.</p>
+        {% if restore_error %}<p class="tone-crit" style="margin-bottom:0.75rem;">{{ restore_error }}</p>{% endif %}
+        <form method="post" action="/setup/restore" enctype="multipart/form-data"
+              style="display:flex;gap:0.75rem;flex-wrap:wrap;align-items:center;">{{ csrf_field() }}
+            <input type="file" name="file" accept=".tar" required>
+            <button type="submit" class="btn btn-ghost">Restore</button>
+        </form>
+    </div>
 </div>
 {% endblock %}