Skip to content
SHC Docs

A backup and an export

A backup copies a deployment’s volumes into the cluster’s backup repository, and the app says which volumes matter. Add a backup.yaml to notes on home01 and replace its app.yaml with this one, which adds two hooks.

/usr/share/shc/apps/notes/backup.yaml
include:
- pgdata
/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
pre_backup:
- stop: [postgres]
post_backup:
- start: [postgres]

include lists the volumes worth backing up. A backup copies pgdata, and a move must carry it. A volume the file doesn’t list is scratch, never backed up. See backup.yaml. pre_backup stops postgres before the backup copies the volume and post_backup starts it again, so the copy is of a database at rest (Lifecycle hooks).

shc update reads the app again, so placed takes the new files.

home01
$ shc update placed
updating deployment "placed"
[placed] Healthy 1/1
✔ postgres healthy
source: /usr/share/shc/apps/notes
placed: changed: app package apppkg-v1:9f7e48404c4daf470cf8941aa2505cca26c45cdefb8077c1ebf2ea4cd18ec700 -> apppkg-v1:2b75857dd2114aaabfac43cdb1905c03c25cfc0f45b890b0fd62aa76e61e431e read from /usr/share/shc/apps/notes
the rollout of prod/placed/prod to v1:sha256:760d7bf5b3077b4c8edc2fe6f7df54a60276c60bdf683603907d6bbc880b4743 finished

shc init made the repository’s key and sealed it in the vault, but it set no repository. Here the repository is a directory on home01’s disk. On a cluster of several nodes each node opens its own repository at that path, so a backup stays on the disk of the node that took it.

home01
$ shc config set backup.repo /var/backups/shc/repo --scope global
KEY VALUE SCOPE
backup.repo /var/backups/shc/repo global

Give placed a row to keep, back it up under the name kept and check the backup by that name.

home01
$ shc exec -s placed -S postgres -- psql -U postgres -c "insert into notes values ('kept by the backup')"
INSERT 0 1
$ shc backup create placed --name kept
[placed] Complete 3/3
✔ validate the request
✔ back up
✔ record the backup
✔ created backup "20261106T174709Z_576448b494ed0d0b" named "kept"
$ shc backup ls -s placed
ID STATUS SIZE BYTES TIMESTAMP POINT IN TIME ENCRYPTION NAME TENANT STACK ENVIRONMENT DATA SCOPE LOCATION
20261106T174709Z_576448b494ed0d0b completed 29731350 2026-11-06 17:47:27 assured restic kept prod placed prod unknown restic:/var/backups/shc/repo:33803feda92f87820c999d82d21e597b7c6892e1fd06ce01b4d67df88c596bff
$ shc backup verify kept -s placed
✔ checked backup "20261106T174709Z_576448b494ed0d0b": the snapshot is present in the repository; its sealed container's member table accounts for all 29731350 bytes the repository records; its in-repo manifest reads back and names this backup; it holds 1 data subject: pgdata, totalling 29703680 bytes; 1 declared by the deployment; 29714432 bytes total including deployment metadata
not proven: the archive's bytes were not read back, only its manifest; `--deep` reads the whole snapshot out of the repository; no restore was performed: this run did not replay the archive onto a stack, so it proves neither the restore path, which resolves the target, sets mount ownership and runs post_restore hooks, nor that the restored application starts

Now lose the row and bring it back.

home01
$ shc exec -s placed -S postgres -- psql -U postgres -c 'delete from notes'
DELETE 1
$ shc backup restore kept -s placed --yes
✔ restored backup "20261106T174709Z_576448b494ed0d0b" into stack "placed" in environment prod, 1 volume replayed; pre-restore safety backup "20261106T174735Z_cabef2ba18f1a0c0"
$ shc exec -s placed -S postgres -- psql -U postgres -tAc 'select body from notes'
kept by the backup

A mirror copies every backup repository onto a second provider, append-only, so losing one provider loses no backup. The vault names that provider under backup/copy_repo, and this cluster names none, so the run says so and copies nothing.

home01
$ shc backup mirror
backup mirror runs as operation fbe8ef34-6e09-4ced-b14a-bfc5e6120e18
✔ skipped: the vault declares no second provider, backup/copy_repo is absent

A backup brings back whole volumes. An export hands over what the app chooses, in its own format, and its jobs run against the running deployment. This exporter writes the notes table as SQL and reads it back.

/usr/share/shc/apps/notes/notes.exporter.yaml
jobs:
export:
- name: dump
context: container
image: postgres:16-alpine
environment:
PGPASSWORD: "{{ vars.password }}"
command: pg_dump -h postgres -U postgres -t notes --clean --if-exists -f /output/notes.sql
volumes:
- "@output:/output"
import:
- name: load
context: container
image: postgres:16-alpine
environment:
PGPASSWORD: "{{ vars.password }}"
command: psql -h postgres -U postgres -v ON_ERROR_STOP=1 -q -o /dev/null -f /input/notes.sql
volumes:
- "@input:/input"

The file’s name, notes, is the exporter’s name. Each job runs in a new container on the deployment’s network, where postgres is the service. @output is the directory the export packs into its artifact, and @input is that directory unpacked again for the import. See Writing an exporter.

home01
$ shc update placed
updating deployment "placed"
[placed] Healthy 1/1
✔ postgres healthy
source: /usr/share/shc/apps/notes
placed: changed: app package apppkg-v1:2b75857dd2114aaabfac43cdb1905c03c25cfc0f45b890b0fd62aa76e61e431e -> apppkg-v1:3b904b6d8a98c4e8bb1b97622f78c755846bcb7b7f1e6be673b594b3fe9362c1 read from /usr/share/shc/apps/notes
the rollout of prod/placed/prod to v1:sha256:f32e4f615236a5e945d8b62edac2158b806cddd67382fdc36022e0e82e14fdd3 finished
$ shc export notes -s placed --output-dir /var/lib/shc/import/notes
export runs as operation 8650486d-9622-4abb-ab90-686b517de758
[placed] Complete 1/1
✔ dump
✔ exported "notes" from stack "placed" to /var/lib/shc/import/notes/2311174ed444c2c3.exp
$ shc exec -s placed -S postgres -- psql -U postgres -c 'delete from notes'
DELETE 1
$ shc import notes -s placed -i /var/lib/shc/import/notes
import runs as operation a85f4537-718d-4a4c-bebe-1c8186cd2a38
[placed] Complete 1/1
✔ load
✔ imported "notes" into stack "placed"
$ shc exec -s placed -S postgres -- psql -U postgres -tAc 'select body from notes'
kept by the backup

The export went into /var/lib/shc/import, the directory an import reads from. Given a directory, the import reads the newest artifact this exporter made of placed.

Keep placed for the vapp and node-failure pages.

Read Underneath the backup before going on; it reads what this page left running.

Next: Nextcloud on Postgres.