Skip to content
SHC Docs

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.


  • A node’s host needs systemd-resolved installed and enabled to resolve the private zones. SHC routes those zones to the node resolver on mesh0 and leaves other lookups with the host’s existing nameservers. Without systemd-resolved, including Debian images managed by resolvconf, containers still resolve private names but the host does not. SHC leaves the host’s resolver configuration unchanged. shc doctor run -c dns reports the host and its resolver manager and tells you to install and enable systemd-resolved.

  • Linux is required for the voter capability. 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 the fabric capability 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 nft binary), on every runtime. The fabric applies its policy and service VIP tables with nft, 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 init and shc node join refuse a host with no nft by name (X400387FABNFT), and shc doctor run reports it on a running cluster as fabric.engine. Install it with apt-get install nftables or dnf 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 ignores gw_priority without an error, and a container on that node then reaches nothing on another node. Debian 13’s own docker.io (26.1.5) and docker-compose (2.26.1) are older, and so is Ubuntu 24.04’s docker-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 installs docker-ce and docker-compose-plugin. It writes Docker’s signing key (fingerprint 9DC8 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 shc and shc node join refuse an older docker by name (X400386FABENG), and shc doctor run reports it on a running cluster as fabric.engine. A single node with no fabric has no such floor. Before you install Docker, write /etc/docker/daemon.json with "ip-forward-no-drop": true:

    Terminal window
    sudo install -d /etc/docker
    echo '{"ip-forward-no-drop": true}' | sudo tee /etc/docker/daemon.json

    dockerd 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 init and shc node join add the key to an existing daemon.json too, 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 run sudo iptables -P FORWARD ACCEPT, then run the command again. shc doctor run reports the same drop on a running cluster as fabric.forward-path. The cloud modules under terraform/modules/shc write the key before they install Docker, and so does the install line (install.sh) on a machine with no dockerd yet: it writes scripts/docker-daemon.json, the address pool and the key, before the package manager brings Docker as the package’s dependency, then runs that Docker’s dockerd --validate on 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 init refuses that engine until Docker 28 or newer replaces it. A daemon.json that 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) before shc init or shc 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 drops x-podman.disable_dns without an error and the networks it creates leave their containers without a resolver (X400396FABPDC). One older than 1.5.0 ignores --no-recreate and 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 init and shc node join install 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 with apt-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 init and shc node join on the podman runtime enable and start it before the daemon starts, and say so. One that will not start stops them with X500687PODSCK, and shc doctor fails node.podman-socket while it is off. See private DNS.

  • Incus (--runtime incus): incus and incus-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 through core.https_address. shc init and shc node join on the incus runtime set it to the node’s incusbr0 address on port 8443 when it is unset, and leave a value you set yourself alone. A node with no incusbr0, or whose Incus does not take that value, is refused before any bootstrap step, naming the command to run (X400461INCAPI; X503462INCSCK when Incus does not answer on its socket). The node’s firewall then closes a listener on the incusbr0 address 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.instance is manual, 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, or ntp running. Cluster raft is sensitive to clock skew > 500ms between nodes (see cluster-join).

  • UDP port 4244 reachable between nodes (mesh0 node plane). Only relevant for multi-node; single-node installs don’t need it.

  • TCP port 4004 reachable 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, before shc cluster repair rebuilds the cache. Multi-node only; the shc cloud terraform modules open it with the other plane ports.

  • UDP port 4243 reachable between nodes: the WireGuard fabric’s listener, needed only when the cluster runs --fabric shc. Scope it to the cluster’s own node addresses, never 0.0.0.0/0; the hetzner terraform module does this for you when bootstrap.fabric = "shc".

  • An shc system user and group for production (§2 below).


Pick the install method that matches your use case.

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:

Terminal window
curl -fsSL https://downloads.selfhostedcloud.org/shc/install.sh | sh

Add 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.

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.

Terminal window
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shc
make 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.apk

Which engine apt picks. Each engine clause of the package lists the Docker packages first, then incus, then podman (>= 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-ce with Docker’s own apt repository configured, else the distro’s docker.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 shells docker and docker compose for every stack it deploys. dpkg -i resolves none of that: it unpacks the package, defers configuration, and prints “dependency problems prevent configuration of shc”. apt-get install ./file.deb resolves the dependencies directly.

apt-get update first 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 run dpkg -i, recover with sudo apt-get update && sudo apt-get install -f then sudo 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 compose would install clean and then deploy nothing.

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.

Terminal window
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shc
make install

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.

Terminal window
git clone https://github.com/bitspur/selfhosted-cloud.git shc && cd shc
make prepare # one-time per machine
make dev # every session: builds and runs bin/shcd

make 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.


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:

Terminal window
shc init

Init 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:

  1. 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 running shc vault to re-unlock. See vault for why we never persist the password.
  2. 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).
  3. Fabric and the node plane. The workload network defaults to the shc fabric. Each node takes /26 chunks of the fabric range; each of its containers is a routed /32 from 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. --runtime is docker, podman, incus or apple (shc init --runtime).
  4. 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.
  5. Group membership. If invoked via sudo, init adds the invoking user ($SUDO_USER) to the shc group so they can talk to the daemon socket without sudo. Re-login (or newgrp shc) is required for the new membership to take effect.
  6. Service activation. Init runs the equivalent of systemctl enable --now shc, then POSTs the password to /api/method/shc.vault.unlock so 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):

Terminal window
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 -y

Precedence (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.


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:

Terminal window
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.


Terminal window
shc version
shc cluster status # should show one HEALTHY node
shc cluster nodes
shc repo ls # system repos

Create your first tenant. A cluster you installed yourself has only SHC’s own master, and your first tenant is free (Tenants):

Terminal window
shc tenant add demo
shc ctx -t demo
shc install postgres --stack db
shc status

Terminal window
make uninstall # keep config + data
make purge # remove everything including /var/lib/shc, /etc/shc

The make purge target will prompt before deleting stateful directories.