ReaperCI Documentation

ReaperCI documentation

ReaperCI Operations Checklist

First boot

  1. Generate a 32-byte master key with reaperci key generate and store it outside the ReaperCI data volume.
  2. Mount that file read-only and set REAPERCI_MASTER_KEY_FILE.
  3. Set REAPERCI_EXTERNAL_URL to the HTTPS URL served by nginx.
  4. Read bootstrap-login.txt, sign in, change the dashboard password, and remove the bootstrap token file after creating a replacement PAT.

Upgrades

  • Back up the data volume and master key before upgrading.
  • Start the new binary with the old master key. Plaintext sensitive rows are migrated transactionally; startup fails if the key is missing or wrong.
  • Review builds and deployments with failure_code=hub_restarted after any restart. Inspect remote targets before requesting deployment retries.
  • Run reaperci key rotate during a maintenance window when rotating the master key.

Backups and restores

The Compose-mode scripts/backup.ps1/backup.sh and matching restore script detect a running hub, stop it, archive or restore the complete named data volume, restart it, and verify /api/healthz. The archive contains SQLite, bare repositories, registry blobs, SSH host state, and generated credentials, but never the externally mounted master key. Restore the matching key before starting the hub. Use -HostDirectory (PowerShell) or REAPERCI_BACKUP_HOST_DIRECTORY=1 (shell) only for non-Compose local data.

Registry garbage collection

Run the embedded distribution mark-and-sweep collector while the hub is stopped. Start with:

reaperci registry gc --root <data>/registry --dry-run

Review the report, then repeat without --dry-run only after confirming that no uploads or deploy pulls are active.

Release gates

  • go test ./...
  • go vet ./...
  • internal/githost coverage at or above 60%
  • pnpm --dir web check
  • pnpm --dir web test -- --run
  • bash scripts/generate-openapi.sh followed by a clean-tree check
  • backup/restore smoke
  • Docker image build
  • Playwright browser smoke suite

Gitea Actions publishes tagged multi-architecture images only when the repository variable REAPERCI_IMAGE, registry host variable, and registry credentials are configured.