Skip to content
SHC Docs

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.

~/learn/hello/compose.yaml
services:
nginx:
image: nginx:1.27-alpine
ports:
- "9000:80"
volumes:
- ./site:/usr/share/nginx/html:ro
~/learn/hello/site/index.html
<!doctype html>
<title>hello again</title>
<p>Hello again from SHC.</p>
home01
$ shc install ~/learn/hello -s hello
installing deployment "hello"
[hello] Healthy 1/1
✔ nginx healthy
✔ installed deployment "hello"
$ shc status -s hello
last polled 2026-10-10 18:38:04 UTC
NODE STATE CPU% MEM% DISK% LOAD
home01 healthy 96.4 24.7 13.6 4.16
all 53 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS NO HEALTHCHECK
prod hello prod healthy 1/1 home01 app=/root/learn/hello environment=prod stack=hello tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATE
prod hello prod nginx-r0 home01 ready
runs on home01; no other node to move to
1 node, 1 deployment

SHC 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:

home01
$ 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.

home01
$ shc update hello --expose 18081=nginx:80
updating deployment "hello"
[hello] Healthy 1/1
✔ nginx healthy
source: /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 had

Run the curl command again if the port is not answering yet.

home01
$ 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.

home01
$ shc status -s hello
last polled 2026-10-10 18:38:04 UTC
NODE STATE CPU% MEM% DISK% LOAD
home01 healthy 44.0 24.3 13.6 4.02
all 53 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS NO HEALTHCHECK
prod hello prod healthy 1/1 home01 app=/root/learn/hello environment=prod stack=hello tenant=prod 1
TENANT STACK ENVIRONMENT REPLICA NODE STATE
prod hello prod nginx-r0 home01 ready
Published ports
prod/prod/hello nginx 18081/tcp listen=every node nodes: home01 local
runs on home01; no other node to move to
1 node, 1 deployment

Every 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.

home01
$ shc cluster fabric vips -s web
node node-286506ff1608 revision 475 converged sha256:3e49748a434eb8b0efb99bfd80cd9634b25e8aa5b8e8716db03bb3b365055710
...
nginx 10.128.17.4 node-286506ff1608 ready

The 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:

home01
$ 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:

explained, not walked: it holds the forward open until you stop it, and a walk runs every command to its exit
$ shc forward web nginx:80=18090 --address 127.0.0.1 --environment prod

Keep web and hello installed.

Next: Who answers a port.