Skip to content
SHC Docs

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 wantUse
Upgrade the daemon / clusterUpgrading SHC
Move an app to a new upstream versionshc update <stack> <version>
Take a catalogue change to an app you already runThis 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.


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:

VerdictMeaning
currentBoth identities known and equal. The deployment is running what the catalogue would render today.
staleBoth known and different. An update would re-render this deployment from different bytes.
unknownOne 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 missingWhat it meansRepairable read-only?
The catalogue halfThis 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 halfIt 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.


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:

Terminal window
shc repo ls
Repo kindWhere the package livesWhat makes it move
addon (shipped://apps)/usr/lib/shc/apps/<app>, shipped in the .debInstalling 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.yamlA published .app archive, downloaded and extracted on demandshc repo sync <name>. The release publishing new archives is not enough on its own.
git+…A clone on the nodeshc 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:

Terminal window
shc repo sync shc
shc repo ls # SYNCED AT must be newer than it was

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


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 --check says out loud that the daemon returned no verdict, and the provider lands on unknown.

One deployment, with the reasoning:

Terminal window
shc update --check myblog
myblog: 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:

Terminal window
shc doctor run # the app.package-drift diagnosis; it has no --fix

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

PopulationSeverityVerdictRemedy
Recorded an identity, and it differs from the cataloguewarningfail (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 allwarningfail (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 establishedinfowarn (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):

Terminal window
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.

Terminal window
shc ls --all-tenants

app_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 revisions
that render different images (1.0+1 renders percona/…:18.4@sha256:40b133dec71f;
1.0+0 renders percona/…:16.14@sha256:d329970c5013), refusing to pick one

What 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.yaml sets images.* to is the packager’s business. A row labelled 0.26+0 can ship a 0.27.3 image, in which case the pin that reads like a freeze is an upgrade. affine is the measured case: the packaging commit that moved its image 0.26.5 → 0.27.3 did not move app.yaml’s version: "0.26", so every published revision (0.26+0, 0.26+1 and all four 0.27+N) ships 0.27.3, and a deployment still running 0.26.5 has 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 has
    docker inspect --format '{{.Config.Image}}' <deployment-id>-app-1
    # what each published revision of that app renders
    curl -s https://selfhostedcloud.org/apps/index.yaml \
    | yq '.apps[] | select(.name == "affine") | .versions[] | {version, images}'

    A revision whose images contains 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_version without 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 case compose up recreates nothing; verify that by hashing the deployment’s rendered compose.yaml before and after.

These cannot be undone by re-running the old version. Check this list against shc ls before refreshing anything:

AppWhat a refresh takes, permanently
defectdojoLoses SSO; the app now refuses an oidc binding outright. Sibling app defectdojo-classic holds the featureful line.
affineflags.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.
redisRedis 8 writes an RDB that Redis 7 cannot read. No downgrade.
clickhouse26.3 has no downgrade path.
mariadb12 fails to start on option keys removed upstream.
paperless3.0 removes API v1 and wipes task history.
nextcloudFails 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:

Terminal window
shc backup create -s <stack>

Per deployment, deliberately, one at a time:

Terminal window
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 to latest when you omit it (if args.Version == "" { args.Version = "latest" }) and BuildUpdateBody puts it on the wire, so phase 1 folds latest onto the row before phase 2 resolves anything. The daemon-side replay (resolveUpdateAppVersion) then reads the already-merged row and sees latest. Net effect: a bare shc update <stack> on a deployment pinned at 16 leaves the row reading latest and re-renders from the catalogue head. The pin is destroyed and the version hop is taken in the same command.

Omitting version over the API (POST shc.stack.update with no version field) 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.

shc_deployment exposes the comparison as three computed attributes plus one consent switch:

AttributeKindMeaning
app_digestexportWhat this deployment last rendered from. Empty = none recorded; never “current”.
app_package_availableexportWhat the catalogue would render now. Empty = could not resolve, which is not an all-clear.
app_package_driftexportcurrent / stale / unknown.
refresh_app_packageargument, default falseStanding 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.


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.

  1. The deployment is re-rendered from the resolved package, replaying its persisted vars, hosts, ports, integrations, connections, quotas, add-ons and placement.
  2. pre_update and post_update hooks fire (not the install pair). A pre_update refusal abandons the update.
  3. docker compose up -d --remove-orphans --wait runs against the new render. Compose recreates only the services whose rendered spec changed and leaves the rest running.
  4. The new package identity is recorded, and the deployment is polled to a terminal state when wait_healthy is 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 create does;
  • 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.


  1. Upgrade the platform first. Rolling the .deb re-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.
  2. Make the new packaging reachable: Step 0. For repo-sourced apps, sync and then confirm SYNCED AT moved.
  3. Read the fleet: shc doctor run, then shc update --check <stack> on anything it names. Expect a wave of unknown the first time: no deployment installed before this feature recorded an identity.
  4. 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.
  5. 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>.
  6. Then the rest, one at a time, stateful stacks last and quiet. Reserve refresh_app_package = true for 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.