Skip to content
SHC Docs

Step 1: a static site

New line, in development. Installed on a four-node test cluster built from shc next b43f0c168 (ce 5db649eb) on 2026-10-08: three nodes in location home, one in far. The output below is that run’s, trimmed.

The smallest app: one nginx container serving one page. Two files and the page.

nginx/
app.yaml
compose.yaml
site/index.html
nginx/app.yaml
name: nginx
version: "1.27"
title: nginx
description: A static site served by nginx
category: development
license:
id: BSD-2-Clause
nginx/compose.yaml
services:
nginx:
image: nginx:1.27-alpine
expose:
- "80" # the port nginx listens on; nothing is published yet
volumes:
- ./site:/usr/share/nginx/html:ro
healthcheck:
test: ["CMD", "wget", "-qO-", "http://127.0.0.1/"]
interval: 10s
retries: 3
deploy:
resources:
limits:
cpus: "0.25" # this is the service's quota
memory: 64M
nginx/site/index.html
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>

On a node, from the directory’s absolute path, as deployment web in tenant rig, publishing outside port 8080 to the container’s port 80:

Terminal window
$ shc install /root/tutorial/nginx -s web -t rig --expose 8080=nginx:80
installing stack "web"
web: starting
web: running
web: nginx running
installed deployment "web"
exposure: lan
$ curl -s http://<node address>:8080/
<!-- nginx/site/index.html -->
<!doctype html>
<title>hello</title>
<p>Hello from SHC.</p>
$ shc ls -t rig
STACK TENANT ENV APP STATUS NODE
web rig prod /root/tutorial/nginx running far01

A relative path works too: the CLI resolves ./nginx (and ~) in your shell’s directory before it sends anything, and X404064SRCNFD means only that the directory isn’t on this machine (SHC-1407, ce modules/app/commands/source_body.go). The directory exists on that node only, so that node packs it into the cluster’s app archive and hands the install to the render leader, which renders the archive like any other app; placement puts the replica on any node the rules allow, and that node reads the files it binds from the same archive (SHC-1722, ce modules/app/app_archive.go). Step 3 installs from a repository instead. --expose 8080=nginx:80 publishes the container’s port 80 on outside port 8080. exposure: lan is about an HTTP hostname through Traefik, which admits only LAN addresses (ce modules/app/commands/install.go). On a cluster with service VIPs, SHC listens on the nodes selected by publish.listen, or every node when unset. It prefers a ready replica on the accepting node; +spread allows any ready replica. This publish has no connection, so SHC renders no ports: entry and the node’s 127.0.0.1:8080 does not answer (ce modules/app/port_mappings.go, core/publish, modules/vip/compile). Use a listening node’s reachable address for the curl above; in this run each of the four nodes’ addresses answered with the page, though the replica ran on far01 alone.

The deployment’s rendered compose.yaml (on the node that rendered it, the render leader, under /var/lib/shc/deployments/rig/web/prod/; the node that runs the replica holds no copy of that directory), trimmed for a cluster with service VIPs:

services:
nginx:
image: nginx:1.27-alpine
deploy:
resources:
limits: {cpus: "0.375", memory: 96M} # quota x 1.5
reservations: {cpus: "0.25", memory: 64M} # quota x 1.0
dns: [10.42.0.1, 1.1.1.1, 8.8.8.8] # the node resolver first
expose: ["80"]
labels:
shc.tenant: rig
shc.stack: web
shc.environment: prod
shc.service: nginx
shc.node: ""
shc.restart.policy: unless-stopped
shc.mount_digest: sha256:07522ee7...
logging:
driver: json-file
options: {max-file: "3", max-size: 50m}
networks:
__shc_fabric: {ipv4_address: 10.128.1.130} # a pinned address on the fabric
default:
aliases: [prod.nginx.web] # <environment>.<service>.<stack>
restart: "no" # the node agent restarts, not docker
volumes:
- /var/lib/shc/deployments/rig/web/prod/files/site:/usr/share/nginx/html:ro
x-shc-quota: {cpu: "0.25", cpu_source: limit, memory: 64M, memory_source: limit}
x-shc-restart: unless-stopped
networks:
default:
ipam:
config: [{subnet: 10.64.0.0/24, gateway: 10.64.0.1}] # SHC picks the subnet

Every line SHC added is on What SHC does to your compose file; the limit and reservation are the resource model. Beside it SHC wrote one replica project, replicas/nginx-r0/compose.yaml, with the same service as nginx-r0, dns_search: [web.prod.rig.shc.internal] and the replica’s labels (shc.ordinal: "0", shc.pod: nginx, shc.location: home, shc.spec_digest). A Linux node of a cluster on the shc fabric with service VIPs runs that replica project in place of compose.yaml; any other node runs compose.yaml. shc doctor (pods.replica-projects) says which this node does (ce modules/pods/doctor.go).

Terminal window
$ shc uninstall web -t rig -y
uninstalling stack "web"
web: uninstalling stack "web" on node far01, which holds it
web: taking the safety backup of stack "web"
web: taking stack "web" out of every node's service VIP table
web: tearing down stack "web"
web: taking down the replicas of stack "web" on node far01
web: removing the copy of stack "web" on node home01
uninstalled deployment "web"
web: removed with the deployment: config lanEnforcement

Next: Step 2: Postgres.