Skip to content
SHC Docs

Guide

How to install, run, and operate SHC. Audience: operators standing up SHC for their own infrastructure and deploying apps onto it.

For writing your own SHC apps, see ../app-development/. For internals, see ../architecture/. For exhaustive CLI/API/config lookup, see ../reference/.

The new line is SHC on the dev branch, in development. The operator pages:


  • Installation: install via deb, source, or dev mode
  • Quick start: first stack, first backup, first restore
  • After shc init: the four places a fresh cluster stops: package deps, an app repo, a DNS connection and an entrypoint. It also locates the deploy pipeline’s plan/apply jobs
  • Core concepts: tenant, environment, stack, deployment, node

Standing up SHC on a public cloud. Each cloud has a Terraform module + example root and a live make test/<cloud> smoke lane.

  • Cloud guides: per-cloud pages (AWS, Azure, GCP, DigitalOcean, Exoscale, OpenStack, Scaleway, Vultr) plus the shared make test/<cloud> env-var contract: one Cloudflare domain tests them all

Running pre-built SHC apps. (For authoring your own app, see ../app-development/.)

  • App catalog: index of all bundled apps grouped by category (auto-generated from apps/*/app.yaml)

Featured app guides:

  • Deployment constraints: read explain and status, including relocation requirements
  • Object storage for apps: connect a hosted provider and bind an app to its bucket
  • Multi-node cluster setup: add nodes to an existing cluster
  • Upgrading SHC: rolling upgrades, migrations, compatibility policy
  • Rolling a daemon back: undoing a roll, what the binary alone cannot undo, and the pre-flight that makes rollback possible at all
  • Refreshing app packaging: why an SHC upgrade does not touch running apps, and how to see and take app-package drift
  • Estate app refresh: August 2026: the measured pin-then-refresh pass on two live estates, and the pin grammar that actually freezes a deployment
  • The cluster entrypoint: which address dns.public_address writes into every managed DNS record, and the one topology where the default publishes somewhere unreachable
  • Private names through the node resolver: how nodes, containers and NetBird devices resolve the private zones, and the NetBird routing peer and nameserver group
  • Storage providers: local / NFS / CephFS setup
  • Block storage by default: durable volumes go on block storage when the estate has a provider, backup.yaml decides which are durable, and an existing deployment is flagged rather than switched
  • Vault & secrets: unlocking, ref+vault://, provider options
  • Enable backups: first encrypted off-box archive, which engine encrypts, verifying it is real
  • Set a backup destination: connect a bucket and set backup.repo, so backups leave the server
  • Restore onto a new cluster: back up to a bucket, delete the cluster, bring the app back on a new one
  • Disaster recovery: recovering from quorum loss, dead leaders, permanent node failure
  • Losing a site: the site holding the voters is gone: seating a survivor, moving the control-plane fence, rebuilding the voter count
  • Observability: health endpoints, logs, metrics, traces, collector setup
  • SSE dashboard and alert rules: Grafana and Prometheus assets
  • Portal secret custody: operating the Portal bench once it holds customer cloud credentials: the site-wide encryption key, why bench backup became a secret export, and the run ledger as the read audit