Skip to content
SHC Docs

shc install

install an application

Install an app as a deployment. The source accepts an app catalog name, an /, a / instance, a git URL, or a local path; when no version is given, latest is used. To bring a stack up from an archive, name the app and pass the archive to --from-backup (shc install postgres -s mydb --from-backup /var/lib/shc/mydb.bak). A .bak/.bkg path is not accepted as the positional source.

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.

An install whose replicas do not all read ready fails and rolls back. A replica that failed with a non-zero exit 3 times over at least 3 minutes without reading ready, counted from when every service it runs after reads ready, ends it at once, naming the replica, its exit and, on the node running the install, its last log line (X409783PODCRS). Otherwise it ends once its 15 minute settle window passes, counted from when its images are pulled and again each time a replica moves on (X504798PODSET). A replica moves on at most three times (bound, started, ready), so once its images are pulled an install of N replicas ends within 15 x (3N + 1) minutes. While images are pulled it goes on as long as one pull ends within 30 minutes of the last (X504799PODPLS). A failed install’s rollback then has 10 minutes, and the deployment stays taken until it ends.

A slash names something inside an app when the app publishes it, and a repo otherwise:

/ an add-on: shc install nextcloud/deck. The add-on file declares its own vapp, so you never type the middle segment, and the instance defaults to the add-on’s name. Pin with /@. / a vapp instance, addressed --into --instance . / the app from that repo, when no app claims the token and is a registered repo, or --stack is slash-free: community/[email protected] installs what plane 25.1 -r community does, under stack plane.

A name that is both a vapp and an add-on is refused, never guessed; spell it // to disambiguate. When several registered repos carry the same app name, the highest repo priority wins; name one with / or -r/--repo. A / and an -r/--repo naming two different repos are refused (X400076REPTWO).

The deploy runs asynchronously on the daemon and this command follows its progress until every service settles (use --quiet to suppress the stream). Variables (--var), resource quotas (--cpu-quota/ --memory-quota), ingress (--expose), and integrations (--integrate) are applied at render time. New installs land in the “prod” environment unless -e/--environment names another, and so does every other verb that addresses one deployment (exec, logs, backup, clone, stop/start/restart, uninstall), so a bare install and a bare anything-else reach the same stack. On an estate with no licence and no trial, that environment is “default”. SHC’s own -t master tenant always resolves “default”. --from-backup replays a backup’s data into the fresh deployment once the install completes. --public exposes the deployment to the internet; the default is LAN-only and enforced (Traefik ipAllowList, deployment-scoped lanEnforcement=allowlist). --gated puts Keycloak SSO in front of it.

The CLI never prompts. An install runs what the flags state, at a terminal and in a pipeline alike, and a required variable nobody supplied is a refusal that names every one of them at once and prints the command that supplies them (X400419VARMIS). Pass --interactive to open the variables form instead and be walked through it; shc update carries the same flag with the same meaning. The HUD stays the guided surface either way.

shc install <app>[/<addon|vapp>][@<version>] | <repo>/<app>[@<version>] [<version>] [flags]
shc install nextcloud
shc install nextcloud 30 # pin an upstream version (positional)
shc install nextcloud@30 # same pin, one token
shc install nextcloud@30+2 # pin an exact app revision
shc install plane -r community # name the repo (overrides priority)
shc install nextcloud/talk # a vapp instance of a parent app
shc install community/[email protected] # <repo>/<app>@<version>: the repo inside the token
shc install nextcloud -s cloud -e staging --var [email protected]
shc install nextcloud --where location=hel1 --where db:location=nbg1
shc install https://github.com/acme/widget --ref v2.1.0 --path deploy
shc install plane --expose plane.example.com=web:8080 --gated --from-backup ./plane.bak
--acme-provider string override ACME provider (which named CA issues public certs; blank = acme.default)
--auth string basic auth credentials for private archives
-c, --config-set stringArray deployment-scoped config row: key=value, same grammar as --var (a key! removal is refused here: a fresh install has no row to remove)
-C, --connection strings bind a declared connection: name=connection (bare connection ok when the app declares exactly one)
--cpu-quota strings per-service CPU quota (service=value); 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 to install into (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) (default "prod")
--expose strings publish out: <port|hostname[:port][/path]>[+option...][@where][=<service>[:<container port>]] (repeatable)
--force allow --ttl against a protected environment (prod)
--from-backup string restore data from backup after install
--gated require Keycloak SSO in front of the app
-h, --help help for install
--instance string instance name of a vdeployment under --into
-i, --integrate strings integrate with provider
-I, --interactive open the variables form (off by default: the CLI installs what the flags state and refuses when a required variable is missing)
--into string deployment a vdeployment attaches to
--label stringArray operator label: key=value sets, key! removes, ! clears every operator label (repeatable)
--memory-quota strings per-service memory quota (service=value); 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
--no-rollback skip rollback on failure
--no-wait return without waiting for the containers to report healthy
--open no SSO gate; rely on the app's own auth (the default)
--path string subdirectory path within the repository
--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)
--profile strings compose profiles to run, comma-separated or repeated: a service naming one of them runs, one naming none always runs
--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 and enforced)
-q, --quiet suppress progress output
--ref string git reference for git URL sources
-r, --repo string resolve the app from this repository (overrides repo priority)
--runtime string target runtime (docker|podman|incus|apple)
--scale stringArray replicas per service, or members per group: <name>=<n>, <name>=<n>@<location>[,<n>@<location>...] or <svc>=<n>/<kind> (repeatable)
--secrets-password stringArray candidate password to decrypt --from-backup's secrets bundle (repeatable; tried after this cluster's vault master)
--secrets-password-file stringArray file of newline-separated candidate passwords for --from-backup (repeatable). Also reads $SHC_SECRETS_PASSWORDS / $SHC_SECRETS_PASSWORD_FILES
-s, --stack string stack name
--storage stringArray storage for the deployment's volumes, repeatable: <backend> or node puts every volume there, <volume>=<size> sizes one volume, <volume>=<backend>:<size> sets both; sizes take Ki, Mi, Gi, Ti, K, M, G or T
--token string authentication token for private git or archives
--ttl string lease duration (e.g. 72h); the deployment auto-uninstalls once it expires unless renewed with 'shc lease renew'
--unprotected clear the deployment's protection flag
--var stringArray variable override (key=value)
--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)
--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