Skip to content
SHC Docs

Step 2: Postgres

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

SHC ships a Postgres app (Percona Distribution for PostgreSQL 16) in its shipped repository, the same package that backs the platform’s own Keycloak. shc catalog ls -t rig lists it as postgres. You write no files for this step.

Terminal window
$ shc install postgres -s pg -t rig
installing stack "pg"
pg: starting
pg: running
installed deployment "pg"
$ shc ls -t rig
STACK TENANT ENV APP STATUS NODE
pg rig prod postgres running far01

The shipped Postgres is a members group of one: its server is the service postgres-1, and shc status -s pg -t rig lists the group’s members. Step 3 builds a group by hand.

Placement chose a node (here far01); you did not. Nothing is published: Postgres is reachable inside the deployment and, through a plug, from other apps (step 4).

shc exec runs a command in a service, wherever it runs:

Terminal window
$ shc exec -s pg -t rig -S postgres-1 -- psql -U postgres -d postgres -tAc "select version()"
PostgreSQL 16.14 - Percona Distribution on x86_64-pc-linux-gnu, compiled by gcc (GCC) 14.2.1 20250110 (Red Hat 14.2.1-12), 64-bit

The app directory is /usr/lib/shc/apps/postgres on every node:

FileWhat it does
app.yaml, vars.yamlVariables. postgres.password: "ref+vault://password?autogen": SHC makes a password on first install and keeps it in the vault, scoped to the deployment.
compose.yamlA members group postgres, one service per member (postgres-1 by default, up to five with --scale postgres=N). Each member’s entrypoint refuses to start its server on a data directory of another major version.
backup.yamlHow a backup captures the data and how a restore puts it back.
postgres.socket.yamlWhat the deployment offers other apps: host, port, a database and a user, made by the socket’s integration jobs.
database.vapp.yaml and friendsThe postgres/database vapp: one database and user inside this deployment (step 7).
*.job.yamlJobs the hooks and backups run: quiesce, resume, the major-version upgrade.

Under /var/lib/shc/deployments/rig/pg/prod/ on two nodes. The node that rendered the deployment (here home01) holds its compose.yaml and one replica project per service under replicas/ (postgres-1-r0); the node that runs it (here far01) holds the data under mounts/:

# compose.yaml, trimmed
services:
postgres-1:
environment:
POSTGRES_PASSWORD: <the value> # a vault variable templated into the environment
volumes:
- /var/lib/shc/deployments/rig/pg/prod/mounts/pgdata-1:/data/db # member 1's volume pgdata-1
  • The named volume pgdata-1 is a directory under mounts/ on the node that runs member 1. No volume provider is configured on this cluster, so there is no size limit; see the resource model. It is durable, so the deployment stays on its node.
  • The password is a vault key: shc vault ls -s pg -t rig lists password at deployment scope, and shc vault get password -s pg -t rig prints it.
  • A vault variable that the template puts in environment: is rendered as its value into that compose.yaml (mode 0600, root). A compose secrets: entry with x-shc-vault is not: it is staged into RAM and the file keeps the reference (One app, every feature, line 3).

Keep pg installed for steps 4 and 7. To remove it: shc uninstall pg -t rig -y.

Next: Step 3: Postgres across locations.