{
  "slug": "registry/operator-runbook",
  "title": "Registry operator runbook",
  "description": "Operate Cuitty Registry in local, self-hosted, and production deployments.",
  "url": "https://cuitty.com/docs/registry/operator-runbook",
  "markdown_url": "https://cuitty.com/docs/registry/operator-runbook.md",
  "json_url": "https://cuitty.com/docs/registry/operator-runbook.json",
  "frontmatter": {
    "title": "Registry operator runbook",
    "description": "Operate Cuitty Registry in local, self-hosted, and production deployments.",
    "order": 9,
    "section": "Registry",
    "updatedAt": "2026-06-09"
  },
  "headings": [
    {
      "depth": 2,
      "slug": "startup-order",
      "text": "Startup order"
    },
    {
      "depth": 2,
      "slug": "service-checks",
      "text": "Service checks"
    },
    {
      "depth": 2,
      "slug": "native-client-smoke-checks",
      "text": "Native-client smoke checks"
    },
    {
      "depth": 2,
      "slug": "cleanup-jobs",
      "text": "Cleanup jobs"
    },
    {
      "depth": 2,
      "slug": "failure-modes",
      "text": "Failure modes"
    },
    {
      "depth": 2,
      "slug": "backups",
      "text": "Backups"
    },
    {
      "depth": 2,
      "slug": "related-pages",
      "text": "Related pages"
    }
  ],
  "body_markdown": "This runbook covers standalone Cuitty Registry operation: migrations, startup order, authorization checks, native-client smoke tests, cleanup jobs, and recovery steps.\n\n## Startup order\n\n1. Start Store records, events, and blob storage.\n2. Start SpiceDB.\n3. Load the Registry authorization schema.\n4. Start the auth issuer.\n5. Run Registry migrations.\n6. Start the Registry API.\n7. Start the Registry worker or scheduler.\n8. Run protocol smoke checks.\n\n## Service checks\n\n```bash\ncurl -fsS https://registry.example.com/health\ncurl -fsS https://registry.example.com/api/v1/registry/health\n```\n\nConfirm the worker is draining outbox work:\n\n```sql\nSELECT status, count(*)\nFROM registry_outbox\nGROUP BY status\nORDER BY status;\n```\n\n## Native-client smoke checks\n\n```bash\nnpm config set @acme:registry https://registry.example.com/npm/\nnpm publish --registry https://registry.example.com/npm/\nnpm install @acme/button --registry https://registry.example.com/npm/\n```\n\n```toml\n[registries.cuitty]\nindex = \"sparse+https://registry.example.com/cargo/index/\"\n```\n\n```bash\ncargo publish --registry cuitty\ntwine upload --repository-url https://registry.example.com/pypi/ dist/*\ndocker push registry.example.com/acme/api:1.2.0\n```\n\n## Cleanup jobs\n\nRun the Registry worker for:\n\n- Expired OCI upload sessions.\n- Orphaned temporary blobs.\n- Sparse index rebuilds.\n- PyPI Simple API page regeneration.\n- npm metadata and dist-tag reconciliation.\n- Audit event export, replication, and scan scheduling.\n\n## Failure modes\n\n- SpiceDB unavailable: reject security-expanding writes, restore SpiceDB, then drain the authz outbox.\n- Store record store unavailable: fail API writes and hold protocol publishes until records are durable.\n- Store blob store unavailable: stop new uploads and reconcile metadata against stored file references before reopening publishes.\n- npm publish succeeds but the tarball is missing: compare package version records, artifact references, API logs, and blob storage.\n- Private package returns `404`: this can be correct when the caller lacks read permission.\n- OCI uploads accumulate: verify upload TTL settings and that the worker is running cleanup jobs.\n\n## Backups\n\nBack up Store records, Store events, and Store blobs together. Restoring only metadata or only blobs can produce versions whose checksums point at missing artifacts.\n\n## Related pages\n\n- [Self-hosted Registry](/docs/registry/self-hosted)\n- [Registry authorization](/docs/registry/authz)\n- [Code integration](/docs/registry/code-integration)",
  "links_out": [
    "/docs/registry/self-hosted",
    "/docs/registry/authz",
    "/docs/registry/code-integration"
  ]
}