Installation
New line, in development. See the current runtime contract.
This page covers installing SHC on a single node. For multi-node clusters, come back after finishing here and follow Multi-node cluster setup.
Requirements
Section titled “Requirements”-
A node’s host needs systemd-resolved installed and enabled to resolve the private zones. SHC routes those zones to the node resolver on
mesh0and leaves other lookups with the host’s existing nameservers. Without systemd-resolved, including Debian images managed byresolvconf, containers still resolve private names but the host does not. SHC leaves the host’s resolver configuration unchanged.shc doctor run -c dnsreports the host and its resolver manager and tells you to install and enable systemd-resolved. -
Linux is required for the
votercapability. This page covers Linux; a Mac follows macOS. A Mac joins as a mesh0 member and raft non-voter, using userspace WireGuard on a utun. It gains thefabriccapability and shc0 chunks once its pf policy loads and its shc0 key is published (SHC-1623, SHC-1642), and takes no control-plane role. See Platform support for the capability guards and hardware verification status. -
A Linux node needs the nftables package (the
nftbinary), on every runtime. The fabric applies its policy and service VIP tables withnft, and Podman’s netavark sets up every container network with it. Some images ship without it (Scaleway’s Debian 13 does), and netavark only recommends it.shc initandshc node joinrefuse a host with nonftby name (X400387FABNFT), andshc doctor runreports it on a running cluster asfabric.engine. Install it withapt-get install nftablesordnf install nftables. -
Go 1.23+: SHC is written in Go; the build toolchain requires Go 1.23 or later.
-
Docker: either
docker-ce(default) or Podman configured in Docker-compat mode. A cluster on the shc fabric (--fabric shc) needs Docker Engine 28.0 and Compose 2.33.1 or newer on every docker node. An older docker ignoresgw_prioritywithout an error, and a container on that node then reaches nothing on another node. Debian 13’s owndocker.io(26.1.5) anddocker-compose(2.26.1) are older, and so is Ubuntu 24.04’sdocker-compose-v2(2.24.6): install Docker from Docker’s own apt repository instead. The install line (install.sh) does this on Debian and Ubuntu: when apt is about to bring Docker as the package’s dependency, it adds Docker’s repository first, so apt installsdocker-ceanddocker-compose-plugin. It writes Docker’s signing key (fingerprint9DC8 5822 9FC7 DD38 854A E2D8 8D81 803C 0EBF CD88) from its own copy and never downloads one. A machine that already reads Docker’s repository keeps its own source. One with a package Docker’s would make apt or dpkg refuse or remove (docker.io,docker-cli,docker-buildx,docker-compose,docker-compose-v2,containerd,runc,podman-docker,rootlesskit) gets no repository, and a distribution or codename Docker publishes none for gets a warning; both keep the distribution’s own Docker.shc init --fabric shcandshc node joinrefuse an older docker by name (X400386FABENG), andshc doctor runreports it on a running cluster asfabric.engine. A single node with no fabric has no such floor. Before you install Docker, write/etc/docker/daemon.jsonwith"ip-forward-no-drop": true:Terminal window sudo install -d /etc/dockerecho '{"ip-forward-no-drop": true}' | sudo tee /etc/docker/daemon.jsondockerd sets iptables’ filter FORWARD policy to drop when it turns the host’s forwarding on at its first start, and that drop takes every container’s fabric traffic: a fabric address is no docker bridge, so no rule of dockerd’s accepts it, and SHC writes no rule into iptables to get past it. With the key dockerd never sets it.
shc initandshc node joinadd the key to an existingdaemon.jsontoo, but a dockerd that already started keeps its drop until the next boot, so both refuse such a node before they deploy anything (X500396FWHDRP), naming dockerd and the fix: reboot, or runsudo iptables -P FORWARD ACCEPT, then run the command again.shc doctor runreports the same drop on a running cluster asfabric.forward-path. The cloud modules underterraform/modules/shcwrite the key before they install Docker, and so does the install line (install.sh) on a machine with no dockerd yet: it writesscripts/docker-daemon.json, the address pool and the key, before the package manager brings Docker as the package’s dependency, then runs that Docker’sdockerd --validateon it. A Docker older than 28 does not know the key and will not start with it (Debian 13’s docker.io 26.1.5 is one), so the installer removes the file, starts Docker without it and warns:shc initrefuses that engine until Docker 28 or newer replaces it. Adaemon.jsonthat is already there is left alone. A Podman node on the shc fabric must have no aardvark-dns. Podman’s own resolver asks the node’s DNS from the host, so every container would be answered every tenant’s service names. Remove the package (apt-get remove aardvark-dns) beforeshc initorshc node join: both refuse a node that has it (X400398FABAVK), and so does every later start if a package manager brings it back. It also needs podman-compose 1.5.0 or newer. One older than 1.4.0 dropsx-podman.disable_dnswithout an error and the networks it creates leave their containers without a resolver (X400396FABPDC). One older than 1.5.0 ignores--no-recreateand creates every container of a deployment again when one service changes, so an update would replace the containers it keeps (X400397FABPRC). When the node’s podman-compose is older or absent,shc initandshc node joininstall 1.5.0 from the SHC release tree, checked against its pinned SHA256 before installation. Debian 13 ships 1.3.0. Python3’s PyYAML and python-dotenv must be present; a refusal names the command to install them. Every later start still enforces the floor. Only for a node that refuses, install it manually withapt-get install -y python3-dotenv python3-yaml && curl -fsSL https://downloads.selfhostedcloud.org/shc/podman-compose/1.5.0/podman_compose.py -o /usr/local/bin/podman-compose && chmod 0755 /usr/local/bin/podman-compose. SHC reaches Podman through its API socket,podman.socket, which Debian ships turned off.shc initandshc node joinon the podman runtime enable and start it before the daemon starts, and say so. One that will not start stops them withX500687PODSCK, andshc doctorfailsnode.podman-socketwhile it is off. See private DNS. -
Incus (
--runtime incus):incusandincus-compose, which is not in the Debian archive (its upstream releases go to/usr/local/bin). Incus has to listen on the network, because the runtime pulls every image and dials each health watcher throughcore.https_address.shc initandshc node joinon the incus runtime set it to the node’sincusbr0address on port 8443 when it is unset, and leave a value you set yourself alone. A node with noincusbr0, or whose Incus does not take that value, is refused before any bootstrap step, naming the command to run (X400461INCAPI;X503462INCSCKwhen Incus does not answer on its socket). The node’s firewall then closes a listener on theincusbr0address to everything but the node itself and its health watchers: another machine that routes to that address gets no answer. A listener you put on any other address, such as an Incus cluster’s, is yours to scope and SHC adds no rule for it.A node that is a member of an Incus cluster needs nothing of the cluster’s placement. incus-compose names no member when it creates an instance, so shcd hands it a socket of its own in front of Incus’s, which names this member as the target of every instance it creates. A member whose
scheduler.instanceismanual, or a cluster with no placement scriptlet, runs SHC as it is. An instance Incus still puts on another member is refused, naming this member (X409841INCPLC). -
Clock sync:
systemd-timesyncd,chrony, orntprunning. Cluster raft is sensitive to clock skew > 500ms between nodes (see cluster-join). -
UDP port
4244reachable between nodes (mesh0 node plane). Only relevant for multi-node; single-node installs don’t need it. -
TCP port
4004reachable between nodes: the peer status port, at each node’s underlay address. A node that lost its mesh0 cache asks its peers here, over mTLS with its node certificate, beforeshc cluster repairrebuilds the cache. Multi-node only; the shc cloud terraform modules open it with the other plane ports. -
UDP port
4243reachable between nodes: the WireGuard fabric’s listener, needed only when the cluster runs--fabric shc. Scope it to the cluster’s own node addresses, never0.0.0.0/0; the hetzner terraform module does this for you whenbootstrap.fabric = "shc". -
An
shcsystem user and group for production (§2 below).
1. Install the code
Section titled “1. Install the code”Pick the install method that matches your use case.
The installer (recommended)
Section titled “The installer (recommended)”One line installs the newest release’s native package for your distro
(.deb, .rpm or .apk), refusing any package whose SHA-256 is not the one
the release’s checksums file names:
curl -fsSL https://downloads.selfhostedcloud.org/shc/install.sh | shAdd sh -s -- --dry-run to print every step without changing the machine.
The installer reads only https://downloads.selfhostedcloud.org/shc/:
RELEASE names the newest release, and the package and
shc_<ver>_checksums.txt sit under <ver>/. SHC_INSTALL_BASE points it at
a mirror of that tree instead. It refuses a release on the denied list.
1a. Native package from a checkout
Section titled “1a. Native package from a checkout”Builds .deb / .rpm / .apk via goreleaser. All formats include the
systemd unit, sysusers.d + tmpfiles.d snippets, and the bundled
rqlited raft engine. Files land in the canonical FHS locations.
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shcmake package# Debian/Ubuntu:sudo apt-get update && sudo apt-get install -y ./dist/shc_*_linux_amd64.deb# Fedora/RHEL:sudo rpm -i dist/shc_*_linux_amd64.rpm# Alpine:sudo apk add --allow-untrusted dist/shc_*_linux_amd64.apkWhich engine apt picks. Each engine clause of the package lists the Docker packages first, then
incus, thenpodman (>= 5~). apt keeps an engine that is already installed and only installs one when none is. On a node with no engine it installs Docker:docker-cewith Docker’s own apt repository configured, else the distro’sdocker.io, with its client and Compose v2. The install line configures that repository on Debian and Ubuntu. A node that already runs Incus or Podman 5 keeps it and gets no Docker, so install the engine first and SHC second. Podman older than 5 (Debian 12, Ubuntu 24.04) does not count, and apt installs Docker next to it.On Debian/Ubuntu, do not reach for
dpkg -i. On a Docker node the package hard-depends on a Docker engine, a Docker client (docker-ce-cli | docker-cli | docker.io (<< 26~)) and Compose v2, because the daemon shellsdockeranddocker composefor every stack it deploys.dpkg -iresolves none of that: it unpacks the package, defers configuration, and prints “dependency problems prevent configuration of shc”.apt-get install ./file.debresolves the dependencies directly.
apt-get updatefirst is not optional on a fresh image: with an empty package list even the usual repair fails a second time with “Unable to locate package”, which reads like a corrupt.deb. If you have already rundpkg -i, recover withsudo apt-get update && sudo apt-get install -fthensudo dpkg --configure shc.On a distro whose archive cannot satisfy the Compose v2 clause, apt refuses the install outright and names the candidates. That refusal is deliberate: a Compose v1 that cannot answer
docker composewould install clean and then deploy nothing.
1b. make install (source install)
Section titled “1b. make install (source install)”Installs the binaries, systemd unit, sysusers.d / tmpfiles.d snippets,
and apps catalog directly into the system. Useful for dev hosts that
shouldn’t go through a package. On macOS the same target installs the
binaries and the apps catalog and skips the systemd pieces; run shcd
by hand if you need the daemon locally.
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shcmake install1c. Development mode
Section titled “1c. Development mode”For hacking on SHC itself. make prepare installs the system
toolchain (Go, golangci-lint, docker, shfmt, bats, …); make dev
builds bin/shcd and runs it against ./.shc/, auto-bootstrapping a
single-node dev cluster (CA and node certificate) on first
invocation.
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shcmake prepare # one-time per machinemake dev # every session: builds and runs bin/shcdmake clean removes build outputs. It leaves ./.shc/ in place.
make purge wipes that dev state after you confirm; the next
make dev bootstraps the cluster again.
2. Initialize the cluster
Section titled “2. Initialize the cluster”The .deb ships the systemd unit and enables it (so the node
survives a reboot before init) but does not start it; the daemon
will not run until node.id and the vault password exist, and
auto-starting before that just causes a crashloop until systemd gives
up. What postinstall.sh does start is shc-watchdog (the single-writer
watchdog) and two timers, shc-estate-audit.timer and
shc-backup-repo-mirror.timer, each armed once and left alone after a
deliberate systemctl disable. shc init is the bootstrap step:
shc initInit fixes a handful of things that are awkward or impossible to change later: the serving host, the node name, the container runtime, the fabric. Init-time decisions lists all of them with what each costs to undo. If you are about to run this on something you intend to keep, read that first.
shc init writes /var/lib/shc, sets up the container runtime, and enables
the system service, so it needs root: it auto-elevates via sudo when run
as a normal user (so you type plain shc init, not sudo shc init), and the
elevation still sets $SUDO_USER for the group-membership step below.
What runs as part of init:
- Vault password prompt. Init asks for a master password
(
Set vault password:+Confirm vault password:). The password is held in memory only; it is not written to disk, so every daemon restart requires runningshc vaultto re-unlock. See vault for why we never persist the password. - Cluster CA + node certificate. The internal cluster CA and this node’s certificate for mTLS cluster-internal traffic. On a multi-node cluster, enrol also hands each joiner its mesh0 address and peers (kernel WireGuard node plane, UDP 4244).
- Fabric and the node plane. The workload network defaults to
the shc fabric. Each node takes
/26chunks of the fabric range; each of its containers is a routed/32from them on a link of its own, and reaches other nodes on shc0 (WireGuard). Nodes reach each other on mesh0, also WireGuard, on its own UDP port. rqlite is the only raft.--runtimeisdocker,podman,incusorapple(shc init --runtime). - Database bootstrap. The control-plane database is created as
a plain SQLite file; when a later node joins via
shc node join <token>, it is promoted into the rqlite raft automatically. - Group membership. If invoked via
sudo, init adds the invoking user ($SUDO_USER) to theshcgroup so they can talk to the daemon socket withoutsudo. Re-login (ornewgrp shc) is required for the new membership to take effect. - Service activation. Init runs the equivalent of
systemctl enable --now shc, then POSTs the password to/api/method/shc.vault.unlockso the daemon comes up with the vault already unlocked. System apps (postgres, keycloak, openobserve, traefik) then deploy automatically.
For non-interactive flows (cloud-init, ansible, CI):
shc init --vault-password "$VAULT_PASSWORD"# or, read from stdin:echo "$VAULT_PASSWORD" | shc init --vault-password-file -# or, read from a file:shc init --vault-password-file /etc/shc/vault.pass# or via env (this form keeps `sudo` so the variable survives the# privilege elevation: a plain `shc init` would re-exec via sudo and# drop it):sudo SHC_VAULT_PASSWORD="$VAULT_PASSWORD" shc init -yPrecedence (first match wins): --vault-password-file → --vault-password
→ SHC_VAULT_PASSWORD env → interactive prompt.
Re-running shc init on an already-initialized cluster is a no-op.
To force a clean re-init, see
cluster recovery and the
shc cluster repair command.
3. After every reboot: unlock the vault
Section titled “3. After every reboot: unlock the vault”The vault password is not persisted: every fresh boot of the
shc service starts with the vault locked, and the daemon will block
module reconciliation at wait_for_vault() until you unlock it:
shc vault # interactive prompt# or:shc vault -p "$VAULT_PASSWORD"SHC_VAULT_PASSWORD is a CLI input for shc init and shc vault.
Setting it in shcd’s environment makes the daemon refuse to start
(X400975VLTRFE). Do not put it in a systemd drop-in.
To auto-unlock at boot, give shc init the master password
(--vault-password-file). On systemd it seals the password with
systemd-creds into
/etc/systemd/system/shc.service.d/vault-autounlock.cred, to the node’s
credential host key and, where the node has a usable TPM2, to the TPM as
well. shcd opens it at boot, and no file holds the password in
plaintext. A node whose systemd is older than 250 has no
systemd-creds, so shc init plants nothing there and warns. See
vault: the sealed auto-unlock credential.
On launchd shc init writes the password to a System keychain item that
no other account can open without an administrator’s authorization, and
the plist does not set the variable.
4. Verify
Section titled “4. Verify”shc versionshc cluster status # should show one HEALTHY nodeshc cluster nodesshc repo ls # system reposCreate your first tenant. A cluster you installed yourself has only SHC’s
own master, and your first tenant is free
(Tenants):
shc tenant add demoshc ctx -t demoshc install postgres --stack dbshc status5. Remove
Section titled “5. Remove”make uninstall # keep config + datamake purge # remove everything including /var/lib/shc, /etc/shcThe make purge target will prompt before deleting stateful
directories.
Next steps
Section titled “Next steps”- Quick start: install your first real app
- macOS, standalone or as a mesh0 cluster member
- Core concepts: tenant / environment / stack / deployment
- Multi-node cluster setup: add more nodes
- File locations: where SHC puts things
- Mesh architecture: how nodes find each other