All procedures
runbookuai-explorerOperator truth

UAI Explorer Migration-Ready Runbook

Synced UAI Explorer runbook documentation from docs/runbooks/migration-ready-runbook.md.

Updated 2026-06-21·Freshness: Current·Sensitive tokens or credentials were hidden before display.

UAI Explorer Migration-Ready Runbook

Created: 2026-06-20

Status: historical pre-cutover runbook. It is retained for rollback and design lineage. Production CT 121 was cut over internally to public-safe 0.2.3 on 2026-06-21 under separate backup and cutover evidence: [REDACTED:high-entropy].md.

Purpose

Define the pre-cutover stop line for UAI Explorer public-safe work: migration-ready, not production migrated.

This runbook prepared the operator to decide on production cutover later. It does not authorize new cutovers, external exposure, storage cleanup, or raw content publication by itself.

Stop Line

Stop when:

  • Sandbox CT 126 is healthy with the enterprise public-safe build.
  • Production CT 121 is still healthy and unchanged. This was true for the 2026-06-20 migration-ready phase and is no longer the current production state.
  • QA, QC, and QoL loops have passing evidence.
  • Migration backup and rollback have been tested against sandbox.
  • Public cutover checklist is complete but not executed.

Do not:

  • Repoint DNS.
  • Add TLS routes.
  • Open firewall paths.
  • Replace production container 121.
  • Run the old production deploy script against 121.
  • Destroy or mutate production data.

Pre-Migration Evidence

Capture these before declaring migration-ready:

Invoke-WebRequest -Uri "http://10.0.0.121:8080/health" -UseBasicParsing
Invoke-WebRequest -Uri "http://10.0.0.126:8080/health" -UseBasicParsing
ssh -o BatchMode=yes -o StrictHostKeyChecking=no root@10.0.0.103 "ssh root@10.0.0.250 'pct status 121; pct status 126'"

Expected:

  • Production returns healthy.
  • Sandbox returns healthy.
  • Both containers are running.

Backup Plan

Before production cutover, create a Proxmox-level backup or snapshot of container 121.

Required record:

  • Backup method.
  • Backup file or snapshot ID.
  • Date and timezone.
  • Restore command.
  • Verification that backup completed.

No backup means no production cutover.

Sandbox Migration Rehearsal

Run the full deployment, data seed, auth bootstrap, catalog seed, and QA/QC/QoL checks on CT 126.

Required proof:

  • Admin login works.
  • Human catalog works.
  • AI context endpoint works.
  • Redaction tests pass.
  • Audit logs are created.
  • Migration readiness panel reports pass.
  • Production CT 121 remains healthy after rehearsal.

Production Cutover Checklist

This checklist is prepared now but executed later only with explicit operator approval:

  • Confirm latest production backup.
  • Confirm rollback command.
  • Confirm DNS/TLS route target.
  • Confirm public base URL.
  • Confirm admin bootstrap credential handling without writing secret values to docs.
  • Confirm health check path.
  • Confirm maintenance window if needed.
  • Confirm user seed list and tag grants.
  • Confirm smoke test accounts.

Rollback Plan

Rollback must restore the prior production service path.

Minimum rollback actions:

  • Remove or revert public route changes.
  • Restart or restore production CT 121 only if the operator approves.
  • Confirm http://10.0.0.121:8080/health returns healthy.
  • Record what changed and what was reverted.

Migration-Ready Acceptance

Mark migration-ready only when all are true:

  • docs/qa/qa-qc-qol-gates.md has passing evidence for all required checks.
  • Sandbox service passes browser and API smoke checks.
  • Production service remains healthy.
  • Backup and rollback are documented with current evidence.
  • No secrets are written to docs, logs, or prompts.
  • Operator has a clear final cutover decision packet.

Current Status

Historical migration-ready state as of 2026-06-20.

Evidence:

  • Sandbox CT 126 was healthy after the non-destructive app refresh.
  • Production CT 121 remained healthy on the legacy UAI Explorer surface at that time.
  • Local and sandbox automated QA/QC suites passed.
  • Live HTTP smoke passed.
  • Browser readiness panel showed Migration ready.
  • Readiness API kept production_cutover at not-authorized.
  • Current sandbox rollback rehearsal passed with snapshot mr022g-20260620-191542.
  • Evidence file: [REDACTED:high-entropy].md.

This stop line was superseded by the 2026-06-21 internal production cutover. The current stop line is: do not change DNS, TLS, firewall, reverse proxy, NetBird, public routes, storage cleanup, node onboarding, or raw-content publication without a separate approved runbook.

Local Hardening Note

Local build 0.2.2 added stricter public-safe refusal of legacy filesystem, raw download, and upload APIs plus context-note redaction. Later build 0.2.3 is the current public-safe production/staging version recorded in production cutover evidence.