A port and a VIP
Start from what the app ladder’s pages 00 to 07 left running: home01 alone,
and in tenant prod the deployments web, db, pgweb, cloud, store
and placed.
A compose file published web on port 18080 with
--expose. This ladder is about what that flag does, who answers it, and
what SHC gives a service that has no published port at all.
A compose file declares the ports a service listens on. It never publishes
them. web’s nginx declares port 80 under expose:. Write a second copy
that declares it the Docker way, under ports: with a host side.
services: nginx: image: nginx:1.27-alpine ports: - "9000:80" volumes: - ./site:/usr/share/nginx/html:ro<!doctype html><title>hello again</title><p>Hello again from SHC.</p>$ shc install ~/learn/hello -s helloinstalling deployment "hello"[hello] Healthy 1/1✔ nginx healthy✔ installed deployment "hello"$ shc status -s hellolast polled 2026-10-10 18:38:04 UTCNODE STATE CPU% MEM% DISK% LOADhome01 healthy 96.4 24.7 13.6 4.16
all 53 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS NO HEALTHCHECKprod hello prod healthy 1/1 home01 app=/root/learn/hello environment=prod stack=hello tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATEprod hello prod nginx-r0 home01 ready
runs on home01; no other node to move to
1 node, 1 deploymentSHC took the host side of 9000:80 out. shc status prints no published
port for hello, and port 9000 does not answer. The rendered compose
keeps only the declaration:
$ shc inspect hello... expose: - "80"...Publish it now. --expose <outside>=<service>:<container port> is the one
flag that reaches a deployment from outside. It is on shc install and
shc update.
$ shc update hello --expose 18081=nginx:80updating deployment "hello"[hello] Healthy 1/1✔ nginx healthysource: /root/learn/hello, replayed from the deployment's persisted source (path)hello: no change: nothing was updated; the re-render read the same app package, apppkg-v1:43f6dfcef01b8b47abd0e861d65d8ce8ea79ff620881483e9f699c5360dd898c from /root/learn/hello, and produced the compose the deployment already hadRun the curl command again if the port is not answering yet.
$ curl -s http://localhost:18081/<!doctype html><title>hello again</title><p>Hello again from SHC.</p>shc status now has a Published ports section for the deployment. One
line per port: the deployment, the service, the port and protocol, the
selector that chose which nodes listen, and each listening node with what
it does with a connection, by name in name order.
$ shc status -s hellolast polled 2026-10-10 18:38:04 UTCNODE STATE CPU% MEM% DISK% LOADhome01 healthy 44.0 24.3 13.6 4.02
all 53 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS NO HEALTHCHECKprod hello prod healthy 1/1 home01 app=/root/learn/hello environment=prod stack=hello tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATEprod hello prod nginx-r0 home01 ready
Published portsprod/prod/hello nginx 18081/tcp listen=every node nodes: home01 localruns on home01; no other node to move to
1 node, 1 deploymentEvery node listens, because the port names no place; this cluster has one.
local means the node holds the replica. On a cluster of several nodes a
node that does not hold it reads crossing: it forwards the connection to
another node. Who answers a port adds a second node to see it.
A published port is the exception. Inside the cluster a service needs no
port of its own: every service gets a virtual IP, a VIP, the moment it is
installed, and the kernel of each node sends a connection to that address
to a ready replica. shc cluster fabric vips lists the VIPs this node
routes and the replica behind each.
$ shc cluster fabric vips -s webnode node-286506ff1608 revision 475 converged sha256:3e49748a434eb8b0efb99bfd80cd9634b25e8aa5b8e8716db03bb3b365055710... nginx 10.128.17.4 node-286506ff1608 readyThe line between names the VIP and the tier: here it read
prod/prod/web/nginx 10.224.0.8 local -> 10.128.17.4. 10.224.0.8 is
web’s VIP and 10.128.17.4 is the replica’s own address on the fabric.
The tier says where this node sends a new connection: local to a replica
of its own, location to one in its own location, else to any ready
replica. Another deployment of the same tenant reaches the service by
name, through the VIP, on the port its compose file declares. The name is
<service>.<deployment>.<environment>.<tenant>.shc.internal:
$ shc exec -s cloud -S nextcloud -- curl -s http://nginx.web.prod.prod.shc.internal/<!doctype html><title>hello</title><p>Hello from SHC.</p>Nextcloud reached nginx on port 80 with nothing published. Declared ports are open to the tenant; published ports are open to the outside.
From your own machine, shc forward opens a local port onto a service
of a deployment, through the cluster, for as long as the command runs.
--address is the local bind address and --environment the
deployment’s environment:
$ shc forward web nginx:80=18090 --address 127.0.0.1 --environment prodKeep web and hello installed.
Next: Who answers a port.