App commands
shc install
Section titled “shc install”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.
Basic Installation (from Repository)
Section titled “Basic Installation (from Repository)”shc install nextcloudshc install nextcloud --stack cloud --environment prodshc install wordpress --stack blog --var title="My Blog"shc install keycloak/realm --into keycloak --instance test-realmshc install nextcloud --expose cloud.example.com --dns-provider cloudflareName the Repository
Section titled “Name the Repository”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:
shc install frappe 15.118 -r bitspur # the same installshc repoint photos apps/immichThe 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.
Install a Pinned Version
Section titled “Install a Pinned Version”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:
# Positional: <app> <version>shc install nextcloud 30
# One-token: <app>@<version>, peeled off the source before catalog lookupshc install nextcloud@30
# Pin an exact app revision: <app>@<version>+<revision>shc install nextcloud@30+2A 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.
Install an Add-on
Section titled “Install an Add-on”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:
# The add-on file says `vapp: plugin`, so the vApp is not typed.shc install nextcloud/talk
# `@<version>` rides the last segment.
# 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 from Local Path
Section titled “Install from Local Path”Install apps directly from a local filesystem path:
# From relative pathshc install ./apps/myapp --stack myapp
# From absolute pathshc install /home/user/apps/myapp --stack myapp
# With configurationInstall from Git URL
Section titled “Install from Git URL”Install apps directly from a git repository:
# From GitHub (HTTPS)shc install https://github.com/user/myapp --stack myapp
# From GitLabshc install https://gitlab.com/user/myapp --stack myapp
# From Bitbucketshc install https://bitbucket.org/user/myapp --stack myapp
# From SSH URLInstall with Git Reference
Section titled “Install with Git Reference”Specify a branch, tag, or commit hash:
# From a specific tagshc install https://github.com/user/myapp --ref v1.0.0 --stack myapp
# From a branchshc install https://github.com/user/myapp --ref main --stack myappshc install https://github.com/user/myapp --ref feature/new-ui --stack myapp
# From a commit hashshc install https://github.com/user/myapp --ref abc123def456 --stack myappInstall from Monorepo Subdirectory
Section titled “Install from Monorepo Subdirectory”For repositories containing multiple apps, specify the subdirectory:
# Install app from subdirectoryshc install https://github.com/user/monorepo --path apps/myapp --stack myapp
# Combined with refshc install https://github.com/user/monorepo --path apps/myapp --ref v2.0.0 --stack myappInstall from Private Repository
Section titled “Install from Private Repository”Provide authentication for private repositories:
# With GitHub personal access tokenshc install https://github.com/user/private-app --token ghp_xxxxxxxxxxxx --stack myapp
# With GitLab access tokenshc install https://gitlab.com/user/private-app --token glpat-xxxxxxxxxxxx --stack myappNote: Tokens are used only for the clone operation and are not stored.
Install Flags
Section titled “Install Flags”| Flag | Short | Description |
|---|---|---|
--stack | -s | Deployment name (the flag is --stack; defaults to the app name) |
--environment | -e | Environment name |
--where | Nodes this deployment may run on. --node, --rule, and --fence are refused (X400242SELFLG) | |
--repo | -r | Repository name (if app exists in multiple repos) |
--var | Set configuration variable (key=value) | |
--expose | How 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-provider | DNS provider for dns-01 challenge | |
--ref | Git reference (branch, tag, or commit) | |
--path | Subdirectory path within repository | |
--token | Authentication token for private repos | |
--runtime | Target runtime (docker, podman, incus, apple) | |
--storage | Storage provider (e.g., ‘local’, ‘nfs’, ‘cephfs’) | |
--naming-exception | Record 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-quota | Per-service CPU quota (service=value) | |
--memory-quota | Per-service memory quota (service=value) | |
--integrate | -i | Integrate with an existing deployment (repeatable) |
--from-backup | Restore data from backup file after install | |
--quiet | -q | Suppress 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.
The telemetry integration: -i otel=OTEL
Section titled “The telemetry integration: -i otel=OTEL”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).
Exposure
Section titled “Exposure”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.comselects the deployment’s only ingress candidate.--expose huly.example.com=nginxselects servicenginx.--expose huly.example.com=:80selects container port80.--expose huly.example.com=nginx:80selects servicenginx, container port80.--expose example.com/v1=api:8080also routes only the/v1path prefix.--expose app.example.com=web:8080, with the service selectorweb: side=blue, routes only to the replicas that matchside=bluenow.
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 5432publishes outside port 5432 to the app’s default service and port.--expose 5432=dbpublishes it on servicedb.--expose 5432=postgres, with the service selectorpostgres: 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=:80publishes container port 80 on outside port 8080, selecting the service by its declared port.--expose 8022=gitea:22publishes container port 22 on outside port 8022.--expose 53+udp=dnspublishes UDP 53.--expose 5432@hz-lb=dbpublishes through thehz-lbload balancer.--expose db.example.com:5432=dbpublishes port 5432 and a DNS record fordb.example.com.--expose db.example.com:5432@hz-lb=dbpublishes that record at thehz-lbload balancer.--expose git.example.com:8022=gitea:22publishes container port 22 on outside port 8022, with a DNS record forgit.example.com.--expose 5432+spreadsends 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:514takes UDP 514 on each node’s private address only, never on a public one.--expose '5432@(edge=true)'listens on the nodes whose labels matchedge=true.--expose 5432@eu/hellistens on the nodes in the locationeu/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!.
DNS and TLS Behavior
Section titled “DNS and TLS Behavior”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: thehost=targetsuffix is refused at parse time on EVERY path (X400995HSTTGT) and the persisteddns_targetsmap it fed is removed. An operator-fixed proxy endpoint threaded by a recover replay > for non-internet exposures only,dns.lan_addressthen the scopeddns.public_addressconfig key (an ip or hostname; internet exposure never reads either key) > the system traefik’s web endpoint, inferred: a webconn@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=internetwith 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.
shc uninstall
Section titled “shc uninstall”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.
shc uninstall nextcloudshc uninstall nextcloud --environment prodshc uninstall nextcloud --yes --no-backupThe 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.
shc update
Section titled “shc update”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.
Basic Update
Section titled “Basic Update”# Re-render/re-deploy with current settingsshc update mystack
# Update to a specific version (repository apps)shc update nextcloud 29.0.0
# Update configurationshc update nextcloud --var new_setting=value
# Adjust per-service quotas and replica countsshc update webapp --cpu-quota web=1.0 --memory-quota web=512Mi --scale web=3Update Flags
Section titled “Update Flags”| Flag | Short | Description |
|---|---|---|
--var | Set a variable override (key=value); key! removes it | |
--cpu-quota | Per-service CPU quota (service=value) | |
--memory-quota | Per-service memory quota (service=value) | |
--scale | Per-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 | |
--expose | Add 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 | -i | Wire an integration ([plug=]provider[@env], plug=@connection); a bare <ref>! disconnects, and one token may drop several edges; see Removing a persisted override |
--gated / --open | Toggle the Keycloak SSO gate | |
--from | Repoint the deployment at a new source (git URL or local path) | |
--ref | Git reference, with --from or against the existing git source | |
--path | Subdirectory, with --from or against the existing git source | |
--token | Authentication token for a private git source | |
--naming-exception | Record 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.
Removing a persisted override
Section titled “Removing a persisted override”--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:
shc update myblog --var theme! # back to the app defaultshc update myblog --expose blog.example.com! # drop a persisted routeshc update myblog --expose blog.example.com/promo! # drop one path routeshc update traefik --expose '80@hetzner!' # drop an LB port mappingshc update nextcloud -i keycloak! # disconnect an integrationA -i disconnect token resolves to exactly one of three handles, tried in
this precedence order; they are not alternatives tried together:
- the consumer plug:
-i oidc!; - the connection:
-i aws-primary!(the@sigil form,-i '@aws-primary!', works too); - 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=keycloakandauth=keycloak,-i keycloak!drops both edges; - on
m1=mail@prodandm2=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:
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--varvalue is never a marker.--var key=valueis structurally a set because of the=, so--var password=hunter2!sets the password tohunter2!. - 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 installrefuses the marker outright (X400002VALINP): there is no persisted state to remove on a fresh install.- A
-idisconnect drops the edge from the re-rendered compose, from the deployment’s persisted state and from theintegrationtable, so it stops being replayed. It removes no provider-side resource: thejobs.unintegration:phase authored in*.socket.yaml/*.plug.yamlhas 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.
shc ls
Section titled “shc ls”List deployments:
shc lsshc ls --tenant acme --environment prodshc ls --status runningshc ls --output jsonThe output includes the source column showing where each deployment was installed from:
repo:appname- From repository cataloggit:url- From git URLpath:/path- From local path
shc status
Section titled “shc status”View deployment + service health (replaces the removed shc ps):
shc status nextcloudshc -o json status nextcloudNaming 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:
shc install paperless --stack docs --expose docs.corp.example.comshc install nextcloud --stack cloud --expose cloud.corp.example.comshc install glitchtip --stack errors --expose errors.corp.example.comWhy 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.
What SHC does about it
Section titled “What SHC does about it”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 itssoftware, 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.
Finding the ones that already drifted
Section titled “Finding the ones that already drifted”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:
shc doctor run --category appIts 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.
Renaming: one operation, never two
Section titled “Renaming: one operation, never two”shc rename nextcloud cloud --yes && shc update cloudRun 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:
shc integration ls -t corp -e prod # who pointed at the old nameshc update <consumer> -i <plug>=cloud # repoint, same windowRecording an exception
Section titled “Recording an exception”Some deployments genuinely should differ: one fronting several unrelated hostnames, or a name held for continuity across a migration. Say so on the deployment:
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.
shc rename
Section titled “shc rename”Rename a deployment:
shc rename nextcloud cloud --yes && shc update cloud # ALWAYS as one operationA 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).
shc clone
Section titled “shc clone”Duplicate a deployment:
shc clone myapp myapp-cloneshc clone myapp myapp-prod --where 'location=hetzner/hel1'shc clone myapp myapp-test --environment stagingshc validate
Section titled “shc validate”Validate app definitions:
shc validate myappshc validate /path/to/app.yamlshc validate ./apps/myappshc validate https://github.com/user/myapp