Skip to content
SHC Docs

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.

SHC ships one app repository, and shc init registered the public catalogue beside it as shc. Give the catalogue a sync interval.

home01
$ shc repo ls
NAME URL APP COUNT PRIORITY TENANT ID ENVIRONMENT SYNCED AT
shc https://selfhostedcloud.org/apps/0.1/index.yaml 585 50 system 2 system 2026-10-11T09:24:31.354027674Z
shipped 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 ls
NAME URL APP COUNT PRIORITY TENANT ID ENVIRONMENT SYNCED AT SYNC INTERVAL
shc https://selfhostedcloud.org/apps/0.1/index.yaml 585 50 system 2 system 2026-10-11T09:24:31.354027674Z 24h
shipped 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.

home01
$ 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.

home01
$ 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.

explained, not walked: the repositories here are tenant-wide
$ 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 -y

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

explained, not walked: it needs a deployment that serves a guarded registry, which this ladder does not install
$ 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.

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.

home01
$ shc config get backup.repo --show-origin
KEY FOUND SOURCE
backup.repo true default

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

home01
$ shc config set backup.repo /var/backups/shc/repo --scope global
backup.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 node
KEY VALUE SCOPE
backup.repo /var/backups/shc/repo global
$ shc config ls --prefix backup
PATH VALUE SCOPE
backup.password ref+vault://backup/password global
backup.repo /var/backups/shc/repo global

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

home01
$ shc label set location=learn/far --backup-repo /var/backups/shc/far
LABEL location=learn/far
source derived
description the far site
reserved no
granted to -
backup repo /var/backups/shc/far
created 2026-10-11 08:59:50
NODES
NODE CONDITION AVAILABILITY SOURCE
far01 ready active derived
CONSTRAINTS
none
DEPLOYMENTS
none
$ shc label ls --key location -v
...
$ shc label set location=learn/far --backup-repo ''
LABEL location=learn/far
source derived
description the far site
reserved no
granted to -
backup repo -
created 2026-10-11 08:59:50
NODES
NODE CONDITION AVAILABILITY SOURCE
far01 ready active derived
CONSTRAINTS
none
DEPLOYMENTS
none

Back something up. Install the shipped Postgres as scratch, give it a row, and take a backup.

home01
$ shc install postgres -s scratch --where node=home01
installing 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 TABLE
INSERT 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 completed
ID STATUS SIZE BYTES TIMESTAMP POINT IN TIME ENCRYPTION NODE NAME TENANT STACK ENVIRONMENT DATA SCOPE DATABASES LOCATION
20261106T184557Z_78c22ed729e8fc93 completed 498050 2026-11-06 18:46:16 assured restic home01 first prod scratch prod unknown postgres restic:/var/backups/shc/repo:7144e5eba192c774d6ae9de29276ce5230528bc80d2852bdb0a719faf44f8f6d

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

~/backup-key
P@ssw0rd
home01
$ 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.

home01
$ 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.

explained, not walked: scratch has one mount, nothing depends on scratch, the rotation removed the old key, no frappe app here
$ 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/handover

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

home01
$ mkdir -p /srv/handover
$ shc backup create a1 --file /srv/handover/a1.bak --fail --timeout 60
...
$ shc backup inspect /srv/handover/a1.bak
APP 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.

explained, not walked: no archive here was clamped
$ shc backup import /srv/handover/a1.bak --repair-container

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

home01
$ 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.

home01
$ shc backup prune --repo /var/backups/shc/repo -y
REMOVED PACKS REMOVED BLOBS REMOVED BYTES REMAINING PACKS REMAINING BLOBS REMAINING BYTES
0 0 0 8 49 434028
$ shc backup rm first -s scratch -y
...
$ shc uninstall scratch -y
uninstalling 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"

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.

home01
$ shc uninstall a1 -y
uninstalling 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 -y
uninstalling 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 -y
uninstalling 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.