Admin runbooks

Danger

ADMIN-ONLY. Procedures in this section mutate production state (catalog tables, R2 prefixes, config defaults). Each runbook lists its own prerequisites, dry-run path, and rollback. Do not run any of them without first reading the runbook end-to-end and announcing a maintenance window in #engineering-support.

These pages document one-time or rarely-run operations against the production Ursa catalog and R2 layout. They are deliberately separated from the Setup and Quickstart — those describe day-to-day researcher workflows; this section describes operations that researchers should never need to run.

• Catalog rebuild — rebuild the production catalog from R2 raw data
• Catalog maintenance — data-only backfills & fixes
• Offline ingest — manual NAS-side ingest when a rig has been offline

When to use this section

• You’re a maintainer responsible for the Ursa catalog’s integrity, and

• You have a documented reason to mutate production state at the schema or prefix level, and

• The fix can’t be done via a one-off scripts/fix_*.py script (which lives in the repo’s scripts/ directory and operates per-row).

If any of those three is false, you don’t want this section. Check Concepts for the day-to-day API, or post in #engineering-support.