Skip to content
SHC Docs

The new line

New line, in development. These pages describe SHC as it is on the dev branch, not the released product. Anything marked “designed, not built” does not run.

The new line is SHC without Docker Swarm: a deployment’s compose document is rendered at install and update, placed by SHC’s own engine and run by its node’s runtime. This page names each feature with one sentence and links its page. The status column distinguishes code on this pin from designs that do not run.

The new line does not upgrade an old-line estate in place: a new-line shcd refuses to boot on the old line’s database (X500901OPFAIL), and the path is a fresh cluster with each app’s data brought across (upgrades).

Checked against shc next eff7d335fa, which pins ce 5f03cbef76d0, and ce next 7c95a7e91, on 2026-10-06.

Start with One app, every feature: one app directory that illustrates the built features and names the remaining gaps.

Then the tutorial, one complete app per step. All seven were run on a four-node test cluster from next on 2026-10-08, and each page shows that run’s output; steps 5 and 6 ran with an S3 server on the cluster in place of the Backblaze B2 bucket:

  1. A static site: nginx from a directory, a published port, and what SHC writes.
  2. Postgres: the Postgres that ships with SHC, shc exec, where its data and password live.
  3. Postgres across locations: a primary and two streaming standbys as a members group, installed from a repository.
  4. An app that uses Postgres through a plug: the socket makes the app its own database and user.
  5. Nextcloud on Postgres and S3: two plugs, with the bucket from a Backblaze B2 connection.
  6. Nextcloud add-ons: Calendar and Contacts as vapp instances inside the running Nextcloud.
  7. A vapp: a database inside an existing Postgres, with no containers of its own.
FeatureOne sentenceStatusPage
What SHC does to a compose fileEvery compose key is honoured, reinterpreted, dropped or refused, and one subset runs exactly as written.builtWhat SHC does to your compose file
GroupsA group scales as numbered members, each with its own services and volumes, written with the {% members %} block.Built: members are placed across nodes on install and stay there on update; install and update render on the cluster leader (an install from a path or an archive renders on its placed node); failover, moves and global joins finish the leader’s stored render (SHC-1426, SHC-1628, SHC-1616, SHC-1618).Groups
Replicas as podsServices joined by namespace sharing or volumes_from form a pod, and each replica has its own compose project.Built on a Linux node with the shc fabric and service VIPs, and on a Mac node on the apple runtime (SHC-1259, SHC-1426, SHC-1557). Any other node runs the deployment’s one compose project, with a warning (X200769PODOFF), not a refusal.Replicas and pods
RuntimesA node runs one runtime: docker through docker’s compose CLI, podman through podman-compose, incus through incus-compose, apple on macOS.built, all four linked into shcd; apple on macOS only. shc cluster init detects only docker or podman; name incus or apple with --runtimeNew-line runtime support, incus design, apple design
Node networkNodes talk over mesh0 and containers over shc0, two WireGuard tunnels (kernel on Linux, wireguard-go on a Mac), never one inside the other, and the leader signs the peer table.Built (SHC-1201, SHC-1286). mesh0 and shc0 keys rotate with shc cluster mesh rotate and on a schedule (SHC-1345, MESHROT), except a Mac’s shc0 key; relay and punching are built (SHC-1285).Network fabric, the two-tunnel design
ResourcesOne quota per service and axis becomes its limit and reservation; scope caps, disk and node capacity are separate mechanisms.built in partThe resource model on next
Labels and selectorsNode and replica labels support --where, --prefer, named node selectors and scoped constraints.Built (SHC-1355 slices 1 to 4).Labels and selectors
Published ports--expose declares HTTP routes or L4 listeners, with listen selectors and DNS for L4 hostnames.Built in part; listener-targeted load balancing is built, and a port the app declares app_protocol: proxy-v2 gets the edge’s header from its trusted sources alone (SHC-3444, SHC-3482).Published ports
CLI symbolsEach of = : @ / + ! , means one thing inside any flag value, and --expose and --scale have one spelling each.Built (SHC-1354, SHC-1353).CLI symbols
Single-writer watchdogA process outside shcd stops a node’s single-writer containers once the node’s lease has expired, so a hung shcd cannot leave two writers.built: docker, podman, incus and apple (SHC-1114, SHC-1454). It records a heartbeat, and shcd records the watchdog capability on its node row while that heartbeat is fresh, so the leader may take the node’s single writers over on the lease proof (SHC-1150).New-line runtime support
Node failoverWhen a node’s lease is lost, the leader’s failover pass re-assigns its work once a grace clock runs out.Built: stateless replicas are re-assigned and delivered after their grace, and queued jobs move after their deployment’s grace (SHC-1153). A replica with a volume moves through the dead-source move: its RWO volumes are rebound to the new node behind a lease-generation bump, each step guarded by the epoch, its generations and, until the first volume moves, the lost node’s lease (SHC-1150). A single writer moves only after the stop window, on a STONITH confirm where the volume backend’s agent covers the node, else on the lease proof from a node whose row records the watchdog. Pinned replicas, far ones without a confirm, and every move while placement is frozen wait for the node or for shc update --where. The node-loss rig run is still to come.A node failing
Daemon-only verbsshc install, shc update, shc uninstall and a rule-change relocate go through shcd; with shcd unreachable they refuse with X503738DMNREQ.Built (SHC-1328). shc uninstall refuses only when nothing answered. shc install, shc update and a relocate also report a request that connected and got no answer as X503738DMNREQ, and shcd may have acted on that one, so read shc ls before you retry.Common issues
Variables layoutEvery catalogue app’s vars.yaml uses one layout, and TestEveryCatalogueAppVariableFollowsTheLayout refuses an app that drifts.Built (SHC-1360). The test refuses the offences it lists (flat first-account keys, flat connection fields, the old backing-service field names), a subset of the page; it doesn’t check camelCase keys, for one.App variables
shc.yamlApp directories still load compose.yaml; the *.shc.yaml deployfile read by shc deploy is a separate format.An app-directory shc.yaml is designed, not built (SHC-1361).The shc.yaml design; the annotated app as shc.yaml

--no-auto-bind and --lifetime are still registered on install and update, hidden, and refused (X400808ABNGON, X400809LFTGON, commands/no_auto_bind.go). storage.autoBind.s3 and core.lifetime are retired config paths: a write is refused with X409073CFGRTD (modules/app/register.go). An unintegration job that still declares lifetime: is refused and not run (X400074UNILFT). Nothing new should depend on them (SHC-1370, SHC-1371). --ha and --no-ha are gone. A deployment is highly available when its stored spec has a group with two or more members. The drain budget reads that derived answer; the deployment row carries no HA flag (SHC-1789).