Skip to content
SHC Docs

Host lifecycle: prepare, install, init, run

Layer 11. Lifecycle. Lifecycle

This document maps every entry point that touches a host to the responsibilities it owns. The goal is one concern, one owner: no duplication, no hidden state changes.

There are three distinct concerns when bringing SHC up on a host:

  1. “Make this host capable of running SHC”: system packages, Docker installed, runtime libs.
  2. “Make SHC available as a binary on this system”: file placement, user/group, service unit.
  3. Make this host an SHC node: Runtime checks and cluster bootstrap, including certificates and system apps.

These are owned by different entry points depending on whether SHC is installed via package manager (deb/rpm/apk/brew) or run from source (make dev, make install).

ConcernOwned by (deb/rpm/apk)Owned by (brew)Owned by (source)
Make host capableDepends: / Requires: / depends=depends_onmake prepare
Make SHC availablePackage payloadBrew Cellarmake install
Make host an SHC nodeshc init and shc node join call hostactivate.Activate(same)(same)

The cluster bootstrap (shc init, daemon startup post-init) is always SHC’s own code, never the package manager’s. Packages stay minimal: file placement, user creation, service unit registration. Cluster formation belongs to shc init.

make install supports DESTDIR for callers that want to stage files into a directory before packaging (e.g. downstream distro maintainers building from source). The ifdef DESTDIR gate splits the two paths:

  • DESTDIR set → staging mode: place files into $DESTDIR/..., don’t install runtime deps, don’t enable services.
  • DESTDIR unset → direct install: also pull prepare deps and start the systemd unit.

Goreleaser packaging (.deb/.rpm/.apk) does not call make install. It builds binaries directly and stages files into the package via nfpms.contents; scriptlets under scripts/ run on the end-user’s machine after install.

make prepare installs runtime system packages (Docker, system libs, the asdf toolchain), what’s needed to build and run SHC. Currently Debian/Ubuntu only (apt install docker-ce ...). Idempotent.

It does not:

  • Form a cluster; shc init owns that step.
  • Write /etc/docker/daemon.json. shc init and shc node join write the docker address pools there.
  • Create cluster certs, bootstrap files, or system apps

shc init initializes the cluster identity and runtime posture. make dev auto-runs shc init --yes on first invocation when no bootstrap.json exists, so contributors run make prepare && make dev and never need a separate “dev-cluster bootstrap” step.

PhaseWhenAuthority to mutate host?Calls hostactivate.Activate?
Debian/RHEL/Alpine package installOperator runs apt install shc (or dnf / apk add)No. Depends pull runtime packages, payload places files, postinst creates user and reloads systemdNo
make prepareContributor / source operator preparing runtimeYes. Installs system packages (Docker, libs, goreleaser)No
make install (direct)Source-built prod installYes (pulls prepare deps)No
make install DESTDIR=...Manual staging into a treeNo (DESTDIR set)No
make packageBuild .deb/.rpm/.apk via goreleaserNo (snapshot mode, build only)No
shc initFirst-time cluster bootstrap on a hostYes. Checks the runtime and initializes cluster stateYes, after bootstrap
shc node joinA node enrolsYesYes, after enrol
daemon startup (post-init)systemd / make dev after shc initSubsystems reconcile local state. Host activation does not run again on this bootNo
daemon startup (pre-init)First-ever daemon boot, no bootstrap.jsonNo. Limited mode, only serves /api/init/*No
make devContributor running daemon from sourceYes. Auto-runs shc init --yes if no bootstrap, then starts daemonYes, through shc init
Test environmentbats / Go test fixture spins ephemeral SHCYes (sandboxed under SHC_BASE_DIR)Skipped when SHC_STATE_HOME, SHC_BASE_DIR or SHC_MODE=test is set

shc init and shc node join call hostactivate.Activate after bootstrap or enrol. Sources: CE core/hostactivate, modules/cluster/activation.go and modules/cluster/commands/init.go, SHC modules/node/commands/join.go. A run that is not root skips it. So does a run that sets SHC_STATE_HOME, SHC_BASE_DIR or SHC_MODE=test.

On a root run it:

  1. Adds the invoking user to the shc group.
  2. Writes the service definition. On systemd that is the podman drop-in for shc.service. On macOS it is the LaunchDaemon plist. A failure here stops activation and does not start the service.
  3. Writes /etc/sysctl.d/90-shc-inotify.conf and applies it. Best-effort, and Linux only.
  4. Writes the docker address pools into /etc/docker/daemon.json. Best-effort. It restarts dockerd only when the node has no running containers.
  5. Enables and starts the service.
  6. On init, posts the vault master password to /api/method/shc.vault.unlock.

Cluster identity and certificate creation belong to bootstrap and enrol, before this activation.

The public API listens on port 8000 at 127.0.0.1, the container gateway and the mesh address, never a wildcard. Loopback binds at start, and the http.bind_retry loop binds the other two when they appear and rebinds them when they move. server.tcp.bind replaces the three with the one address it names, and server.tcp.enabled: false turns the listener off (CE subsystems/impl/http.go). The internal API binds internal_api.bind, default :4003. With no explicit bind and a recorded bind_ip, it binds that NIC’s current IPv4 (CE subsystems/impl/internal_api.go).

See core/paths/paths.go (ce module). Three modes: dev (project-relative), root (system FHS), non-root (XDG home).

ConcernLinux rootDev mode
Config/etc/shc<project>/.shc/config
State (database, vault, deployments)/var/lib/shc<project>/.shc/state
Cache/var/cache/shc<project>/.shc/cache
Logs/var/log/shc<project>/.shc/logs
Runtime / socket / pid/run/shc<project>/.shc/run
Service unitsystemd /usr/lib/systemd/system/shc.service(foreground process)

SHC never edits /etc/hosts. Dev/test domains use nip.io (or sslip.io) wildcard DNS:

keycloak.10.240.0.4.nip.io → 10.240.0.4
app.127.0.0.1.nip.io → 127.0.0.1

This works without sudo, without DNS-cache flushes, and on every platform. Operators with real DNS supply --expose example.com to override.

make package runs goreleaser release --snapshot --clean, which builds the pure-Go binaries (CGO_ENABLED=0) and bundles the external rqlited raft-engine binary, then produces .deb, .rpm and .apk for Linux plus a .tar.gz per macOS architecture under dist/. The macOS archives come from SEPARATE goreleaser build ids, so no darwin binary can reach the nfpm packages. Tag pushes trigger the same flow in CI without --snapshot for real releases.

PlatformPackageInit systemStatus
Debian/Ubuntu.debsystemdFirst-class
RHEL family (Fedora, Rocky, RHEL, CentOS Stream).rpmsystemdFirst-class
Alpine.apkOpenRCFirst-class
macOS.tar.gz archivelaunchd, installed by a root shc init (nothing is packaged)Artifact published and payload-verified; runtime never exercised on Mac hardware; see macOS
Windows(none)(none)Out of scope; WSL2 if requested

shc install, shc update and shc uninstall require shcd. If the daemon cannot be reached, they refuse with X503738DMNREQ before changing the deployment. Sources: CE modules/app/commands/install.go, update.go and uninstall.go.