Network module
Layer 9. Fabric. Fabric The module owns local bridges; modules/fabric allocates addresses.
Source: modules/network/.
Responsibilities
Section titled “Responsibilities”The network module creates and removes local bridge networks and stores
deployment host and port mappings. Its Service wraps a container-engine
executor and the cluster database. Sources: CE modules/network/service.go
and types.go.
Fabric allocation and policy belong to modules/fabric. The app renderer
joins every pinned service to the node’s fabric network shc_fabric, and
records deployment networks in networks.json; see
Network architecture.
Source layout
Section titled “Source layout”| File | Responsibility |
|---|---|
service.go | Network lifecycle and mapping storage |
interfaces.go | Network names and NIC resolution |
router.go | API registration |
tasks.go | Registered network tasks |
Compose processing
Section titled “Compose processing”The leader renders once (modules/app/install_runner.go): it normalizes
the compose document, applies SHC’s declarations, and projects it for the
node’s runtime. The node materialises that document. It does not render.
Compose deploy: keys are
translated or refused. The exact key contract is in
Compose keys.
Fabric services join shc_fabric with pinned addresses, each a routed
/32 on a link of its own. The node resolver answers service and provider
names from live state; the deployment’s stored spec records the provider
names its integrations call.
Sources: CE modules/app/fabric_render.go, deployment_networks.go and
modules/resolver/source.go.
Public access
Section titled “Public access”Services become reachable through --expose. A hostname without an
outside port requests HTTP(S); an outside port requests an L4 listener.
shc install nextcloud --expose cloud.example.comshc install postgres --expose 5432HTTP routes are Traefik file-provider entries generated from ingress
intent. The daemon’s certificate sources supply TLS material; see
TLS configuration.
Source: CE modules/app/ingress_materialize.go.
An L4 listener does not pass through Traefik. On the shc fabric a port
published without a connection is SHC’s own rule on each listening node (see
docs/proposals/2026-10-02-service-vip.md, section 4), and the rendered
compose has no ports: entry for it.
- Which nodes listen is a selector after
@:--expose 5432@(edge=true)=db,@eu/helfor a location,@(node=@(service=db))for the nodes that hold a replica. With none, the cluster’spublish.listenselector applies, and with that unset every node listens. - Where a connection goes: to a ready replica on the listening node when
there is one, which then sees the client’s address. Otherwise to the
nearest ready replica, and the replica sees the node’s fabric address.
+spreadsends each connection to any ready replica. - One port per node: a port and protocol on a node belongs to one
deployment. A second publish that wants it is refused at install and
update (
X409136PUBOVR), and so is ashc node labeledit that would create the overlap. - No TLS: direct exposure bypasses Traefik. Handle TLS in the app if needed.
A port published through a connection (@<connection>) keeps its node-port
publish on the placement node, bound to the node’s private address, which
that connection’s load balancer targets.
On the shc fabric an app’s own ports: entries publish nothing. The render
takes them out and declares their container ports under expose:, and the
install warns with X200141PUBTPL, which names the --expose that would
publish each one. The system Traefik’s own publishes are the one exception:
its 80 and 443, and its SSH entrypoint when one is set, are listen rules on
the nodes that hold a Traefik replica (node=@(service=traefik)), so every
listening node sends a connection to its own replica and Traefik sees the
client’s address. Nothing answers those ports on a node’s loopback; shcd
reaches Traefik through its service VIP.
Fabric selection
Section titled “Fabric selection”Linux Docker, Podman and Incus nodes and Mac apple nodes use the shc
fabric. A runtime that cannot attach it, Docker or Podman on a Mac, forms
without fabric and reports that posture through shc doctor. Sources: CE
modules/fabric/types.go, posture.go and network.go.