A label and a location
A label describes a deployment. A location rule limits where it can run. This
page, the backup page, the vapp page and the node-failure page use an app you
write, notes: Postgres from its official image, with a job that makes its
table.
SHC finds an app by name in its catalogues and in /usr/share/shc/apps on
the node where you type. Write notes there, on home01, so the vapp page can
install parts of it by name. Create these four files.
name: notesversion: "1.0.0"title: Notesdescription: A Postgres that keeps notescategory: databaselicense: id: PostgreSQLvars: password@secret!: the postgres user's passwordhooks: post_install: - schemapassword: P@ssw0rdservices: postgres: image: postgres:16-alpine environment: POSTGRES_PASSWORD: "{{ vars.password }}" expose: - "5432" volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: ["CMD", "pg_isready", "-U", "postgres"] interval: 5s retries: 12volumes: pgdata:name: schemacontext: serviceservice: postgrescommand: psql -U postgres -c 'create table if not exists notes (body text)'app.yaml names the app and declares one variable, password: @secret
keeps its value in the vault and ! makes it required. Its hooks run the
job schema once the install is ready. See App definition
and Lifecycle hooks.
vars.yaml gives the variable its value (Variables).
compose.yaml is one service whose data lives in the named volume pgdata
(Compose keys). schema.job.yaml is the
job: context: service runs its command inside the running postgres service.
Install it by name and require home01 as its node.
$ shc install notes -s placed --where node=home01installing deployment "placed"[placed] Healthy 1/1✔ postgres healthy✔ installed deployment "placed"$ shc exec -s placed -S postgres -- psql -U postgres -tAc 'select count(*) from notes'0The table is there and empty: the job ran after the install. Now label the
deployment and limit it to learn/home.
$ shc update placed --label tier=learn --where location=learn/home --planrelocation plan for prod/placed/prod: nothing moves home01 is still inside its rules, so it stays there$ shc update placed --label tier=learn --where location=learn/home --yesupdating deployment "placed"[placed] Healthy 1/1✔ postgres healthysource: /usr/share/shc/apps/notesplaced: changed: label tier=learn; placement rule where location=learn/home stored on the deployment. The app package and the compose bytes are UNCHANGED; anything this changes in what a replica runs is on the rollout's own line$ shc ls --where tier=learnSTACK TENANT ENV APP STATUS NODEplaced prod prod notes running home01$ shc status -s placedlast polled 2026-11-04 18:26:01 UTCNODE STATE CPU% MEM% DISK% LOADhome01 healthy 28.7 21.8 8.7 1.78
all 68 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELSprod placed prod healthy 1/1 home01 app=notes environment=prod stack=placed tenant=prod tier=learn
TENANT STACK ENVIRONMENT REPLICA NODE STATEprod placed prod postgres-r0 home01 ready
runs on home01; no other node to move to
1 node, 1 deployment--plan shows what would move. --yes applies the change. home01 is the
only node in learn/home, so the database stays there. The rule starts to
matter when the cluster has a second location: the node-failure page changes
it and the database moves. The label tier=learn lets
shc ls --where tier=learn select it.
shc update --storage sizes a volume of a running deployment, as
<volume>=<size>. A block volume grows to the size. A volume never shrinks
and keeps its backend.
$ shc update placed --storage pgdata=2GiKeep placed for the backup, vapp and node-failure pages.
Read Underneath the label and the location before going on; it reads what this page left running.
Next: A backup and an export.