Skip to content
SHC Docs

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.

/usr/share/shc/apps/notes/app.yaml
name: notes
version: "1.0.0"
title: Notes
description: A Postgres that keeps notes
category: database
license:
id: PostgreSQL
vars:
password@secret!: the postgres user's password
hooks:
post_install:
- schema
/usr/share/shc/apps/notes/vars.yaml
password: P@ssw0rd
/usr/share/shc/apps/notes/compose.yaml
services:
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: 12
volumes:
pgdata:
/usr/share/shc/apps/notes/schema.job.yaml
name: schema
context: service
service: postgres
command: 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.

home01
$ shc install notes -s placed --where node=home01
installing 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'
0

The table is there and empty: the job ran after the install. Now label the deployment and limit it to learn/home.

home01
$ shc update placed --label tier=learn --where location=learn/home --plan
relocation 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 --yes
updating deployment "placed"
[placed] Healthy 1/1
✔ postgres healthy
source: /usr/share/shc/apps/notes
placed: 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=learn
STACK TENANT ENV APP STATUS NODE
placed prod prod notes running home01
$ shc status -s placed
last polled 2026-11-04 18:26:01 UTC
NODE STATE CPU% MEM% DISK% LOAD
home01 healthy 28.7 21.8 8.7 1.78
all 68 queues green
TENANT STACK ENVIRONMENT STATE SERVICES NODE LABELS
prod placed prod healthy 1/1 home01 app=notes environment=prod stack=placed tenant=prod tier=learn
TENANT STACK ENVIRONMENT REPLICA NODE STATE
prod 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.

explained, not walked: a volume never shrinks, so a walk that grew pgdata could not give the room back
$ shc update placed --storage pgdata=2Gi

Keep 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.