Skip to content
SHC Docs

Network module

Layer 9. Fabric. Fabric The module owns local bridges; modules/fabric allocates addresses.

Source: modules/network/.

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.

FileResponsibility
service.goNetwork lifecycle and mapping storage
interfaces.goNetwork names and NIC resolution
router.goAPI registration
tasks.goRegistered network tasks

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.

Services become reachable through --expose. A hostname without an outside port requests HTTP(S); an outside port requests an L4 listener.

Terminal window
shc install nextcloud --expose cloud.example.com
shc install postgres --expose 5432

HTTP 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/hel for a location, @(node=@(service=db)) for the nodes that hold a replica. With none, the cluster’s publish.listen selector 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. +spread sends 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 a shc node label edit 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.

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.