Skip to content
SHC Docs

Underneath the nginx deployment

Read this right after A compose file. Every command here reads; none changes the cluster.

shc inspect prints what SHC keeps for a deployment, one file after another, each under a banner with its name: where it placed the deployment, its variables, the compose file you wrote, the compose file SHC rendered from it and the record of the install, then a table of the deployment’s containers. That is more than a terminal shows at once: scroll back to the first banner, placement, to read it from the top.

home01
$ shc inspect web
# ============================================================
# placement
# ============================================================
node: home01
rule: engine
reason: home01 is the only node its rules, condition and capacity leave; every node it may use is full of memory or cpu by the commitment ledger; it asks for its app's own limit, which reserves nothing (SHC-2738), so it binds anyway
factors:
memory_headroom: 498, 7.6 GiB of 7.5 GiB committed
cpu_headroom: 392, 3100m of 2000m committed
deployment_count: 1000, 3 deployments, fewest 3
tenant_spread: 1000, 0 of the tenant's deployments, fewest 0
app_spread: 1000, 0 of the app's deployments, fewest 0
disk_room: 1000, docker root /var/lib/docker 66.0 GiB free of 74.8 GiB, 65.9 GiB once its 0.0 GiB lands, most left 65.9 GiB
runtime_match: 2001, a node of the deployment's runtime outranks any other
candidates:
home01:
score: 2770
factors:
memory_headroom: 498, 7.6 GiB of 7.5 GiB committed
cpu_headroom: 392, 3100m of 2000m committed
deployment_count: 1000, 3 deployments, fewest 3
tenant_spread: 1000, 0 of the tenant's deployments, fewest 0
app_spread: 1000, 0 of the app's deployments, fewest 0
disk_room: 1000, docker root /var/lib/docker 66.0 GiB free of 74.8 GiB, 65.9 GiB once its 0.0 GiB lands, most left 65.9 GiB
runtime_match: 2001, a node of the deployment's runtime outranks any other
# ============================================================
# vars.yaml
# ============================================================
{}
# ============================================================
# original/compose.yaml
# ============================================================
services:
nginx:
image: nginx:1.27-alpine
expose:
- "80"
volumes:
- ./site:/usr/share/nginx/html:ro
# ============================================================
# compose.yaml
# ============================================================
services:
nginx:
dns:
- 10.64.48.1
- 185.12.64.2
- 185.12.64.1
expose:
- "80"
image: nginx:1.27-alpine
labels:
shc.cluster: ""
shc.environment: prod
shc.job: ""
shc.mount_digest: sha256:07522ee72043ad44000ae9ea3c1a584ae381cd9d7aafd1b1c490ac7ef1a7b57c
shc.node: ""
shc.restart.defaulted: "true"
shc.restart.policy: on-failure
shc.service: nginx
shc.stack: web
shc.tenant: prod
logging:
driver: json-file
options:
max-file: "3"
max-size: 50m
restart: "no"
volumes:
- /var/lib/shc/clusterfs/packagefiles/current/prod/prod/web/pkgfiles-v1-80a0284ccc217e028b6ddcc368877b8c4b01e027a63eed4305645a54bb623815/site:/usr/share/nginx/html:ro
x-shc-restart: on-failure
# ============================================================
# stack_record.json
# ============================================================
{"app_digest":"apppkg-v1:7753cc3b9cfd1d7365d699a8c416e585449bbbf8dde5839cc4c7e2ad9d264a08","app_name":"/root/learn/nginx","compose_path":"/var/lib/shc/deployments/prod/web/prod/compose.yaml","effective_vars":"{}\n","environment":"prod","inferred_runtime":"docker","package_within_tenant":false,"ports":[{"container":80,"external":18080,"node_port":18080,"protocol":"tcp","service":"nginx"}],"project":"prod_prod_web","stack_name":"web","tenant":"prod"}
# ============================================================
# containers
# ============================================================
NODE NAME STATE IMAGE
node-08abb2345fbb prod_prod_web-nginx-r0-nginx-r0-1 running nginx:1.27-alpine

placement names the node SHC chose for web, the rule and the reason, and the score each factor gave every candidate node. home01 is the only candidate here. A label and a location shows how to steer the choice.

vars.yaml holds the values the deployment runs with. The nginx app is a compose file and a page, with no variables, so it reads {}. original/compose.yaml is the file you wrote, as SHC stored it.

compose.yaml is that file rendered, with SHC’s labels, logging and DNS added. The ./site directory became a path under clusterfs/packagefiles/current: SHC copied the app directory into the cluster’s package store at install, so the node that runs nginx reads the files from there and not from home01’s ~/learn/nginx. stack_record.json names the published port, 18080 to the service’s port 80.

The rendered compose.yaml can hold the values SHC resolves from its vault, so it lives in RAM, at /run/shc-secrets/.rendered/var/lib/shc/deployments/prod/web/prod/. compose_path names it by the deployment directory, and the directory itself keeps only rendered.sealed, the same file sealed with the node’s vault.

The files the container serves:

home01
$ shc exec -s web -S nginx -- cat /usr/share/nginx/html/index.html
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>

shc exec runs in the container on whichever node holds it, from any node.

Nothing in the compose file publishes a port. Every node holds an nftables rule that sends port 18080 to the replica’s address on SHC’s fabric network, whichever node the replica is on:

home01
$ nft list chain ip shc_vip published
table ip shc_vip {
chain published {
tcp dport 80 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.64.128.126:80 comment "master/default/traefik/traefik 80/tcp local"
tcp dport 443 counter packets 0 bytes 0 ct mark set ct mark | 0x10000000 dnat to 10.64.128.126:443 comment "master/default/traefik/traefik 443/tcp local"
tcp dport 18080 counter packets 2 bytes 120 ct mark set ct mark | 0x10000000 dnat to 10.64.128.72:80 comment "prod/prod/web/nginx 18080/tcp local"
}
}

That rule covers IPv4. For localhost over IPv6, shcd, SHC’s daemon, listens on the port itself:

home01
$ ss -ltn 'sport = :18080'
State Recv-Q Send-Q Local Address:Port Peer Address:Port
LISTEN 0 4096 [::1]:18080 [::]:*

Next: A simple Postgres.