Skip to content
SHC Docs

shc update

update a deployment

Update a deployment in place: bump the app version, change variables, add or remove hosts and ports, and rewire integrations. The update runs asynchronously on the daemon, which re-renders and re-deploys the deployment with the merged settings.

/@ takes the app from that repo at that version, the same update as <stack> <version> -r <repo>. When a deployment named exists, the token is the vApp instance / instead. A / and an -r/--repo naming two different repos are refused (X400076REPTWO).

One install, update or uninstall changes a deployment at a time, on the whole cluster. A second one on a deployment another is still changing is refused, not queued, naming the operation in flight, its node and its start (X409953OPRRUN), and nothing is started or written; run it again once that one has ended. shc operation ls lists what is in flight. Operations on different deployments run in parallel.

--where and --prefer change where the deployment may run. Each replaces its expression; an empty value clears it. A change that leaves its node outside the new rules relocates it: the update prints a plan naming the replicas that move, what happens to each volume, the durable data to carry and the expected downtime, and asks before anything is copied. --plan prints that plan and stops; --yes skips the question. Durable volumes (the ones the app’s backup keeps) are copied or reattached while the node they are on is alive, and scratch volumes are recreated empty. When that node is dead and a durable volume cannot be reattached elsewhere the update is refused, naming the volume, unless --restore-from-backup restores it from the deployment’s latest backup.

--storage moves the deployment’s durable volumes off the node disk onto that block-storage provider, on the node it runs on, or with --where on the node the new rules place it on. The update prints the plan and asks first, as a rule change does: the deployment stops, its data is backed up and restored onto new volumes, and it starts on them. A failed restore puts it back on the node disk as it was. Scratch volumes stay where they are. shc doctor lists the durable volumes still on a node disk (storage.durable-on-node-disk).

--scale =@[,@…] says where a group’s members live. A member it sets for a location it does not run in is moved there: the update prints the same plan and asks before anything changes, records the scale, then moves the members one at a time, each ready before the next. --plan prints that plan and stops; --yes skips the question.

--rollback goes back to a spec the deployment keeps: the newest one that finished its rollout and differs from the current spec, never a failed attempt or a copy of what runs; with --rollback=, the kept spec the digest or a prefix of it names, whatever its outcome. The plan says when that spec last finished. The settings it was rendered with come back with it, and the replicas roll back as an update rolls them. It prints the plan and asks first; --plan prints it and stops, --yes skips the question. It puts the spec back, not data: volumes keep what the newer spec wrote. It takes no other change beside it.

An update whose rollout fails stops where it is, unless a service’s update_config says failure_action: rollback: replicas that moved stay moved, the ready ones keep serving, and the rollout reads paused. The update then ends (X409148RLTNFN), naming each replica that failed and its exit: a default rollout pauses at a replica’s first failure. With failure_action: continue the rollout goes past failed replicas, and once it is done the update ends on a replica that failed with a non-zero exit 3 times over at least 3 minutes without reading ready, as an install does (X409783PODCRS). Otherwise it waits for every replica to read ready and be routed for at most compose_converge (15 minutes by default) and the longest start period. Running update again, with the same spec or a new one, is a new attempt that goes forward from there and never rolls back first; once it finishes, its post_update jobs run as any update’s do. --rollback goes back instead. --rollback-on-failure makes this one run go back by itself when it fails, to the spec it replaces, whatever failure_action says; a rollout that finishes with a replica not ready on the new spec counts as failed. It waits for the rollout to tell, so it does not go with --no-wait.

--var overrides are persistent deployment state: a bare update replays the overrides the deployment was installed (or last updated) with, --var key=value adds or replaces a single key, and a trailing ’!’ (--var key!) drops that key back to the app’s default.

The trailing ’!’ is the removal marker on the spec flags: --expose blog.example.com! drops a persisted route, --expose 8080! drops a persisted port mapping, and -i oidc! disconnects an integration. You remove a thing by the same identity you would use to replace it, and a token carrying more than that identity is refused rather than having the extra silently discarded: a port removal names external[+udp][@conn] and never a service or container port, so --expose 80=web! is refused; a route removal names hostname[/path] and never a target, so --expose blog.example.com=web:80! is refused. A bare --expose ’!’ removes every route and port the same line does not name: the entries beside it are the deployment’s whole expose set, in the order given, and the first host is the canonical origin.

A removal and an add of the same identity on one line is an add: the removal applies to what the deployment already had, and the add lands afterwards, so the order you type them in does not matter.

A removal token that matches nothing is reported and ignored (the rest of the update still applies), because re-running a correct command must not fail. Pass --strict-removals (or set SHC_STRICT_REMOVALS=1) to make it a hard failure instead. Either way the update says what each removal token did: one line naming every token that matched, one naming every token that did not, so a typo and a success are not both silent.

A module such as traefik / keycloak / openobserve in the master tenant restates part of its variable set on every update, from modules.<app>.vars.<key> config rows and from values the daemon derives. --var <key>! on one of those is refused rather than performed, because the restate would write it straight back: the error names the real source, and for a config-backed value the shc config unset line that clears it.

Integrations are persistent deployment state like routes, ports and --var overrides: -i oidc=keycloak adds or repoints one edge and leaves every other integration on the deployment wired.

An update that adds or repoints an edge is held only to the edges it changes. Another edge whose socket job fails is left as it was, with a warning naming it, and the update goes on. An update that changes no edge is refused when any edge’s socket job fails, and the error names that edge.

An integration edge is identified by its consumer plug, so -i oidc! always names exactly one edge, and a bare removal token is always read as a plug, never as a provider, however much the deployment happens to hold. That is what makes re-running a removal safe: once the plug is gone the same token matches nothing and is reported, instead of quietly meaning something else on the second run. The bare add form is still sugar: -i keycloak is resolved to the plug it means before anything else happens, and is refused if it cannot be, so the edge it wires is named by that plug, not by ‘keycloak’. An edge whose plug could not be resolved (a sidecar written before this rule, on a node where the provider is not deployed) is named by its provider reference instead: -i @aws-primary! or -i postgres@default!, exactly as shc update prints it back to you. A disconnect drops the edge from the re-rendered compose, from the deployment’s persisted state and from the integration table, so it stops being replayed, and then it runs the provider’s unintegration teardown against the context the edge was bound with, so a disconnected keycloak edge also has its OIDC client deleted from the realm. The teardown runs only after the re-deploy succeeded, and a teardown job that fails is reported as retained state rather than failing the update. It does not revoke a connection-backed edge’s minted credential: -i s3=@aws-primary! leaves the scoped IAM user behind; that still happens only on uninstall.

To remove several, either repeat the flag (--expose a.com! --expose b.com!) or comma-join them (--expose a.com!,b.com!). --expose and -i comma-split, so both spellings arrive as two removals. --var alone has no comma form: a var value may itself contain commas, so --var takes one key per flag, and a removal key carrying a comma, a semicolon or whitespace is rejected rather than read as one strange key. The comma form always works in scripts, in CI and over the Terraform provider, which do not run history expansion at all; it needs single quotes only when typed at an interactive bash or zsh prompt, where a bang followed by a comma is a history reference and an unquoted line fails loudly with ‘event not found’ without running anything. A ’!’ inside a --var value is never a marker: the token carries an ’=’, so --var password=hunter2! sets the password to hunter2!. When you do quote a marked token, use single quotes: zsh runs history expansion inside double quotes, so double quotes are the one form that breaks.

An update is a patch and never prompts. It changes what the flags name and leaves every other variable exactly as the deployment already holds it. There is no form, no interview, and no need to restate values you are not changing. The behaviour is identical at a terminal and in a pipeline; piping does not change what a command means. A required variable the deployment does not hold, and that no integration can supply, is a refusal that names every one of them at once and prints the command that supplies them (X400419VARMIS). Passing --var does not suppress that check: one --var has never been evidence that the others are set.

--interactive opts in to the variables form, and is the only thing that opens one. On its own it opens the form prefilled with the deployment’s current values (folded with any --var you gave); alongside a change flag (--expose, -i, --scale, a version) it asks only for required variables the deployment does not already hold, which for a healthy deployment is none. Cancelling a form that stood in front of typed flags abandons the update and changes nothing (X400418UPDABD), because those flags were never sent. A variable a plug supplies is never demanded in either form; leave it blank and connect the plug with -i. shc install carries the same flag with the same meaning. --gated/--open switch the SSO gate. --from/--ref/--path/--token repoint or refresh the deployment’s git/path source.

shc update [[<repo>/]<stack>[@<version>]] [<version>] [flags]
shc update myblog --check
shc update myblog --rollback --plan
shc update myblog --rollback=9f8e7d6c --yes
shc update myblog
shc update myblog 2.4.1 --var theme=dark
shc update community/[email protected] -t corp -e prod
shc update myblog --var theme!
shc update myblog --expose blog.example.com=web:8080 --gated
shc update myblog --expose blog.example.com! --expose old.example.com!
shc update myblog --expose 'a.example.com!,b.example.com!'
shc update myblog --expose 8080!
shc update myblog -i oidc=keycloak
shc update myblog -i oidc!
shc update myblog --where 'location=hetzner/hel1' --plan
shc update myblog --where 'node=hel-02' --yes
shc update myblog --where ''
shc update myblog --where location=hel1 --where db:location=nbg1
shc update myblog --where 'db!'
shc update myblog --storage linstor --plan
shc update myblog --cpu-quota web=1.0 --memory-quota web=512Mi --scale web=3
shc update myblog --interactive
--acme-provider string override ACME provider (which named CA issues public certs; blank = acme.default)
--check report whether the app changed since this deployment was rendered, and change nothing
-c, --config-set stringArray deployment-scoped config row: key=value sets, key! removes the row at this deployment's scope only
-C, --connection strings rebind a declared connection: name=connection (bare connection ok when the app declares exactly one)
--cpu-quota strings per-service CPU quota (service=value, service! clears it, ! alone clears every service not named; services not named keep theirs otherwise); the limit and reservation derive from it via deploy.limit_ratio / deploy.reservation_ratio, and accounting charges it
--dns-provider string override DNS provider
-e, --environment string environment name (default: "prod", or "default" on an estate with no licence and no trial; $SHC_ENVIRONMENT and shc ctx -e override it, and the "master" tenant is always "default")
--expose strings publish out: <port|hostname[:port][/path]>[+option...][@where][=<service>[:<container port>]] (outside! removes one; bare '!' clears every route and port)
--force allow --ttl against a protected environment (prod), and a relocation that copies volumes its storage does not follow
--from string change source (git URL or local path)
--gated require Keycloak SSO in front of the app
-h, --help help for update
-i, --integrate strings integrate with provider: [plug=]provider[@env] or plug=@connection (provider! or plug! disconnects one edge)
-I, --interactive open the variables form (off by default: an update changes what the flags name and asks about nothing else)
--label stringArray operator label: key=value sets or replaces, key! removes, ! clears every operator label (repeatable; keys not named stay)
--memory-quota strings per-service memory quota (service=value, service! clears it, ! alone clears every service not named; services not named keep theirs otherwise); the limit and reservation derive from it via deploy.limit_ratio / deploy.reservation_ratio, and accounting charges it
--naming-exception string record why this deployment keeps a name that is not the DNS label it serves; silences the naming-convention warning and is reported by shc doctor run --diagnosis app.deployment-naming as a recorded decision. A reason is required: an empty value is refused. A bare update replays whatever is already recorded
--no-backup when a rule change moves the deployment, rebind its block volumes without the pre-move archive
--no-wait return without waiting for the containers to report healthy
--open no SSO gate; rely on the app's own auth
--path string subdirectory path when using --from or an existing git source
--plan print what this update would change (vars, quotas, config, integrations, routes, ports, placement, the app it renders, and each replica it re-creates) and change nothing; exits 3 when it would change something. A rule change or a --scale to locations prints the relocation it runs, and --rollback the rollback
--prefer stringArray nodes the deployment prefers: <selector> for every service, <service>:<selector> for one service, <service>! drops that service's own, ! drops them all (repeatable)
--private walk the deployment back to LAN-only (undo --public); re-renders the ipAllowList
--profile strings replace the compose profiles the deployment runs, comma-separated or repeated; --profile '' runs none, and an update without it keeps them
--protected protect the deployment: refuse uninstall/destroy until 'shc unprotect' (it can still be moved and drained)
--public expose to the internet (default: LAN-only)
-q, --quiet suppress progress output
--ref string git reference when using --from or an existing git source
-r, --repo string resolve the app from this repository (overrides the deployment's replayed repo pin; authorises a source swap, carrying current effective vars forward)
--reset-vars adopt the app's defaults instead of preserving the deployment's current effective values, on a source swap and for templated defaults on any update (persisted --var overrides still replay, an identifier it would rewrite is refused)
--restore-from-backup when a rule change moves the deployment off a dead node, restore the durable volumes that node took with it from the latest backup
--rollback digest[=previous] go back to a spec the deployment keeps: bare, the newest one that finished its rollout and differs from the current spec; =<digest> names a kept spec by digest or a prefix of it. The replicas roll back as an update rolls them; data is not rolled back
--rollback-on-failure if this update fails, roll back to the spec it replaces, whatever the services' failure_action says
--scale stringArray replicas per service, or members per group: <name>=<n>, <name>=<n>@<location>[,<n>@<location>...] or <svc>=<n>/<kind>; <name>! clears it, ! alone clears every name not given, names not given keep theirs otherwise (repeatable)
-s, --stack string stack name, in place of the first argument
--storage stringArray a volume's size, repeatable: <volume>=<size>; sizes take Ki, Mi, Gi, Ti, K, M, G or T; a block volume grows to it; a volume never shrinks and keeps its backend. Or <block provider>: move the deployment's durable volumes off the node disk onto it, copying their data
--strict-removals fail the update when a removal token ('!') matches nothing, instead of reporting it and carrying on
--token string authentication token for private git repositories
--ttl string re-stamp the deployment lease (e.g. 72h); unset leaves any existing lease untouched
--unprotected clear the deployment's protection flag
--var stringArray variable override: key=value sets, key! removes the persisted override (one key per flag, no comma form)
--where stringArray nodes the deployment may run on: <selector> for every service, <service>:<selector> for one service, <service>! drops that service's own, ! drops them all (repeatable)
-y, --yes relocate or roll back without asking, when a rule change or a --scale to locations moves the deployment or --rollback is given
--config stringArray extra YAML config file to layer on top of auto-discovered config; repeatable, later files win
-d, --debug enable debug mode (default: $SHC_DEBUG)
--exclude string comma-separated dotted paths to drop
--fields string comma-separated columns/keys to show (and their order)
--filter string comma-separated dotted paths to keep (drops everything else)
-o, --output string output format: tty|text|json|yaml (default: $SHC_OUTPUT)
-t, --tenant string tenant name (default: $SHC_TENANT)
-v, --verbose verbose output (default: $SHC_VERBOSE)
  • shc - Selfhosted Cloud CLI