Skip to content
SHC Docs

shc deploy

deploy the deployments declared in one or more .shc.yaml deployfiles

Deploy from a .shc.yaml deployfile: a declarative manifest naming the app, what it exposes, the --var wiring and the environments a stack deploys to. A deployfile is to shc what a helmfile is to helm.

The verb is install-or-update: a (stack, environment) that does not exist yet is installed from the app directory, one that does is updated with the declared hosts re-asserted. Running it repeatedly is the normal case: the pipeline that runs it is the reconciler.

The file is the deployment’s whole desired state. An update converges to it: every route and port, integration, --var override, operator label, where and prefer the file does not name is removed, a hand-added one included, and a file with no expose: means no routes and no ports. The routes an app declares behind a host (x-shc-path) come with that host.

A file names one source: app: for an app directory in this checkout (an app repo deploying what it just built), catalog: for a catalogue app, optionally with repo: and version: (an estate deploying something it does not build), or git: for a git remote, its url, the ref it renders and the path that holds the app (an estate deploying an app from its own repo). A deployment that records another source is repointed onto the file’s before its update. An estate file can also name its tenant:, wire the deployment to its neighbours with integrate: (a map of consumer plug to provider), and set the SSO gate with gated:.

expose: takes the --expose grammar, routes and ports alike. Each hostname is written for prod and fans out per environment on the convention the GitLab CI generator uses: app.example.com is app.dev.example.com in dev, inside the environment’s DNS base, placed the same way in test or any other environment, .review.app.example.com in review (needs --slug), and as written in prod. The zone’s own apex is dev.example.com in dev. A bare port renders as written everywhere. There is no domain: key, and a file carrying one is refused. The DNS zone the first hostname lives in gives the environment’s DNS base, dev.example.com in dev and example.com in prod: the longest zone of the daemon’s public DNS connections, or the hostname’s registrable domain when no connection holds it or no daemon is asked, and the plan says which. The deployment records that base, and its hosts directly under it that share one address publish one wildcard and one claim. ${VAR} references in the file resolve from --env-file, the process environment and --set, in that order of increasing precedence; an undefined variable is refused rather than rendered as an empty value.

vars: is a tree, as an app’s vars.yaml is: postgres: {image: {tag: 16}} sets what --var postgres.image.tag=16 sets. A key with a dot in it is refused. A list is one var holding its JSON: roleKeys: [eng, ops] sets what --var 'roleKeys=["eng","ops"]' sets.

storage: sizes the volumes, one entry per volume: pgdata-1: 20Gi, or pgdata-1: hcloud:20Gi to name the backend too. Each renders one --storage, as on shc install. --storage on the command line adds to them, and for a volume both name the flag wins. An update sizes the volume as shc update --storage does and keeps the backend its install chose.

scale: maps service or group names to --scale values, as strings or integer counts. Every deploy passes them to install or update. A name removed from the map keeps its stored scale.

quota: maps a service to its cpu: and memory: quota, as --cpu-quota and --memory-quota take them: web: {cpu: "0.5", memory: 512M}. Every deploy passes them to install or update, so they land in the deployment’s resource overrides. A service or axis removed from the map keeps its stored quota.

addons: lists the vApp add-ons the deployment carries, otpmanager or [email protected], on a catalog: file. After the deployment has deployed, each is installed into it in file order, as shc install <catalog>/<add-on> --into <stack>, and one already there is updated to its version, or the catalogue’s newest when the file pins none. The plan prints each add-on’s step after its deployment’s.

An environment block may carry app:, vars:, scale:, quota:, integrate: and connections: of its own. Its app replaces the file’s for that environment, and the others merge key by key over the file’s, the environment’s entry winning, so a review deployment can be a thinner app, seeded, and only staging and prod bind a CDN bucket. An environment adds or replaces an entry and never removes one: a plug only some environments bind is named in their blocks alone. Nothing else differs per environment: stack: and tenant: are the deployment’s identity.

--dry-run is the plan and changes nothing. For each deployment it prints install, no changes, or the update’s changes against what runs: the app digest it would move to, vars by key (a secret’s value never shown), integrations, routes with the app’s own paths, ports, where and prefer, labels and volume sizes, removals first. It exits 0 when nothing would change and 3 when something would. With no cluster named it needs no daemon and prints the resolved argv and variables instead, so a deployfile is reviewable from a laptop. Logged in to a cluster, given a socket, or run on a cluster node, it asks that daemon, and fails when it cannot.

An app: directory on this machine goes to a daemon on another machine as an upload, which the cluster keeps by its digest. A catalog: app travels by name.

Several deployfiles deploy as a set: -f repeated, or -f a directory, which reads every *.shc.yaml directly inside it. Deployments start at once, except that one whose integrate: names another deployment of the set (same tenant and environment) waits until that one has deployed. A deployment whose provider failed never starts, and the first failure stops every deployment not yet started unless --keep-going is given. Integrate edges that form a cycle, and two files naming one deployment, are refused before anything deploys.

shc deploy -f <file.shc.yaml|directory> -e <environment> [flags]
shc deploy -f deploy/ioverse.shc.yaml -e dev
shc deploy -f deploy/ioverse.shc.yaml -e review --slug feat-login-42
shc deploy -f deploy/ -e prod # every *.shc.yaml in deploy/, as one set
shc deploy -f deploy/postgres.shc.yaml -f deploy/gitea.shc.yaml -f deploy/wiki.shc.yaml -e prod # gitea integrates postgres, so it waits for it; wiki starts at once
shc deploy -f deploy/ioverse.shc.yaml -e dev --dry-run # the plan, touches nothing
shc deploy -f deploy/ioverse.shc.yaml -e dev --env-file .env --set CI_COMMIT_SHORT_SHA=abc1234
--dry-run print the plan, what each deployment's install or update would change, and change nothing; exits 3 when something would change
--env-file stringArray file of KEY=VALUE interpolation values (repeatable; the process environment and --set beat it)
-e, --environment string environment to deploy (must be declared in the deployfile)
-f, --file stringArray deployfile, or a directory of *.shc.yaml deployfiles (repeatable); deployments start at once, except one whose integrate: names another deployment in the set, which waits for it
-h, --help help for deploy
--keep-going after a failure, still start every deployment that does not wait on a failed one (still exits non-zero)
--set stringArray interpolation value (KEY=VALUE); beats both --env-file and the environment
--slug string review-app slug; the review host is <slug>.review.<host>, and a slug past 56 bytes is cut to fit an environment name, the same for every deployfile
--storage stringArray volume storage, repeatable, as on shc install: <backend>, <volume>=<size> or <volume>=<backend>:<size>; a volume named here outranks the deployfile's storage: entry for it; an update sizes the volume and keeps the backend its install chose
--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)
-s, --stack string stack name (default: $SHC_STACK)
-t, --tenant string tenant name (default: $SHC_TENANT)
-v, --verbose verbose output (default: $SHC_VERBOSE)
  • shc - Selfhosted Cloud CLI