Installation

OrbitalReg ships three supported deployment shapes. Pick the one that matches how the rest of your platform is run; the underlying binary is the same in all three cases.

Helm chart (recommended)

The chart at charts/orbitalreg/ bundles the API, the SPA frontend, an optional in-cluster Postgres / Redis / MinIO, ServiceMonitors, and a ValidatingWebhookConfiguration for the Kubernetes operator (if installed alongside).

helm install orbitalreg ./charts/orbitalreg \
  --namespace orbitalreg --create-namespace \
  --values values-onprem.yaml \
  --set s3.endpoint=s3.example.com:9000 \
  --set s3.bucket=orbitalreg \
  --set s3.existingSecret=orbitalreg-s3 \
  --set saml.existingSecret=orbitalreg-saml

The bundled values-onprem.yaml enables the production-shape defaults:

• 3 API replicas, HPA on CPU
• External Postgres (the chart no longer ships its own; use CloudNativePG, RDS, or Cloud SQL)
• External Redis
• External S3-compatible bucket (MinIO, Ceph RadosGW, AWS S3, Cloudflare R2 — anything signing requests with SigV4 works)
• NGINX Ingress + cert-manager TLS
• ServiceMonitor enabled

Full chart-value reference: see Helm chart values.

Postgres on CloudNativePG

For HA Postgres with PITR + Barman-managed S3 backups, install CloudNativePG and have OrbitalReg's chart point at the cluster's read-write service. Full walkthrough lives at Postgres on CloudNativePG.

Manual install

For non-Helm clusters, the chart's rendered output is reproducible:

helm template orbitalreg ./charts/orbitalreg \
  --values values-onprem.yaml > orbitalreg.yaml
kubectl apply -f orbitalreg.yaml

The rendered manifests are vanilla Kubernetes resources — Deployment, Service, Ingress, ServiceMonitor, ConfigMap, plus Secrets that you materialise yourself.

Single-binary install

For small deployments, the API binary runs standalone behind a reverse proxy:

go build -o orbitalreg-api ./api/cmd/server
ORBITALREG_DATABASE_URL=postgres://… \
ORBITALREG_REDIS_URL=redis://… \
ORBITALREG_S3_ENDPOINT=… \
ORBITALREG_S3_BUCKET=… \
ORBITALREG_S3_ACCESS_KEY=… \
ORBITALREG_S3_SECRET_KEY=… \
./orbitalreg-api

The frontend bundle (under frontend/dist/) can be served by any static-file server; nginx, Caddy, and the API itself all work.

Full env-var reference: see Environment variables.

Air-gapped install

A fresh OrbitalReg install starts in air-gapped mode. Egress is disabled at the platform layer — webhooks, OSV.dev, Sigstore Rekor, OTel collectors, and version-check pings are all blocked until an admin opts each one in under Admin → System → Egress.

Concrete artefacts an air-gap deployment needs:

• The Helm chart, mirrored to your private chart museum / OCI registry
• The container images (orbitalreg-api, orbitalreg-frontend, optionally orbitalreg-operator), copied into your private registry
• A signed license envelope (mint with bin/orbital-license-issuer)
• A documentation tarball of this site (built from docs-site/ and served from any static file host) — see build instructions

Building the docs tarball

cd docs-site
npm ci
npm run build
tar czf orbitalreg-docs-${VERSION}.tar.gz -C .vitepress/dist .

The resulting tarball is a fully self-contained static site. Untar it behind any reverse proxy and point ORBITALREG_HELP_URL at the chosen URL so the help button in the AppShell topbar opens it.

Verify the install

After the pods report Ready:

kubectl -n orbitalreg port-forward svc/orbitalreg-api 8080:80
curl http://localhost:8080/api/public-config | jq .
curl http://localhost:8080/api/admin/version \
  -H "Authorization: Bearer $TOKEN" | jq .

The /api/admin/version response carries {version, built_at, go_version, git_commit}. If version reads dev, the binary was built without -ldflags "-X main.Version=…" — re-build through the shipped Makefile to get a real version string.

Where to go next

• Disaster recovery — backup + restore
• Observability — metrics, traces, logs
• Air-gapped operations — egress controls
• Kubernetes operator — declarative GitOps management