Skip to content
SHC Docs

One app, every feature

New line, in development. This describes SHC as it is on the dev branch. The SHC behaviour below was checked against shc 3c88a263038b, which pins ce db676cf4aa0b, 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.

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 author
name: notes
version: "2.4.1"
title: Notes
description: A notes app with an API
category: 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
BlockWhat SHC doesCode
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
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 doesCode
1The 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
2A 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
3The 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
4expose: 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
5A 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
6A relative source is bound from the deployment’s copy of the app’s files.ce core/volume/resolve.go DetectMountType
7A tmp/temp source is bound from a per-deployment runtime directory.ce core/volume/resolve.go
8Compose’s own healthcheck. A service without one is ready when it runs.ce core/executor/healthcheck
9Rendered restart: "no"; the policy goes on labels and x-shc-restart, and the node agent applies it.ce modules/app/restart_default.go RenderRestart
10The 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
11shc install ./apps/notes --expose notes.example.com routes that hostname to web through the system Traefik.ce modules/app/primary_ingress.go
12, 13x-shc-* directives, linted closed: a typo is refused.ce modules/app/extension_lint.go xshcRegistry
14notes.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
16db-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
17pgdata-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
18file, environment or external instead is refused.ce modules/app/compose_secrets.go stageComposeSecrets
19Provisioned 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:

Terminal window
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@far
shc install ./apps/notes -s notes -i postgres=pg # connect the postgres plug to deployment pg

Slices 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).

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 list
include: # 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
BlockWhat SHC doesCode
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
required: "{{ not vars.postgres.hostname }}" # required unless an external server is named
services: [web] # only web consumes this provider
data:
database: notes # what notes asks the provider for
KeyWhat SHC doesCode
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
schema:
socket:
url@url:endpoint!: the API's address
data:
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.

name: seed
context: service # exec in a running service
service: web
timeout: 300
command: ["notes", "seed", "--admin", "{{ vars.adminEmail }}"]
KeyWhat SHC doesCode
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.yaml in SHC’s own strict schema instead of compose.yaml. When it is present the compose file is not read. Ports are listening ports only, there are no x-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 source

What changes from the compose form:

  • deploy: is gone. Its contents become replicas, quota and restart, and the label check becomes where.
  • Every x-shc-* directive is an ordinary key. The render still writes x-shc-quota and x-shc-restart on the stored document; the author does not.
  • A volume entry is a mapping with a name or a source, never a src:dst string. The top-level x-shc-volumes block goes away, and size sits on the mount.
  • backup.yaml still says which volumes are kept. Durability is not a key here.
  • Publishing is still the --expose flag. 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.