Repositories
A cluster has two kinds of repository. An app repository is a catalogue of apps to install by name; a backup repository is where backups go. This page sets up both.
App repositories
Section titled “App repositories”SHC ships one app repository, and shc init registered the public
catalogue beside it as shc. Give the catalogue a sync interval.
$ shc repo lsNAME URL APP COUNT PRIORITY TENANT ID ENVIRONMENT SYNCED ATshc https://selfhostedcloud.org/apps/0.1/index.yaml 585 50 system 2 system 2026-10-11T09:24:31.354027674Zshipped shipped://apps 1 10 system 1 system 2026-10-11T09:23:57.506198032Z$ shc repo update shc --sync-interval 24h✔ updated repository "shc"$ shc repo lsNAME URL APP COUNT PRIORITY TENANT ID ENVIRONMENT SYNCED AT SYNC INTERVALshc https://selfhostedcloud.org/apps/0.1/index.yaml 585 50 system 2 system 2026-10-11T09:24:31.354027674Z 24hshipped shipped://apps 1 10 system 1 system 2026-10-11T09:23:57.506198032Z -A repository is synced when it is added and then on its interval. Sync it now, read what it holds in detail, and change its priority and interval. The lower the priority number, the earlier the repository is searched when two offer an app of the same name.
$ shc repo sync shc --force...$ shc repo ls -v...$ shc repo update shc --priority 40 --sync-interval 12h✔ updated repository "shc"$ shc repo ls --rejected...A repository added with -t serves one tenant. A private one takes a
token, which the cluster keeps in its vault and sends with every fetch.
--priority and --sync-interval set at the add what repo update changes
later.
$ shc repo add learn https://selfhostedcloud.org/apps/0.1/index.yaml -t prod --token P@ssw0rd --priority 70 --sync-interval 24h...$ shc repo update learn -t prod --token P@ssw0rd --priority 60...$ shc repo sync learn -t prod...$ shc repo ls -t prod...$ shc repo rm learn -t prod -y✔ removed repository "learn"$ shc repo rm shc -y✔ removed repository "shc"-e scopes a repository to one environment of the tenant; this ladder’s
repositories are tenant-wide, so it is not typed.
$ shc repo add learn https://selfhostedcloud.org/apps/0.1/index.yaml -t prod -e prod --token P@ssw0rd$ shc repo update learn -t prod -e prod --sync-interval 6h$ shc repo sync learn -t prod -e prod --force$ shc repo rm learn -t prod -e prod -yA repository can read its login from a deployment instead of holding a
token. A deployment that serves a guarded registry mints a pull login for
each tenant it grants and keeps it in that tenant’s vault, as a connection
named after the stack. --credential-from <tenant>/<stack>:pull points the
repository at that login. The sync reads it from the vault and the CLI never
sees it. Removing the repository leaves the login where it is, and an empty
--credential-from on repo update drops the reference.
$ shc repo add private https://registry.example.com/apps/index.yaml -t prod --credential-from prod/registry:pull$ shc repo update private -t prod --credential-from ''The app ladder adds the public catalogue again when it needs it.
The backup repository
Section titled “The backup repository”shc init generated the repository’s key and sealed it in the vault, but
set no repository. Until one is set, shc backup create refuses.
$ shc config get backup.repo --show-originKEY FOUND SOURCEbackup.repo true defaultThe repository is a restic repository. Here it is a directory, as on the
app ladder: each node keeps its own copy of the path, so a backup is on
the node that took it. A path every node mounts, or an S3 store, makes it
one repository. It is the cluster’s repository, so the set names
--scope global: with prod selected, a set without it writes a row for
prod alone.
$ shc config set backup.repo /var/backups/shc/repo --scope globalbackup.repo is a path: unless every node mounts the same storage at /var/backups/shc/repo, each of this cluster's 4 nodes keeps its own repository there. A backup is then on the node that took it alone and is lost with that nodeKEY VALUE SCOPEbackup.repo /var/backups/shc/repo global$ shc config ls --prefix backupPATH VALUE SCOPEbackup.password ref+vault://backup/password globalbackup.repo /var/backups/shc/repo globalA location can name an off-site repository of its own, where the
deployments in that location are backed up instead. shc label ls -v
shows it in the BACKUP-REPO column; an empty value clears it.
$ shc label set location=learn/far --backup-repo /var/backups/shc/farLABEL location=learn/farsource deriveddescription the far sitereserved nogranted to -backup repo /var/backups/shc/farcreated 2026-10-11 08:59:50
NODESNODE CONDITION AVAILABILITY SOURCEfar01 ready active derived
CONSTRAINTS none
DEPLOYMENTS none$ shc label ls --key location -v...$ shc label set location=learn/far --backup-repo ''LABEL location=learn/farsource deriveddescription the far sitereserved nogranted to -backup repo -created 2026-10-11 08:59:50
NODESNODE CONDITION AVAILABILITY SOURCEfar01 ready active derived
CONSTRAINTS none
DEPLOYMENTS noneBack something up. Install the shipped Postgres as scratch, give it a
row, and take a backup.
$ shc install postgres -s scratch --where node=home01installing deployment "scratch"[scratch] Healthy 1/1✔ postgres-1 healthy✔ installed deployment "scratch"$ shc exec -s scratch -S postgres-1 -- psql -U postgres -d postgres -c "create table notes (body text); insert into notes values ('kept by the backup')"CREATE TABLEINSERT 0 1$ shc backup create --stack scratch --name first[scratch] Complete 3/3✔ validate the request✔ back up✔ record the backup✔ created backup "20261106T184557Z_78c22ed729e8fc93" named "first"$ shc backup ls -s scratch --status completedID STATUS SIZE BYTES TIMESTAMP POINT IN TIME ENCRYPTION NODE NAME TENANT STACK ENVIRONMENT DATA SCOPE DATABASES LOCATION20261106T184557Z_78c22ed729e8fc93 completed 498050 2026-11-06 18:46:16 assured restic home01 first prod scratch prod unknown postgres restic:/var/backups/shc/repo:7144e5eba192c774d6ae9de29276ce5230528bc80d2852bdb0a719faf44f8f6dThe first backup made the repository. The key that opens it is the one in the vault. Rotating it adds a new key to every repository the old one opens before removing the old one, and records the new one in the vault, so the stored key and the repositories never disagree. Rotate once to a key SHC generates, then once to a key of your own, read from a file only root can read.
P@ssw0rd$ shc backup key ls...$ shc backup key rotate --repo /var/backups/shc/repo --yes...$ chmod 600 ~/backup-key$ shc backup key rotate --new-key-file ~/backup-key --yes...$ shc backup key ls --repo /var/backups/shc/repo...shc backup verify reads the backup’s own manifest and says what it
holds and what it did not prove. --deep reads every byte back out of
the repository.
$ shc backup verify first -s scratch...$ shc backup verify first -s scratch --deep...--paths narrows a backup to the mounts or converters it names and
--exclude leaves files out; scratch has one mount, pgdata-1. --with-dependants
adds every stack that depends on the one named, and nothing depends on
scratch. shc backup key rm drops a key the stored one opens, which the
rotation above already did. --native exports an app’s own format, which
frappe defines.
$ shc backup create --stack scratch --paths pgdata-1 --exclude '*.log' --with-dependants$ shc backup key rm --repo /var/backups/shc/repo --yes$ shc backup export -i <backup> --native --engine-backup <backup> --database site1 --file /srv/handoverA backup can also be written as one file outside the repository, handed
to someone, and read back in. The file is not indexed and not encrypted;
where it lives is yours to decide. --fail with --timeout aborts the
backup if its containers cannot be paused within the seconds given, instead
of stopping them. a1 is a compose app with no database, so its file is small. inspect
reads a file; import makes it a backup in the repository like any other. --from-store sweeps
a whole directory of such files: a report first, the import with
--apply, and a file the repository already holds is skipped.
$ mkdir -p /srv/handover$ shc backup create a1 --file /srv/handover/a1.bak --fail --timeout 60...$ shc backup inspect /srv/handover/a1.bakAPP APP FILES ARCHIVE APP VERSION CHECKSUM DATA SCOPE DEPLOYMENT DEPLOYMENT ARCHIVE ENVIRONMENT ID NAME NODE POINT IN TIME RUNTIME SOURCE MTIMES STACK TENANT TIMESTAMP TOTAL SIZE BYTES/root/learn/cluster/hello 20261106T184643Z_1292d92b8ebbe5aa_app.tar latest e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 no_app_data prod_prod_a1_node_3568dc30fc28 20261106T184643Z_1292d92b8ebbe5aa_deployment.tar prod 20261106T184643Z_1292d92b8ebbe5aa backup_a1_20261106 node-3568dc30fc28 assured docker true a1 prod 2026-11-06T18:46:43.557244717Z 7168
┌─ deployment_config ─────────┐│ lanEnforcement allowlist │└─────────────────────────────┘
┌─ placement ─────────────────┐│ where tier=core&rack!=r1 │└─────────────────────────────┘
┌─ record ───────────────────────────────────────┐│ app_name /root/learn/cluster/hello ││ app_version latest ││ created_at 2026-11-06T17:43:22.436060936Z ││ environment prod ││ id 4 ││ labels.owner learn ││ name a1 ││ node_id node-3568dc30fc28 ││ runtime docker ││ status running ││ tenant_name prod │└────────────────────────────────────────────────┘
┌─ secrets ───────────┐│ count 3 ││ encrypted true ││ environment prod ││ stack_name a1 ││ tenant_name prod │└─────────────────────┘$ shc backup import /srv/handover/a1.bak...$ shc backup import --from-store /srv/handover...$ shc backup import --from-store /srv/handover --apply...$ shc backup ls -s a1...$ shc backup ls --all-tenants --limit 1 --offset 0...--repair-container consents to importing an archive whose member table
was clamped on the way in; none of these was, so it is not typed.
$ shc backup import /srv/handover/a1.bak --repair-containerA schedule takes backups without you. It is five-field cron, and the
leader runs it. --scope says what one schedule covers; --all-connected
and --with-dependants widen each run to the stack’s integration peers
and to the stacks that depend on it.
$ shc backup schedule set '0 3 * * *' --scope deployment -s scratch --all-connected --with-dependants...$ shc backup schedule ls...$ shc backup schedule run --scope deployment -s scratch --all-connected --with-dependants...$ shc backup schedule unset --scope deployment -s scratch...Retention prunes the repository nightly; shc backup prune does it now,
--repo naming the repository to prune, and prints what it removed and
what the repository still holds. Remove first yourself, then remove
the deployment.
$ shc backup prune --repo /var/backups/shc/repo -yREMOVED PACKS REMOVED BLOBS REMOVED BYTES REMAINING PACKS REMAINING BLOBS REMAINING BYTES0 0 0 8 49 434028$ shc backup rm first -s scratch -y...$ shc uninstall scratch -yuninstalling deployment "scratch"[scratch] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "scratch"Before the last page
Section titled “Before the last page”The last page backs up every app the app ladder installs and
restores them on wiped machines. Run that ladder on this cluster now, from
A compose file to A vapp and an add-on.
Skip its page 00, which makes a one-node cluster, and its pages 08 and 09,
which join the machines this cluster already has. First clear what this
ladder left, so its rules do not get in the app ladder’s way: the four hello
deployments, and the reservation on tier=edge, which would refuse the move
of the app ladder’s placed to far01 on the last page.
$ shc uninstall a1 -yuninstalling deployment "a1"[a1] Complete 4/4✔ remove from home01✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ uninstalled deployment "a1"$ shc uninstall a2 -y...$ shc uninstall a3 -yuninstalling deployment "a3"[a3] Complete 5/5✔ remove from home02✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ remove the copy on home01✔ uninstalled deployment "a3"$ shc uninstall a6 -yuninstalling deployment "a6"[a6] Complete 5/5✔ remove from home02✔ take the safety backup✔ leave every node's service VIP table✔ tear down✔ remove the copy on home01✔ uninstalled deployment "a6"$ shc label set tier=edge --reserved=false...$ shc ls...The cluster is as the app ladder’s page 00 leaves it, with the labels this ladder added. When the app ladder’s page 09 is done, come back.
Next: Restoring the whole cluster.