Skip to main content
Private beta

Registry operator runbook

Operate Cuitty Registry in local, self-hosted, and production deployments.

HTML Markdown JSON

This runbook covers standalone Cuitty Registry operation: migrations, startup order, authorization checks, native-client smoke tests, cleanup jobs, and recovery steps.

Startup order

  1. Start Store records, events, and blob storage.
  2. Start SpiceDB.
  3. Load the Registry authorization schema.
  4. Start the auth issuer.
  5. Run Registry migrations.
  6. Start the Registry API.
  7. Start the Registry worker or scheduler.
  8. Run protocol smoke checks.

Service checks

curl -fsS https://registry.example.com/health
curl -fsS https://registry.example.com/api/v1/registry/health

Confirm the worker is draining outbox work:

SELECT status, count(*)
FROM registry_outbox
GROUP BY status
ORDER BY status;

Native-client smoke checks

npm config set @acme:registry https://registry.example.com/npm/
npm publish --registry https://registry.example.com/npm/
npm install @acme/button --registry https://registry.example.com/npm/
[registries.cuitty]
index = "sparse+https://registry.example.com/cargo/index/"
cargo publish --registry cuitty
twine upload --repository-url https://registry.example.com/pypi/ dist/*
docker push registry.example.com/acme/api:1.2.0

Cleanup jobs

Run the Registry worker for:

  • Expired OCI upload sessions.
  • Orphaned temporary blobs.
  • Sparse index rebuilds.
  • PyPI Simple API page regeneration.
  • npm metadata and dist-tag reconciliation.
  • Audit event export, replication, and scan scheduling.

Failure modes

  • SpiceDB unavailable: reject security-expanding writes, restore SpiceDB, then drain the authz outbox.
  • Store record store unavailable: fail API writes and hold protocol publishes until records are durable.
  • Store blob store unavailable: stop new uploads and reconcile metadata against stored file references before reopening publishes.
  • npm publish succeeds but the tarball is missing: compare package version records, artifact references, API logs, and blob storage.
  • Private package returns 404: this can be correct when the caller lacks read permission.
  • OCI uploads accumulate: verify upload TTL settings and that the worker is running cleanup jobs.

Backups

Back up Store records, Store events, and Store blobs together. Restoring only metadata or only blobs can produce versions whose checksums point at missing artifacts.