Skip to content
SHC Docs

App commands

Install an app as a new deployment. Apps can be installed from three sources: the app catalog (repository), a local filesystem path, or a git URL.

Terminal window
shc install nextcloud
shc install nextcloud --stack cloud --environment prod
shc install wordpress --stack blog --var title="My Blog"
shc install keycloak/realm --into keycloak --instance test-realm
shc install nextcloud --expose cloud.example.com --dns-provider cloudflare

When several registered repos carry an app, the highest repo priority wins. Name one in the token, <repo>/<app>[@<version>] (the REPO and APPLICATION columns of shc search), or with -r/--repo:

Terminal window
shc install bitspur/[email protected]
shc install frappe 15.118 -r bitspur # the same install
shc update bitspur/[email protected] -t corp -e prod
shc repoint photos apps/immich

The deployment lands under the app’s name (frappe above), as with -r. A slash keeps its in-app meaning first: when the app before it publishes the name after it as an add-on or a vApp, the token is that add-on or vApp (nextcloud/deck, nextcloud/talk), and on shc update a deployment named like the first half makes the token that deployment’s vApp instance (shc update nc/[email protected]). Otherwise the first half must be a repo this tenant can see. A repo in the token and a different -r/--repo are refused with X400076REPTWO; the same repo stated twice is accepted.

There is no --version flag. The version is always the second positional, or folded into the source as a one-token <app>@<version>. Omit it entirely and latest is used:

Terminal window
# Positional: <app> <version>
shc install nextcloud 30
# One-token: <app>@<version>, peeled off the source before catalog lookup
shc install nextcloud@30
# Pin an exact app revision: <app>@<version>+<revision>
shc install nextcloud@30+2

A bare version (30) resolves to the newest packaged revision of that upstream line; adding +<revision> pins one exact app build. The one-token @ form only fires on a bare catalog source: a path, git URL, or archive keeps its @ untouched ([email protected]:... is unaffected). shc update <name> <version> / <name>@<version> accepts the same grammar. See Apps and deployments for the catalog’s version-retention policy.

There is no --addon flag. An add-on is named in the source token, and the add-on file supplies the vApp segment the operator never chose:

Terminal window
# The add-on file says `vapp: plugin`, so the vApp is not typed.
shc install nextcloud/talk
# `@<version>` rides the last segment.
shc install frappe/[email protected]
# An add-on that declares no `vapp:` uses the same spelling.
shc install <app>/<addon>
# With no --into the deployment name defaults to the token, which for an
# add-on already IS <host>/<instance> (-> nextcloud/talk above).
# --into names the HOST; the instance stays the add-on. A slash-free -s on
# a vApp add-on refuses (X400060ADNHST) and prints this line.
shc install nextcloud/talk --into nc # -> nc/talk
# An explicit --instance still wins: two instances, one add-on.
shc install nextcloud/talk --into nc --instance talk-eu

<app>/<X> names one of three things and the app decides which: an add-on (a file on disk), a <parent>/<vapp> instance, or, when the app publishes neither, <repo>/<app> (see Name the Repository). A name that is both a vApp and an add-on is refused (X400056ADNAMB), never guessed; the three-segment <app>/<vapp>/<addon> form disambiguates and is itself checked against the add-on’s declared vapp: (X400057ADNVAP). A malformed add-on token is X400063ADNTOK. See Add-ons.

shc update <host>/<instance>@<version> (vApp add-on) and shc update <name>@<version> (app-level) re-pin an installed add-on’s version, also with no flag. The rule is the recorded state, not the token’s punctuation: a deployment installed by naming an add-on takes the named version as the add-on’s. The cost is that such a deployment’s app version is no longer separately pinnable on update: it follows the catalogue; re-install to name both halves.

Install apps directly from a local filesystem path:

Terminal window
# From relative path
shc install ./apps/myapp --stack myapp
# From absolute path
shc install /home/user/apps/myapp --stack myapp
# With configuration
shc install ./apps/myapp --stack myapp --var [email protected]

Install apps directly from a git repository:

Terminal window
# From GitHub (HTTPS)
shc install https://github.com/user/myapp --stack myapp
# From GitLab
shc install https://gitlab.com/user/myapp --stack myapp
# From Bitbucket
shc install https://bitbucket.org/user/myapp --stack myapp
# From SSH URL
shc install [email protected]:user/myapp.git --stack myapp

Specify a branch, tag, or commit hash:

Terminal window
# From a specific tag
shc install https://github.com/user/myapp --ref v1.0.0 --stack myapp
# From a branch
shc install https://github.com/user/myapp --ref main --stack myapp
shc install https://github.com/user/myapp --ref feature/new-ui --stack myapp
# From a commit hash
shc install https://github.com/user/myapp --ref abc123def456 --stack myapp

For repositories containing multiple apps, specify the subdirectory:

Terminal window
# Install app from subdirectory
shc install https://github.com/user/monorepo --path apps/myapp --stack myapp
# Combined with ref
shc install https://github.com/user/monorepo --path apps/myapp --ref v2.0.0 --stack myapp

Provide authentication for private repositories:

Terminal window
# With GitHub personal access token
shc install https://github.com/user/private-app --token ghp_xxxxxxxxxxxx --stack myapp
# With GitLab access token
shc install https://gitlab.com/user/private-app --token glpat-xxxxxxxxxxxx --stack myapp

Note: Tokens are used only for the clone operation and are not stored.

FlagShortDescription
--stack-sDeployment name (the flag is --stack; defaults to the app name)
--environment-eEnvironment name
--whereNodes this deployment may run on. --node, --rule, and --fence are refused (X400242SELFLG)
--repo-rRepository name (if app exists in multiple repos)
--varSet configuration variable (key=value)
--exposeHow the deployment is reached from outside, repeatable: <outside>[+<option>...][@<where>][=<service>[:<container port>]]. <outside> is a port or a hostname with an optional path. No outside port means HTTP(S) through Traefik (wiki.example.com, wiki.example.com/docs=web:8080). An outside port is an L4 listener (5432, 5432+spread, 25+local, 514+udp+private, 5432@(edge=true), 5432@eu/hel, 5432@hz-lb=db). A hostname with an outside port is that listener plus a DNS record (db.example.com:5432=db, db.example.com:5432@hz-lb=db); a path on it is refused (X400495EXPPTH). See CLI symbols
--dns-providerDNS provider for dns-01 challenge
--refGit reference (branch, tag, or commit)
--pathSubdirectory path within repository
--tokenAuthentication token for private repos
--runtimeTarget runtime (docker, podman, incus, apple)
--storageStorage provider (e.g., ‘local’, ‘nfs’, ‘cephfs’)
--naming-exceptionRecord WHY this deployment keeps a name that is not the DNS label it serves; silences the naming warning and is reported by the app.deployment-naming diagnosis (shc doctor run --category app). A reason is required, and an empty value is refused. See Naming a deployment
--cpu-quotaPer-service CPU quota (service=value)
--memory-quotaPer-service memory quota (service=value)
--integrate-iIntegrate with an existing deployment (repeatable)
--from-backupRestore data from backup file after install
--quiet-qSuppress progress output

shc install also registers --auth (basic-auth credentials for private archives), but there is no archive install path to authenticate against: every archive source is refused with X400002VALINP before the credentials are read; see Archive sources. Packaged archives reach the platform through an app repo or shc backup import, never through shc install.

For the complete, always-current flag set, see the generated shc install page; this table is the curated subset.

shc install refuses a trailing ! on --var, --expose and -i/--integrate (X400002VALINP): the marker denotes a removal, and a fresh install has no persisted override to remove. It is an shc update grammar; see Removing a persisted override.

OTEL is a token, not a deployment of the app’s tenant. It wires the app’s traces and metrics (never logs: container stdout is collected platform-side already) into SHC’s telemetry fabric: the render injects the standard OTEL_EXPORTER_OTLP_* environment pointing at the system collector (collector.shc.internal), and the platform stamps shc.tenant, shc.stack, and shc.environment onto everything the app emits. The app itself is never told its tenant. The system collector is the collector stack of the master tenant, which shc init installs by default; while it has no replica the install warns X200182OTLNIL and the app’s telemetry has no destination. Works with any app whose runtime honours the OTel SDK environment variables; apps that don’t emit OTel data simply ignore the env. The edge persists like any other integration (shc update <name> -i otel! disconnects; it cannot be qualified with @env).

The --expose grammar is <outside>[+<option>...][@<where>][=<service>[:<container port>]] (see CLI symbols). <outside> is a port, or a hostname with an optional path. A value that is only digits is a port. A hostname must contain a letter or a dot. A hostname with an outside port is an L4 listener; a path on it (db.example.com:5432/x) is refused with X400495EXPPTH. Options and placement precede the target: for example, 36094+udp@(node=home01)=echo:9999. The first = outside parentheses separates the target. The = inside @(...) belongs to the node selector.

No outside port means HTTP(S) through Traefik:

  • --expose huly.example.com selects the deployment’s only ingress candidate.
  • --expose huly.example.com=nginx selects service nginx.
  • --expose huly.example.com=:80 selects container port 80.
  • --expose huly.example.com=nginx:80 selects service nginx, container port 80.
  • --expose example.com/v1=api:8080 also routes only the /v1 path prefix.
  • --expose app.example.com=web:8080, with the service selector web: side=blue, routes only to the replicas that match side=blue now.

For a route, SHC enumerates TCP container-port candidates from Compose expose and ports targets, applies the supplied selectors, and requires exactly one candidate.

The target may be a service or a service selector of the app. A service selector over labels other than group has no ports of its own, so the target names the container port, and some service of the app must declare it. A target that is neither is refused with X400498EXPTGT, which lists the app’s services and service selectors.

An entry that names neither a service nor a container port goes to the app’s default service and port. The default service is the one marked x-shc-primary (primary in shc.yaml), else the first service the file lists. The default port is the port the marker names, else that service’s first declared port (expose before ports). On whoami, --expose whoami.example.com and --expose 8080 both reach whoami:80. An entry that names a service or a port is resolved by that selector alone, and the default is not consulted.

An outside port is an L4 listener. +udp is UDP, and @<connection> sends it through that connection’s load balancer:

  • --expose 5432 publishes outside port 5432 to the app’s default service and port.
  • --expose 5432=db publishes it on service db.
  • --expose 5432=postgres, with the service selector postgres: role=primary:1, publishes it to whichever replica is primary now, and after a failover to the new one with no update. It needs a cluster that runs service VIPs (X400499EXPVIP).
  • --expose 8080=:80 publishes container port 80 on outside port 8080, selecting the service by its declared port.
  • --expose 8022=gitea:22 publishes container port 22 on outside port 8022.
  • --expose 53+udp=dns publishes UDP 53.
  • --expose 5432@hz-lb=db publishes through the hz-lb load balancer.
  • --expose db.example.com:5432=db publishes port 5432 and a DNS record for db.example.com.
  • --expose db.example.com:5432@hz-lb=db publishes that record at the hz-lb load balancer.
  • --expose git.example.com:8022=gitea:22 publishes container port 22 on outside port 8022, with a DNS record for git.example.com.
  • --expose 5432+spread sends a connection to any ready replica.
  • --expose '25+local=postfix-mailcow:25' answers only on the nodes that hold a ready postfix replica and never forwards, so postfix sees the client’s address.
  • --expose 514+udp+private=wazuh-manager:514 takes UDP 514 on each node’s private address only, never on a public one.
  • --expose '5432@(edge=true)' listens on the nodes whose labels match edge=true.
  • --expose 5432@eu/hel listens on the nodes in the location eu/hel.

+spread sends a connection to any ready replica. A publish without +spread prefers a replica on the node that accepted the connection. @(selector) is a label selector. A location path contains a slash. A name with no slash, @hel1, is a location when a node is in that location and no connection has the name. It is that connection’s load balancer when the name is a connection. A name that is both is refused with X409137PUBAMB. An L4 publish that names no @ follows the publish.listen selector, and every node when that key is unset.

Two deployments cannot listen on one port and protocol on one node. Install, update, and a label edit that would cause that are refused with X409136PUBOVR, which names the deployment that already listens and the nodes. On a cluster that runs service VIPs, a port published without a connection is an SHC listen rule on each listening node. The rendered compose has no ports: entry for it, so the port does not answer on 127.0.0.1 from the node itself. A port published through a connection (@<connection>) keeps its node-port publish on the placement node, bound to the node’s private address, which that connection’s load balancer targets. An app’s own ports: entries publish nothing there: the render declares their container ports, and the install warns with X200141PUBTPL naming the --expose that would publish each one.

An L4 entry with no container port targets the outside port number, and with no service the one service that exposes that port.

The old service@host spelling is refused with X400493EXPATR (an @ on a route has no meaning yet), and service:host does not parse (X400490EXPFMT). Write service=host.

DNS for a route follows the system ingress endpoint; a route carries no DNS target of its own. DNS for an L4 hostname comes from the tenant’s DNS connection and does not follow the system Traefik. @<connection> points the record at that connection’s load-balancer endpoints. A plain publish points it at the nodes that listen: exposure=internet uses each listening node’s public address, drops a private or loopback address, and defers with X200980DNSDEF when none is left. Any other exposure uses dns.lan_address, then dns.public_address, then each listening node’s underlay address. No hostname means no record. An L4 hostname another deployment already serves is refused with X409142PUBHST. db.example.com:5432! removes the same mapping as 5432!.

Install and update, including deployfile deployments, wait for each public provider-plane hostname to answer on every authoritative nameserver address. Queries go directly to literal IPs with recursion disabled. An unchanged name or a covering wildcard that already answers adds no polling delay.

The whole DNS readiness phase, including authority discovery, is bounded at 90 seconds. A timeout leaves the deployment successful with exit code 0 and a verdict warning: X200145DNSRDY names the host and pending nameservers, or X200146DNSAUT names the host and zone when discovery fails. The containers, records and routes remain in place. Check the zone’s delegation and nameservers, and allow outbound UDP and TCP port 53 for discovery. Provider publication failures retain their existing failure behavior.

  • An HTTP --expose (a hostname, no outside port) creates DNS records using the selected provider for the deployment scope. A hostname with an outside port does too, from the same tenant DNS connection. A bare outside port, with no hostname, creates no record. The L7 ladder below is for route hosts only.
  • Record target ladder (top wins; an L7 host’s DNS follows the SYSTEM traefik’s public L4 endpoint, and the workload’s own conn@ mappings never affect it). There is no per-host override rung: the host=target suffix is refused at parse time on EVERY path (X400995HSTTGT) and the persisted dns_targets map it fed is removed. An operator-fixed proxy endpoint threaded by a recover replay > for non-internet exposures only, dns.lan_address then the scoped dns.public_address config key (an ip or hostname; internet exposure never reads either key) > the system traefik’s web endpoint, inferred: a web conn@ mapping uses that load balancer’s endpoints (a still-provisioning VIP defers the write and the reconciler retries). Several mappings are chosen by the app’s location, and two edges with no single answer defer. With no web connection the placed node’s public address (internet exposure; a private/loopback IP is treated as absent) > the exposure-split last rung: exposure=internet with nothing public DEFERS (X200980DNSDEF). Internet DNS fails closed and never publishes a LAN/advertise address, while other exposures keep the LAN fallback (the nodes the persisted 80/443 listen rules name; with none recorded, the system Traefik placement node’s internal address; when that is indeterminable, the advertise address). Record types are auto-classified: IPv4 → A, IPv6 → AAAA, hostname → CNAME.
  • A public route’s certificate comes from the ACME provider once acme.* is set: over DNS-01 when a DNS connection of the tenant owns the hostname’s zone, over HTTP-01 otherwise. No flag picks the challenge.

Remove a deployment. Uninstall is always a full teardown: containers, volumes, and persistent data are all removed (there is no data-preserving mode). A safety backup is taken first; pass --no-backup to skip it.

Terminal window
shc uninstall nextcloud
shc uninstall nextcloud --environment prod
shc uninstall nextcloud --yes --no-backup

The deployment’s backup schedules, config values and kv entries go with it, so a later deployment of the same name starts without them. That covers its backup schedule at the deployment scope and at the stack scope for its environment, and its config values and kv entries at the deployment scope (--config-set writes there). Its stack-scope config values and kv entries go too once no other environment of the tenant runs the stack. Until then the deployments in those environments still read them, and they stay. The uninstall prints one line, removed with the deployment: ..., naming each key it removed and never a value, and -o json lists them under purged. If the purge fails the uninstall still succeeds, warns X200197OWNPRG and removes none of them.

Update a deployment in place: bump the app version, change variables, add or remove hosts and ports, adjust quotas, and rewire integrations. The version is a positional argument (there is no --version flag).

A bare shc update <name> replays the deployment’s own version pin. When the re-render reads the same app package and produces the compose the deployment already had, the result line says no change and names the package digest and the directory it was read from. To take a newer package, name the version: shc update <name> <version>. If the version you want is not offered, this node’s catalogue index may be stale; shc repo sync refreshes it and re-renders nothing.

Terminal window
# Re-render/re-deploy with current settings
shc update mystack
# Update to a specific version (repository apps)
shc update nextcloud 29.0.0
# Update configuration
shc update nextcloud --var new_setting=value
# Adjust per-service quotas and replica counts
shc update webapp --cpu-quota web=1.0 --memory-quota web=512Mi --scale web=3
FlagShortDescription
--varSet a variable override (key=value); key! removes it
--cpu-quotaPer-service CPU quota (service=value)
--memory-quotaPer-service memory quota (service=value)
--scalePer-service replicas, the only replica control: service=<n>, service=<n>@<location>,... or service=<n>/<kind>. The set sent replaces the stored set, so restate every service you keep
--exposeAdd or replace an exposure. hostname[/path]! removes a route, 5432! or 53+udp! removes a port, and a removal names the outside part only. A bare --expose '!' removes every route and every port the same command does not name. The old --route '!' cleared routes only
--integrate-iWire an integration ([plug=]provider[@env], plug=@connection); a bare <ref>! disconnects, and one token may drop several edges; see Removing a persisted override
--gated / --openToggle the Keycloak SSO gate
--fromRepoint the deployment at a new source (git URL or local path)
--refGit reference, with --from or against the existing git source
--pathSubdirectory, with --from or against the existing git source
--tokenAuthentication token for a private git source
--naming-exceptionRecord WHY this deployment keeps a name that is not the DNS label it serves; silences the naming warning and is reported by the app.deployment-naming diagnosis (shc doctor run --category app). A reason is required, and an empty value is refused. See Naming a deployment

Source repoint is wired end to end: the CLI sends --from / --ref / --path as the request’s source object and --token alongside it, and the update runner re-resolves the app directory from that source before re-rendering. A bare --ref or --path with no --from refreshes the deployment’s existing git source.

--var, --expose and -i/--integrate all persist as deployment state: a bare shc update <name> replays whatever the deployment was installed (or last updated) with. Removal is a trailing ! on the same flag that sets the value; there are no separate removal flags:

Terminal window
shc update myblog --var theme! # back to the app default
shc update myblog --expose blog.example.com! # drop a persisted route
shc update myblog --expose blog.example.com/promo! # drop one path route
shc update traefik --expose '80@hetzner!' # drop an LB port mapping
shc update nextcloud -i keycloak! # disconnect an integration

A -i disconnect token resolves to exactly one of three handles, tried in this precedence order; they are not alternatives tried together:

  1. the consumer plug: -i oidc!;
  2. the connection: -i aws-primary! (the @ sigil form, -i '@aws-primary!', works too);
  3. the provider deployment: -i keycloak!, the all-caps magic spelling -i KEYCLOAK!, or narrowed to one environment as -i keycloak@prod!.

The first handle that matches any live edge wins, and the token then drops every edge matching under that handle alone; the remaining handles are never consulted. A bare provider token is therefore a deployment-wide disconnect, not a single-edge one:

  • on a deployment wired oidc=keycloak and auth=keycloak, -i keycloak! drops both edges;
  • on m1=mail@prod and m2=mail@dev, -i mail! drops both.

Narrow it to one edge by naming the plug (-i m1!), or across environments with provider@env (-i mail@prod!). An env-qualified token matches only an edge that persisted with that environment: -i mail@prod! against a plain mail edge matches nothing and fails.

Because the plug is tried first, a plug whose name happens to equal a deployment name shadows the provider handle. On kc2=keycloak plus keycloak=keycloak, -i keycloak! resolves to the plug and drops only keycloak=keycloak; reach the other edge by its own plug (-i kc2!).

A token that matches no live edge is a loud no-op: the update proceeds and warns X200970RMVNOP with the wired edges, so re-running a disconnect that already ran succeeds. --strict-removals turns that warning into a failure (X400002VALINP). The marker rides the bare form only: -i plug=provider! is refused with X400002VALINP rather than guessed at.

To remove several at once, either repeat the flag or comma-join the tokens: --expose and -i comma-split, so both spellings arrive as separate removals:

Terminal window
shc update myblog --expose a.example.com! --expose b.example.com!
shc update myblog --expose 'a.example.com!,b.example.com!'

Notes:

  • A ! inside a --var value is never a marker. --var key=value is structurally a set because of the =, so --var password=hunter2! sets the password to hunter2!.
  • Quoting is only a shell concern, and only at an interactive bash or zsh prompt, where ! followed by a comma is a history reference. Use single quotes there. Double quotes do not help, because zsh expands history inside them. Scripts, CI and the Terraform provider run non-interactive shells with history expansion off entirely, so no quoting is needed.
  • The marker is stripped by the CLI’s parse layer before any spec parser runs, so a ! is never legal inside a hostname, route path, port or provider name.
  • shc install refuses the marker outright (X400002VALINP): there is no persisted state to remove on a fresh install.
  • A -i 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. It removes no provider-side resource: the jobs.unintegration: phase authored in *.socket.yaml / *.plug.yaml has no runner anywhere in the tree. The job scanner lists it (shc job ls) but nothing executes it, on disconnect or on uninstall, so a keycloak edge’s OIDC client is never deleted by either verb and must be cleaned up by hand. A disconnect also does not revoke the sub-credential minted behind a connection-backed edge (-i s3=@aws-primary); that revoke does exist, but it is wired to uninstall only (and is skipped there for a same-key move, which hands the live mint to the moved deployment), so a disconnect leaves the scoped IAM user behind.

List deployments:

Terminal window
shc ls
shc ls --tenant acme --environment prod
shc ls --status running
shc ls --output json

The output includes the source column showing where each deployment was installed from:

  • repo:appname - From repository catalog
  • git:url - From git URL
  • path:/path - From local path

View deployment + service health (replaces the removed shc ps):

Terminal window
shc status nextcloud
shc -o json status nextcloud

Naming a deployment: the name is the DNS label

Section titled “Naming a deployment: the name is the DNS label”

A deployment is named for its job, and the word for its job is the first label of the hostname it answers on. docs runs paperless at docs.corp.bitspur.com. oncall runs goalert at oncall.corp. workflows runs activepieces, projects runs huly, photos runs immich, pdf runs stirling. The two strings an operator types and visits are the same word, in both directions.

App names are unaffected. The catalog keeps paperless, goalert, activepieces, immich. It is the DEPLOYMENT name (the --stack) that follows the hostname:

Terminal window
shc install paperless --stack docs --expose docs.corp.example.com
shc install nextcloud --stack cloud --expose cloud.corp.example.com
shc install glitchtip --stack errors --expose errors.corp.example.com

Why the DNS label, and not a good word for what the app does

Section titled “Why the DNS label, and not a good word for what the app does”

Because the label is already deployed. It is in DNS, it is on the certificate, and it is what the browser has bookmarked, so it can be checked, and a name invented at the desk cannot. A Nextcloud deployment serving cloud.corp.example.com is named cloud, not files: files is a perfectly good description of what Nextcloud does, which is exactly what makes it dangerous. Picking a fresh purpose word swaps one mismatch for another and reads like progress.

SHC warns; it never refuses. A misnamed deployment serves traffic correctly, so the rule is cosmetic and a gate over it would be routed around and then deleted.

The warning fires at the moments the name is still cheap to change (a first install, a shc rename, or a change to the --expose set), and names the target and the evidence:

warning [X200967NAMDNS]: deployment corp/nextcloud@prod is named for its
software, not its job: it serves cloud, so the convention name is cloud …

A bare shc update that replays the same name and the same routes is silent. That is deliberate: with drifted deployments live on a real estate, a check that spoke on every re-render would be filtered within a week.

When a deployment serves several hostnames it is aligned the moment ONE of them carries its name: matrix also serving chat/meet is findable by its own name and is not drift. When several labels are served and none is the name, you get X200968NAMAMB with the CANDIDATE SET and no suggestion. SHC will not pick a primary out of {sbom, sbom-api} for you; a confidently wrong rename of a live deployment costs a window.

The install-time warning only ever reaches a deployment somebody is installing, renaming or re-routing. Everything that drifted before the rule existed is invisible to it, so there is a standing sweep, the app.deployment-naming diagnosis. shc doctor run selects by category, not by diagnosis, so run the app category:

Terminal window
shc doctor run --category app

Its app.deployment-naming row reports at INFO (nothing is broken), names every deployment with its suggested target, and lists the recorded exceptions with their reasons.

Terminal window
shc rename nextcloud cloud --yes && shc update cloud

Run them together. A rename does not re-render Traefik, and the ingress upstreams are literal container names, so a shc rename without the following shc update leaves the deployment unreachable. Rebind every consumer that held the old provider_stack_name in the same window:

Terminal window
shc integration ls -t corp -e prod # who pointed at the old name
shc update <consumer> -i <plug>=cloud # repoint, same window

Some deployments genuinely should differ: one fronting several unrelated hostnames, or a name held for continuity across a migration. Say so on the deployment:

Terminal window
shc update mailcow --naming-exception "fronts mail.bitspur.com and \
mail.promanager.vip for two tenants; neither label names the deployment"

The reason is persisted on the deployment and reported back by the doctor sweep, so the exception reads as a decision on the record rather than as an absence of drift. A reason is required: --naming-exception "" is refused, because an exemption whose justification is empty is indistinguishable from the drift it excuses. A bare update replays whatever is already recorded; you do not restate it every time.

--naming-exception is available on both shc install and shc update.


Rename a deployment:

Terminal window
shc rename nextcloud cloud --yes && shc update cloud # ALWAYS as one operation

A rename does not re-render Traefik and the ingress upstreams are literal container names, so shc rename and shc update are one operation: splitting them leaves the deployment unreachable. The new name should be the DNS label the deployment answers on; see Naming a deployment above.

A consumer binds its provider by name, and a rename rebinds it: once the deployment has started under its new name, the rename updates each deployment that consumes it with -i <plug>=<new name>, in the same operation, and shc integration ls names the new name. A consumer in another tenant cannot be rebound, so the rename refuses with X409675CLNRNC, names that consumer and its plug, and stops nothing. A rename leaves nothing at the old name.

To place a deployment on another node, change --where: see Relocating a deployment. --node, --rule, and --fence are refused (X400242SELFLG).

Duplicate a deployment:

Terminal window
shc clone myapp myapp-clone
shc clone myapp myapp-prod --where 'location=hetzner/hel1'
shc clone myapp myapp-test --environment staging

Validate app definitions:

Terminal window
shc validate myapp
shc validate /path/to/app.yaml
shc validate ./apps/myapp
shc validate https://github.com/user/myapp