Refreshing app packaging
Upgrading SHC upgrades the control plane. It does not re-render, restart, or otherwise touch a single running app. That is deliberate, but it means a release whose whole purpose was to fix an app’s packaging (a memory limit, a compose fragment, a var default, a corrected job) changes nothing that is running until you ask for it.
This page is how you ask.
| What you want | Use |
|---|---|
| Upgrade the daemon / cluster | Upgrading SHC |
| Move an app to a new upstream version | shc update <stack> <version> |
| Take a catalogue change to an app you already run | This page |
Why a platform upgrade does not touch your apps
Section titled “Why a platform upgrade does not touch your apps”An SHC app is rendered once, at install (and again at each shc update).
The render reads the app package (app.yaml, compose.yaml, vars.yaml, the
job files) and writes a concrete compose.yaml into the deployment directory.
From then on the running deployment is that rendered artifact. Nothing re-reads the
package.
So when a .deb upgrade replaces the shipped catalogue, or a repo sync pulls a
newer .app archive, the catalogue moves and every deployment stays exactly
where it was. What an upgrade does redo is the daemon’s half: the leader
finishes each stored render again for the new build, so a value the daemon
computes, such as a container’s route to the host, follows the upgrade. The
package is not rendered again.
This was measured the hard way. v0.0.16 raised 38 catalogue memory limits.
Not one container on either live estate received them, and every surface an
operator would reasonably consult (shc version, shc ls, tofu plan) said
the estate was healthy. Each was telling the truth about every fact it held:
nothing anywhere recorded a value that had changed.
That state (the package changed, the deployment did not, and nothing said so) is what this feature makes observable.
The three facts SHC records
Section titled “The three facts SHC records”Every render records the content identity of the app package it read, as
apppkg-v1:<sha256> over the resolved package directory (core/apppkg). It is
stored twice: on the deployment row (deployment.app_digest) and in the
deployment’s manifest.json sidecar, which is the copy that is always present
even on a node with no row.
Against that, SHC can resolve what the catalogue would render right now, using the same repo and the same version pin an update would use, and compare the two:
| Verdict | Meaning |
|---|---|
current | Both identities known and equal. The deployment is running what the catalogue would render today. |
stale | Both known and different. An update would re-render this deployment from different bytes. |
unknown | One or both identities could not be established. |
unknown is a third answer, not a soft current. A deployment installed
before the identity existed records nothing, and nothing honest can be
backfilled for it: digesting today’s catalogue would stamp the whole fleet
“current” and manufacture the all-clear this exists to disprove. So unknown
never plans an action and never reads as an all-clear. shc update <stack>
records an identity for the first time; after that the comparison is real.
And unknown covers two situations that are not alike. The verdict itself
does not distinguish them (it reports what it could not do, and the reason text
names which half was missing), but every surface that grades the answer must,
because the remedies are opposites:
| Which half is missing | What it means | Repairable read-only? |
|---|---|---|
| The catalogue half | This node cannot resolve the app package: the repo was never synced here, the app was removed from it, the registry is unreachable. Something is wrong. | Yes: shc repo sync. |
| The deployment half | It recorded no identity. Nothing is wrong; it simply predates the recording, and only a render can supply one. | No. |
The doctor sweep grades on exactly that line; see Step 1: see the drift below.
Step 0: make the new packaging reachable
Section titled “Step 0: make the new packaging reachable”Drift can only be seen once the node can resolve the new package. Where that comes from depends on which repo the deployment installed from:
shc repo ls| Repo kind | Where the package lives | What makes it move |
|---|---|---|
addon (shipped://apps) | /usr/lib/shc/apps/<app>, shipped in the .deb | Installing the new .deb. The directory the render reads is the one the package replaced, so the new identity resolves immediately, with no sync. |
https://…/index.yaml | A published .app archive, downloaded and extracted on demand | shc repo sync <name>. The release publishing new archives is not enough on its own. |
git+… | A clone on the node | shc repo sync --force <name> (--force re-fetches an unchanged ref; it is a no-op for the http and registry kinds, which always re-read the index). |
Verify the sync actually happened. shc repo sync is asynchronous: it
enqueues a task and prints a task id. Confirm synced_at moved before you trust
anything downstream:
shc repo sync shcshc repo ls # SYNCED AT must be newer than it wasA repo whose SYNCED AT has not moved has synced nothing: the drift verdicts
below then compare against the old index and report current for a deployment
that has fallen behind the published catalogue, a true statement about a
question nobody re-asked. There is a 6-hour auto-sync cron
(sync_all_repos_cron, leader-only), but do not take it on faith. It enqueues a
task, and a task that sits pending (shc task ls) has synced nothing.
SYNCED AT is the fact; the cron schedule is not.
Step 1: see the drift
Section titled “Step 1: see the drift”Every command in this step is read-only.
Needs SHC v0.0.17 or newer on the node. Older daemons record no package identity and answer no verdict. They do not report “current” either:
shc update --checksays out loud that the daemon returned no verdict, and the provider lands onunknown.
One deployment, with the reasoning:
shc update --check myblogmyblog: app is stale: `shc update myblog` would re-render from a different app, which restarts the deployment app: affine 0.26 running: apppkg-v1:1f0c… catalogue: apppkg-v1:9b73…--check returns before anything that can mutate. An absent digest prints
none recorded rather than a blank, so two absences cannot be mistaken for a
match. It exits 0 for current and for stale (drift is information, not
a failure) and non-zero only when it could not reach the daemon.
The whole fleet at once:
shc doctor run # the app.package-drift diagnosis; it has no --fixThe sweep’s subject set is every deployment row in every tenant, and its status
line always names how many it examined: 0 deployments checked, ok and
12 deployments checked, ok are different claims and only the second is
evidence.
It reports three populations separately, and they are graded differently because their remedies are:
| Population | Severity | Verdict | Remedy |
|---|---|---|---|
| Recorded an identity, and it differs from the catalogue | warning | fail (exit 1) | shc repo sync && shc update <stack>. This re-renders and restarts the deployment. The hint says so before it says what to type. |
| This node cannot resolve the deployment’s app package at all | warning | fail (exit 1) | shc repo sync <name>, read-only, re-renders nothing. Still unresolvable after a successful sync means the app is gone from that repo. |
| No identity was ever established | info | warn (exit 0) | None, and none is offered. |
That third row is the state every deployment predating v0.0.17 is in, which on
both live estates was all of them, so as first shipped this check failed on
every node of every estate and prescribed shc update <stack> for two dozen
stacks holding production data. Neither half of that was honest: nothing was
wrong, and the advice was a fleet-wide restart. A check that fails everywhere
trains operators to skip the output, and a check whose remedy is unsafe trains
them to distrust it; either way you no longer have an observer.
So it is now an info finding: printed, counted, named, and explicitly not an
all-clear, but not a failure, and with no command attached. There is nothing
honest to attach. No read-only command can give a deployment an identity it
never recorded, and a backfill would have to digest today’s catalogue, which
stamps the fleet current and manufactures the very all-clear this feature
exists to disprove. The identity appears on its own, the next time that
deployment is rendered for any reason.
What still turns this check red, so the softer tier cannot be mistaken for “unknown means fine”: a deployment whose recorded identity no longer matches the catalogue (the case the feature was built for), and a node that cannot resolve the catalogue at all. Both are unchanged.
app.package-drift deliberately carries no prescription, so
shc doctor run --fix never touches it; see
the prescription table
for what --fix does change.
Over the API (the comparison is opt-in, because resolving it may download and extract a remote archive):
curl "$SHC_URL/api/method/shc.stack.status?stack_name=myblog&app_package=1"Without app_package=1 the response carries the recorded identity alone and the
app_package verdict is absent, which means “you did not ask”, never
“no drift”.
In OpenTofu / Terraform, drift arrives during refresh, before the plan, with no planned action:
Note: Objects have changed outside of Terraform
# shc_deployment.affine has changed ~ resource "shc_deployment" "affine" { ~ app_package_available = "apppkg-v1:1f0c…" -> "apppkg-v1:9b73…" ~ app_package_drift = "current" -> "stale" }
No changes. Your infrastructure matches the configuration.Step 2: pre-flight, before you take anything
Section titled “Step 2: pre-flight, before you take anything”A refresh re-renders from whatever the catalogue offers for this deployment’s version pin. It is not a limits-only operation, and this is the step people skip.
Read the pin first
Section titled “Read the pin first”shc ls --all-tenantsapp_version: "latest", app_version: "stable" and app_version: null are
behaviourally identical and all mean unpinned: the re-render resolves the
catalogue head.
A bare-major pin is not a freeze either. The catalogue predicate
(catalogVersionPredicate) treats a token containing + as exact equality and
everything else as version = ? OR version LIKE '<token>+%', so
app_version: "16" matches 16 and every 16+N. Only the published
<upstream>+<build> spelling (16+0, 0.7+2, 2025.4.3+0) holds a
deployment on one package.
A bare pin that could land on more than one image set now REFUSES rather than
picking. It used to resolve whichever row the sync inserted last, silently.
Measured 2026-08-04 across all 298 retained archives, sixteen of the 77
published apps have retained revisions that share an app_version and render
different images, so that silence was doing real work: external-postgres
1.0+0 is percona 16.14 and 1.0+1 is percona 18.4; jellyfin 1+0 is
10.10.7 and 1+1 is 10.11.11 (the one-way library migration below);
matomo 5+0 and 5+1 are the same tag at different digests; keycloak
26.6 has five distinct image sets across ten revisions. And because
shc install <app> <version> persists the token, every later
shc update re-resolved it: the hop landed on an update of a stack you
believed pinned.
So a bare token that spans more than one recorded image set now fails
X409041APPVSPN, listing each candidate revision and the images that
distinguish it. Name one:
X409041APPVSPN app external-postgres version 1.0 matches published revisionsthat render different images (1.0+1 renders percona/…:18.4@sha256:40b133dec71f;1.0+0 renders percona/…:16.14@sha256:d329970c5013), refusing to pick oneWhat is not affected: latest / stable / unpinned (all still resolve the
head), any exact <upstream>+<build>, and any bare pin on the ~61 apps whose
retained revisions agree: affine 0.27 spans four revisions that all render
0.27.3 and resolves as before. Revisions published before the index recorded
images are treated as unknown, not as agreeing, so they cannot trigger the
refusal either: the check needs positive evidence of divergence from two
revisions that both recorded what they render.
SHC never auto-pins. Unpinned means unpinned, so on an unpinned deployment a refresh takes the upstream version hop along with the packaging fix.
Two more things a pin cannot do, both worth knowing before you plan a pass:
-
A version label is not a promise about the image. The pin resolves a catalogue row; what that row’s
vars.yamlsetsimages.*to is the packager’s business. A row labelled0.26+0can ship a0.27.3image, in which case the pin that reads like a freeze is an upgrade.affineis the measured case: the packaging commit that moved its image0.26.5→0.27.3did not move app.yaml’sversion: "0.26", so every published revision (0.26+0,0.26+1and all four0.27+N) ships0.27.3, and a deployment still running0.26.5has no pin that holds it.The index now states this, so you can check it without downloading a package. Every published revision records the image references it renders:
Terminal window # what the running deployment actually hasdocker inspect --format '{{.Config.Image}}' <deployment-id>-app-1# what each published revision of that app renderscurl -s https://selfhostedcloud.org/apps/index.yaml \| yq '.apps[] | select(.name == "affine") | .versions[] | {version, images}'A revision whose
imagescontains the reference the container reports is a pin that holds. If no revision does, there is no safe pin; say so and either republish a revision that pins the running image or plan the upgrade; do not pin the closest-looking label, because for a database app that is the one-way hop. -
Setting a pin costs one re-render. There is no verb that writes
app_versionwithout also running phase 2, so “pin now, refresh later” is really “the pin is the first refresh”. It is free only when the pinned package’s bytes are the bytes already rendered, in which casecompose uprecreates nothing; verify that by hashing the deployment’s renderedcompose.yamlbefore and after.
One-way changes in the current catalogue
Section titled “One-way changes in the current catalogue”These cannot be undone by re-running the old version. Check this list against
shc ls before refreshing anything:
| App | What a refresh takes, permanently |
|---|---|
defectdojo | Loses SSO; the app now refuses an oidc binding outright. Sibling app defectdojo-classic holds the featureful line. |
affine | flags.allowGuestDemoWorkspace flips to false: logged-out web visitors get a sign-in page instead of a browser-local demo workspace. Restore upstream behaviour with --var flags.allowGuestDemoWorkspace=true. |
redis | Redis 8 writes an RDB that Redis 7 cannot read. No downgrade. |
clickhouse | 26.3 has no downgrade path. |
mariadb | 12 fails to start on option keys removed upstream. |
paperless | 3.0 removes API v1 and wipes task history. |
nextcloud | Fails closed on a skipped major: take the ladder one hop at a time. |
Anything not on that list is still a container recreate. Back up first:
shc backup create -s <stack>Step 3: take it
Section titled “Step 3: take it”The CLI path
Section titled “The CLI path”Per deployment, deliberately, one at a time:
shc update <stack>A bare shc update does not replay the recorded digest: no verb re-renders
a deployment from the bytes it last used. It re-resolves the package from the
current catalogue.
★ On a pinned deployment, do not run a bare
shc update. The CLI defaults the version argument tolatestwhen you omit it (if args.Version == "" { args.Version = "latest" }) andBuildUpdateBodyputs it on the wire, so phase 1 foldslatestonto the row before phase 2 resolves anything. The daemon-side replay (resolveUpdateAppVersion) then reads the already-merged row and seeslatest. Net effect: a bareshc update <stack>on a deployment pinned at16leaves the row readinglatestand re-renders from the catalogue head. The pin is destroyed and the version hop is taken in the same command.Omitting
versionover the API (POST shc.stack.updatewith noversionfield) does replay the row’s pin; the defect is the CLI’s default, not the resolver. Always name the version explicitly on a pinned deployment, even when you mean “stay here”:shc update <stack> 16+0.
To move the version deliberately, name it: shc update <stack> <version>
(or the glued shc update <stack>@<version>) resolves that version and writes
it onto the row as the new pin.
The OpenTofu (Terraform) path
Section titled “The OpenTofu (Terraform) path”shc_deployment exposes the comparison as three computed attributes plus one
consent switch:
| Attribute | Kind | Meaning |
|---|---|---|
app_digest | export | What this deployment last rendered from. Empty = none recorded; never “current”. |
app_package_available | export | What the catalogue would render now. Empty = could not resolve, which is not an all-clear. |
app_package_drift | export | current / stale / unknown. |
refresh_app_package | argument, default false | Standing consent to take drift. |
The default shows and takes nothing. With refresh_app_package unset, the
three attributes refresh and pin, the drift appears in the refresh note above,
and the plan stays empty. Nothing restarts.
Set the consent to turn a stale verdict into a planned in-place update:
resource "shc_deployment" "affine" { repo = "shc" app = "affine" tenant = "corp"
refresh_app_package = true} # shc_deployment.affine will be updated in-place ~ resource "shc_deployment" "affine" { ~ app_digest = "apppkg-v1:1f0c…" -> (known after apply) }
Plan: 0 to add, 1 to change, 0 to destroy.Only stale ever plans an action. unknown never does: re-rendering every
deployment on the estate because a registry was unreachable would be acting on
the absence of information. Leave the consent false on stateful deployments you
want to restart on your own schedule, and take those with shc update <stack>
instead; a per-stack update needs no change to the file.
What the apply actually does
Section titled “What the apply actually does”The same thing for both paths, because the consent switch carries no value to the daemon: it decides, at plan time, whether a stale deployment plans the ordinary bare update the daemon already resolves from the current catalogue.
- The deployment is re-rendered from the resolved package, replaying its persisted vars, hosts, ports, integrations, connections, quotas, add-ons and placement.
pre_updateandpost_updatehooks fire (not the install pair). Apre_updaterefusal abandons the update.docker compose up -d --remove-orphans --waitruns against the new render. Compose recreates only the services whose rendered spec changed and leaves the rest running.- The new package identity is recorded, and the deployment is polled to a
terminal state when
wait_healthyis true (the default).
What it does not do:
- it does not destroy and recreate the deployment;
- it does not stop the deployment the way
shc backup createdoes; - it does not remove volumes: every data mount survives the recreate;
- it does not run a data migration. If the version hop needs one, that is the app’s own gate, and the one-way table above is the list to read first.
Treat “recreates the changed services” as a restart of those services: for a database stack that is a control-plane restart, however narrow.
Recommended order
Section titled “Recommended order”- Upgrade the platform first. Rolling the
.debre-renders nothing; this is safe and it is what makes the drift signal available at all. See Upgrading SHC. Unlock each node’s vault afterwards: every daemon restart leaves it locked. - Make the new packaging reachable: Step 0. For repo-sourced apps, sync and
then confirm
SYNCED ATmoved. - Read the fleet:
shc doctor run, thenshc update --check <stack>on anything it names. Expect a wave ofunknownthe first time: no deployment installed before this feature recorded an identity. - Pre-flight: Step 2. Read every pin, cross off the one-way table, and confirm a working backup path before the first update rather than after it.
- Take one stack, and read it. Start with the least stateful deployment you
have. Confirm the change actually landed in the container, not merely in the
verdict:
docker inspect --format '{{.HostConfig.Memory}}' <container>. - Then the rest, one at a time, stateful stacks last and quiet. Reserve
refresh_app_package = truefor a fleet you have already walked by hand.
A refresh that reported success and reached no container is the exact failure this mechanism exists to expose. Verify at the container, every time.
See also
Section titled “See also”- Upgrading SHC: the control-plane half
- Estate app refresh, August 2026: a worked pass on two live estates, including how to identify the running package on a daemon that records no digest
shc updatereference: including--check- Terraform provider reference: the
shc_deploymentdrift trio andrefresh_app_package - App update flow: what a re-render does internally