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.
The three layers
Section titled “The three layers”There are three distinct concerns when bringing SHC up on a host:
- “Make this host capable of running SHC”: system packages, Docker installed, runtime libs.
- “Make SHC available as a binary on this system”: file placement, user/group, service unit.
- 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).
| Concern | Owned by (deb/rpm/apk) | Owned by (brew) | Owned by (source) |
|---|---|---|---|
| Make host capable | Depends: / Requires: / depends= | depends_on | make prepare |
| Make SHC available | Package payload | Brew Cellar | make install |
| Make host an SHC node | shc 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.
Detection signal: DESTDIR
Section titled “Detection signal: DESTDIR”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:
DESTDIRset → staging mode: place files into$DESTDIR/..., don’t install runtime deps, don’t enable services.DESTDIRunset → direct install: also pullpreparedeps 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.
What make prepare is, what it isn’t
Section titled “What make prepare is, what it isn’t”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 initowns that step. - Write
/etc/docker/daemon.json.shc initandshc node joinwrite 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.
Lifecycle moments
Section titled “Lifecycle moments”| Phase | When | Authority to mutate host? | Calls hostactivate.Activate? |
|---|---|---|---|
| Debian/RHEL/Alpine package install | Operator runs apt install shc (or dnf / apk add) | No. Depends pull runtime packages, payload places files, postinst creates user and reloads systemd | No |
make prepare | Contributor / source operator preparing runtime | Yes. Installs system packages (Docker, libs, goreleaser) | No |
make install (direct) | Source-built prod install | Yes (pulls prepare deps) | No |
make install DESTDIR=... | Manual staging into a tree | No (DESTDIR set) | No |
make package | Build .deb/.rpm/.apk via goreleaser | No (snapshot mode, build only) | No |
shc init | First-time cluster bootstrap on a host | Yes. Checks the runtime and initializes cluster state | Yes, after bootstrap |
shc node join | A node enrols | Yes | Yes, after enrol |
| daemon startup (post-init) | systemd / make dev after shc init | Subsystems reconcile local state. Host activation does not run again on this boot | No |
| daemon startup (pre-init) | First-ever daemon boot, no bootstrap.json | No. Limited mode, only serves /api/init/* | No |
make dev | Contributor running daemon from source | Yes. Auto-runs shc init --yes if no bootstrap, then starts daemon | Yes, through shc init |
| Test environment | bats / Go test fixture spins ephemeral SHC | Yes (sandboxed under SHC_BASE_DIR) | Skipped when SHC_STATE_HOME, SHC_BASE_DIR or SHC_MODE=test is set |
Host activation
Section titled “Host activation”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:
- Adds the invoking user to the
shcgroup. - 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. - Writes
/etc/sysctl.d/90-shc-inotify.confand applies it. Best-effort, and Linux only. - Writes the docker address pools into
/etc/docker/daemon.json. Best-effort. It restarts dockerd only when the node has no running containers. - Enables and starts the service.
- 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.
Listener addresses
Section titled “Listener addresses”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).
Path layout
Section titled “Path layout”See core/paths/paths.go (ce module). Three modes: dev (project-relative), root (system FHS), non-root (XDG home).
| Concern | Linux root | Dev 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 unit | systemd /usr/lib/systemd/system/shc.service | (foreground process) |
Dev domains: nip.io, never /etc/hosts
Section titled “Dev domains: nip.io, never /etc/hosts”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.4app.127.0.0.1.nip.io → 127.0.0.1This works without sudo, without DNS-cache flushes, and on every platform. Operators with real DNS supply --expose example.com to override.
Packaging: make package
Section titled “Packaging: make package”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.
Multi-platform support matrix
Section titled “Multi-platform support matrix”| Platform | Package | Init system | Status |
|---|---|---|---|
| Debian/Ubuntu | .deb | systemd | First-class |
| RHEL family (Fedora, Rocky, RHEL, CentOS Stream) | .rpm | systemd | First-class |
| Alpine | .apk | OpenRC | First-class |
| macOS | .tar.gz archive | launchd, 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 |
Deployment operations
Section titled “Deployment operations”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.