One app, every feature
New line, in development. This describes SHC as it is on the
devbranch. The SHC behaviour below was checked against shc3c88a263038b, which pins cedb676cf4aa0b, on 2026-10-05. The example app was not run in this audit. It is not the released product. Anything marked “designed, not built” does not run.
One made-up app, notes, illustrates app file formats: variables, a routed web service, a path route, a scaled worker, a database group, volumes with their durability, secrets from the vault, healthchecks, a plug, a socket, a hook job and a backup converter. The comments are short; the table under each file says what SHC does and where in the code.
This is an annotated shape, not a complete application. Supply the Notes image and config/notes.ini, and implement its database credentials and seed command before installing it. The numbered Postgres services below have no replication or initial authentication setup; use the Postgres group tutorial for that setup.
For what SHC does to every compose key, see What SHC does to your compose file. For quotas, caps and node capacity, see the resource model.
The directory
Section titled “The directory”apps/notes/ app.yaml name, variables, hooks compose.yaml the services, a Jinja template backup.yaml what a backup captures and which volumes are kept postgres.plug.yaml notes consumes a Postgres notes.socket.yaml notes offers its API to other apps seed.job.yaml a job the post_install hook runs config/notes.ini configuration supplied by the app authorapp.yaml
Section titled “app.yaml”name: notesversion: "2.4.1"title: Notesdescription: A notes app with an APIcategory: productivity
vars: images: web@string!: web image # required: the install fails without it adminEmail@email!: first admin's address replicas: worker@int: worker count, 2 when unset postgres: hostname@string: an external Postgres, instead of a plug
hooks: post_install: - seed # runs seed.job.yaml after the services are up| Block | What SHC does | Code |
|---|---|---|
vars: | Each leaf is <name>@<type>[:<role>][!]: <description>. ! makes it required; @secret marks a secret variable; use a ref+vault:// value to resolve it from the vault. The value comes from --var key=value or vars.yaml, and the template reads it as {{ vars.images.web }}. | ce modules/app/var_types.go |
hooks: | A hook name maps to job names; each job is <name>.job.yaml beside app.yaml. Eighteen hooks: pre_ and post_ of install, update, uninstall, backup, restore, recover, move, clone and rollback. | ce modules/app/types.go HookName, hook_actions_run.go runHookJob |
compose.yaml
Section titled “compose.yaml”services: web: image: "{{ vars.images.web }}" # 1 variables render first, strict on undefined names environment: ADMIN_EMAIL: "{{ vars.adminEmail }}" DB_HOST: "{{ integrations.postgres.socket.hostname | default(vars.postgres.hostname) }}" # 2 the plug's provider DB_NAME: "{{ integrations.postgres.plug.data.database | default('notes') }}" SESSION_KEY_FILE: /run/secrets/session_key secrets: - session_key # 3 a vault secret, staged into RAM expose: - "8080" # 4 a listening port; never ports: volumes: - uploads:/srv/uploads # 5 a named volume: SHC declares and binds it; kept, see backup.yaml - ./config/notes.ini:/etc/notes.ini:ro # 6 a file shipped in the app - tmp-cache:/tmp/cache # 7 tmp*: runtime scratch, never backed up healthcheck: # 8 run by the runtime; readiness comes from it test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"] interval: 10s retries: 5 depends_on: db-1: condition: service_healthy restart: unless-stopped # 9 the node agent restarts, the runtime never deploy: resources: limits: {cpus: "1", memory: 512M} # 10 read as the service's quota x-shc-primary: true # 11 a bare --expose routes here x-shc-health: restart_after: 2m # 12 unhealthy this long: the node restarts it x-shc-scale: max: 4 # 13 a hard replica ceiling
api: image: "{{ vars.images.web }}" command: ["notes", "api"] expose: - "9090" x-shc-path: /api # 14 /api on web's hostname goes here x-shc-path-strip: true
worker: image: "{{ vars.images.web }}" command: ["notes", "worker"] volumes: - workcache:/var/cache/notes # scratch, see backup.yaml deploy: replicas: {{ vars.replicas.worker | default(2) }} # 15 interchangeable replicas; --scale overrides
{% members "db", default=3, max=5 as m %} # 16 a group: numbered members, not replicas db-{{ m.n }}: image: postgres:16.4 volumes: - pgdata-{{ m.n }}:/var/lib/postgresql/data # 17 one volume per member, declared by SHC environment: MEMBER_LOCATION: "{{ m.location }}" healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s deploy: resources: limits: {cpus: "1", memory: 1G}{% endmembers %}
secrets: session_key: x-shc-vault: ref+vault://session_key?autogen # 18 the secret's only source
x-shc-volumes: uploads: size: 20G # 19 a block volume, when the node has a provider| # | What SHC does | Code |
|---|---|---|
| 1 | The file is a Jinja2 template, rendered at each install or update before anything else; on a fresh install an undefined name is refused X400998TPLUND. | ce modules/app/install_runner.go ExecuteCompose |
| 2 | A connected plug’s provider data is integrations.<plug>.socket.<key>, and the plug’s own data integrations.<plug>.plug.data.<key>. Older pages show integrations.<plug>.<key>; the code has the two levels. | ce modules/app/integration_render.go BuildIntegrationsContext |
| 3 | The value is read from the vault into a RAM-backed file and the service mounts it at /run/secrets/session_key; the rendered compose keeps the reference, never the value. | ce modules/app/compose_secrets.go StageComposeSecrets |
| 4 | expose: declares the port. It is reachable inside the tenant and is what --expose maps. A ports: entry is rewritten to expose:, with a warning when it names a host side. | ce modules/app/swarm_vocabulary.go TranslateSwarmVocabulary, port_mappings.go |
| 5 | A named volume becomes a bind of <deployment>/mounts/uploads, or of a provisioned block volume. A durable volume on a node’s own disk pins its replica to that node. | ce modules/app/install_runner.go ResolveAndPrepVolumesWithDurability, core/placement/movability.go |
| 6 | A relative source is bound from the deployment’s copy of the app’s files. | ce core/volume/resolve.go DetectMountType |
| 7 | A tmp/temp source is bound from a per-deployment runtime directory. | ce core/volume/resolve.go |
| 8 | Compose’s own healthcheck. A service without one is ready when it runs. | ce core/executor/healthcheck |
| 9 | Rendered restart: "no"; the policy goes on labels and x-shc-restart, and the node agent applies it. | ce modules/app/restart_default.go RenderRestart |
| 10 | The quota: limit 1.5 CPU / 768M, reservation 1 CPU / 512M, charged 1 CPU / 512M. --cpu-quota web=2 overrides it. | ce modules/app/resource_quota.go ApplyResourceQuotas |
| 11 | shc install ./apps/notes --expose notes.example.com routes that hostname to web through the system Traefik. | ce modules/app/primary_ingress.go |
| 12, 13 | x-shc-* directives, linted closed: a typo is refused. | ce modules/app/extension_lint.go xshcRegistry |
| 14 | notes.example.com/api goes to api, with /api stripped before it dials. | ce modules/app/secondary_ingress.go |
| 15 | --scale worker=5 sets the count, and the quota is charged once per replica. Each replica is one compose entry <service>-r<ordinal> in its own replica project, which a node on the shc fabric with service VIPs runs (shc doctor check pods.replica-projects). | ce modules/app/deploy_overrides.go ApplyDeployOverrides, core/pod/scale.go, quota_render_charge.go |
| 16 | db-1, db-2, db-3, one member each, scaled with --scale db=5; --scale db=2@home,1@far records a location per member. On a fresh install with replica projects enabled, each member is finished for its admission-bound node (SHC-1426). Local-path apps are held to their source node; use a fetchable repository for cross-node placement. An update keeps each member on the node its live assignment row names (SHC-1628), and failover, moves and global joins finish the leader’s stored render (SHC-1616, SHC-1618, SHC-1146). Install and update still render on one node. See Groups: where members run. | ce core/jinja/members.go, core/pod/members.go |
| 17 | pgdata-1 to pgdata-3, like uploads and workcache, are declared at the top level by SHC. The app writes no top-level volumes: and no networks:: the render declares every named volume a service mounts, then removes the declaration of each data volume it turns into a bind (a tmp* scratch volume’s stays, unused), and it writes the deployment’s network itself, plus the fabric attachment on a cluster on the shc fabric. | ce modules/app/install_runner.go AutoDeclareVolumes, ResolveAndPrepVolumesWithDurability |
| 18 | file, environment or external instead is refused. | ce modules/app/compose_secrets.go stageComposeSecrets |
| 19 | Provisioned from the node’s volume provider, rounded to the provider’s sizes; on a node without one the volume stays a directory with no limit. | ce core/volume/binding.go Binding |
Command shapes, after completing the app. Use a repository source instead of ./apps/notes for the cross-location example:
shc install ./apps/notes -s notes --expose notes.example.com # HTTP: hostname[/path][=<service>[:port]]shc install ./apps/notes -s notes --expose 8443=web:8080 # L4: <port>[+udp][@conn][=<service>[:container]]shc install notes --repo examples -s notes --scale worker=5 --scale db=2@home,1@farshc install ./apps/notes -s notes -i postgres=pg # connect the postgres plug to deployment pgSlices 1 and 2 are built (SHC-1353): --expose is the one flag, a published port listens on the nodes its selector picks (@<place>, @(selector), the publish.listen default), +spread sends a connection to any ready replica, and one ledger refuses two deployments on one port of one node. An L4 hostname gets a DNS record (Published ports). Load balancers target ready listeners. A port reads a PROXY v2 header when the app declares app_protocol: proxy-v2 on it, and +proxy-protocol is no option (SHC-3444, SHC-3482). --scale has one spelling (2@home,1@far, 2/location). --no-auto-bind and --lifetime are refused (X400808ABNGON, X400809LFTGON, SHC-1370, SHC-1371).
backup.yaml
Section titled “backup.yaml”converters: uploads: # runs against the snapshot, writes an archive image: alpine:3.20 volumes: - uploads:/input:ro - "@output:/output" command: tar -czf /output/uploads.tar.gz -C /input . # a string, not a listinclude: # a backup copies these, a relocation carries them - uploads - pgdata-1 - pgdata-2 - pgdata-3 - pgdata-4 - pgdata-5# workcache isn't listed: scratch, recreated empty wherever its replica lands| Block | What SHC does | Code |
|---|---|---|
converters: | A map by name. Each converter runs its image on the snapshot; command is one string; what it writes to @output is archived, and a restore job can read it back as @uploads. A converter’s mount must be under include (X400603BKPCNV). A backup.yaml the parser refuses fails the backup rather than guess a set (modules/backup/phases.go), and install refuses it first. | ce modules/backup/types.go BackupConverter, orchestrator.go |
include: | What a backup copies, and so what a relocation carries; on local disk a listed volume holds its replica to its node. keep: would list persistent data another path protects. A volume in neither list is scratch. An app with named volumes and no backup.yaml is refused at install (X400601BKPUND). | ce modules/app/backup_list.go ParseBackupList, core/placement/durability.go Recreated |
postgres.plug.yaml
Section titled “postgres.plug.yaml”required: "{{ not vars.postgres.hostname }}" # required unless an external server is namedservices: [web] # only web consumes this providerdata: database: notes # what notes asks the provider for| Key | What SHC does | Code |
|---|---|---|
required: | A required plug left unconnected refuses the install before anything runs, X400994PLGREQ. | ce modules/app/plug_required.go |
services: | These services consume the provider. Off the shc fabric they join its network; on that fabric SHC uses fabric connectivity instead (ApplyFabricTarget). | ce modules/app/integration_render.go AttachConsumerToProviderNetworks |
data: | What the consumer sends; fields the socket’s schema.plug declares @identifier are checked at install (database here). Visible as integrations.postgres.plug.data. | ce modules/app/integration_identifiers.go, integration_render.go |
notes.socket.yaml
Section titled “notes.socket.yaml”schema: socket: url@url:endpoint!: the API's addressdata: url: "http://{{ environment }}.api.{{ stack }}:9090"Another app’s notes.plug.yaml connects with -i notes=<deployment> and reads integrations.notes.socket.url. See plugs and sockets.
seed.job.yaml
Section titled “seed.job.yaml”name: seedcontext: service # exec in a running serviceservice: webtimeout: 300command: ["notes", "seed", "--admin", "{{ vars.adminEmail }}"]| Key | What SHC does | Code |
|---|---|---|
context: | service execs in a running service; container starts a new container that runs once, of its image or, with no image, of its service’s own definition; http is also a hook context. General jobs also support graphql, pipeline and playwright, but hooks do not allow those contexts. | ce modules/app/hooks.go HookContext, modules/job |
The same app as shc.yaml (designed, not built)
Section titled “The same app as shc.yaml (designed, not built)”Designed, not built (SHC-1361). Nothing below runs. An app may be one
shc.yamlin SHC’s own strict schema instead ofcompose.yaml. When it is present the compose file is not read. Ports are listening ports only, there are nox-shc-*keys, and a key the schema does not name is an error. The key names are the ones the shc.yaml design proposes. Clay has not ruled on its open questions.
The other files (app.yaml, backup.yaml, the plug, the socket and the job) stay as they are. This is the whole compose.yaml above, written in that schema:
services: web: image: "{{ vars.images.web }}" primary: true # x-shc-primary expose: [8080] # listening ports only; there is no ports: environment: # a mapping; a KEY=value list is an error ADMIN_EMAIL: "{{ vars.adminEmail }}" DB_HOST: "{{ integrations.postgres.socket.hostname | default(vars.postgres.hostname) }}" DB_NAME: "{{ integrations.postgres.plug.data.database | default('notes') }}" SESSION_KEY_FILE: /run/secrets/session_key secrets: [session_key] volumes: - name: uploads # a named SHC volume; the render declares it path: /srv/uploads size: 20G # x-shc-volumes.uploads.size - source: ./config/notes.ini # an app file; any other host path is an error path: /etc/notes.ini read_only: true - name: tmp-cache path: /tmp/cache healthcheck: test: ["CMD", "wget", "-qO-", "http://127.0.0.1:8080/healthz"] interval: 10s retries: 5 health: restart_after: 2m # x-shc-health depends_on: db-1: condition: healthy # the record's word, not service_healthy restart: unless-stopped quota: {cpu: "1", memory: 512M} # deploy.resources.limits, read as the quota scale: {max: 4} # x-shc-scale
api: image: "{{ vars.images.web }}" command: ["notes", "api"] expose: [9090] path: /api # x-shc-path path_strip: true # x-shc-path-strip
worker: image: "{{ vars.images.web }}" command: ["notes", "worker"] replicas: {{ vars.replicas.worker | default(2) }} # deploy.replicas; --scale overrides volumes: - name: workcache path: /var/cache/notes
{% members "db", default=3, max=5 as m %} db-{{ m.n }}: image: postgres:16.4 environment: MEMBER_LOCATION: "{{ m.location }}" volumes: - name: pgdata-{{ m.n }} path: /var/lib/postgresql/data healthcheck: test: ["CMD-SHELL", "pg_isready -U postgres"] interval: 10s quota: {cpu: "1", memory: 1G}{% endmembers %}
secrets: session_key: vault: ref+vault://session_key?autogen # x-shc-vault, the secret's only sourceWhat changes from the compose form:
deploy:is gone. Its contents becomereplicas,quotaandrestart, and the label check becomeswhere.- Every
x-shc-*directive is an ordinary key. The render still writesx-shc-quotaandx-shc-restarton the stored document; the author does not. - A volume entry is a mapping with a
nameor asource, never asrc:dststring. The top-levelx-shc-volumesblock goes away, andsizesits on the mount. backup.yamlstill says which volumes are kept. Durability is not a key here.- Publishing is still the
--exposeflag. Nothing in the file publishes a port.
The design’s open questions that this app touches: whether the label check is called where; whether health.restart_after, path_strip and quota keep those spellings; whether the compose condition words (service_healthy) stay so that a converter need not rename them; and whether app files such as ./config/notes.ini belong in the volume list. See Open questions.