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
Section titled “The new line”The new line is SHC on the dev branch, in development. The operator pages:
- The new line: every feature, marked built or not, with its page
- Labels and selectors: node labels,
--whereand--prefer, named node selectors and constraints - Published ports:
--expose, listening nodes and L4 DNS - CLI symbols: what the characters in a flag value mean, and
--exposeand--scale - New-line runtime support: docker, podman, incus and apple, and the single-writer watchdog
- The resource model on next: quotas, scope caps, disk and node capacity
- Coming from Kubernetes: each Kubernetes object and kubectl command written the SHC way, and what SHC does not do
Getting started
Section titled “Getting started”- 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
Clouds
Section titled “Clouds”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:
- Keycloak
- PostgreSQL
- Traefik
- OpenObserve
- Huly: including migrating an existing install off its bundled CockroachDB and MinIO
- Jellyfin: including the one-way 10.10 → 10.11 library migration, its backup gate, and the rehearsed rollback
Operations
Section titled “Operations”- 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_addresswrites 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.yamldecides 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 backupbecame a secret export, and the run ledger as the read audit
Troubleshooting
Section titled “Troubleshooting”- Troubleshooting index: symptom-first routing
- Common issues: install/integration/backup/cluster/vault failure walkthroughs
- SSE streaming issues
shc@docs:~$