Skip to content
SHC Docs

Copies and deployfiles

A clone is a second deployment made from a running one: its app, its variables, its data and its secrets. The source keeps running. --dry-run prints the plan and changes nothing.

home01
$ shc clone notebook notecopy --dry-run
...
$ shc clone notebook notecopy --yes --quiet
...
$ shc exec -s notecopy -S notes -- wc -l /srv/notes/log
...

The copy is placed by the source’s own rules, here where: node=home01; --prefer and --where add to them. It can land in another environment of the same name, and on a named runtime. constraint explain shows the rules the copy carries.

home01
$ shc clone notebook notebook --target-environment staging --prefer node=home01 --runtime docker --yes
...
$ shc constraint explain -s notebook -e staging
...
$ shc ls
...

A deployment connected to others is cloned with them. --all-connections takes the deployments one integration away, --closure every one reachable, and --rename gives each copy its name. notebook connects to nothing, so the plan holds notebook alone.

home01
$ shc clone notebook notecopy2 --all-connections --closure --rename notebook=notecopy2 --dry-run
...
$ shc uninstall notecopy --yes
...
$ shc uninstall notebook -e staging --yes
...

Two things a clone takes that this cluster has one of: a tenant and a storage backend.

explained, not walked: the learning cluster has one tenant and one storage backend
$ shc clone notebook notebook --target-tenant acme --storage nfs --yes

A deployfile is a deployment written down: the app, its variables, the hostnames it answers on and the environments it goes to. shc deploy installs what does not exist yet and updates what does, so running it again is the normal case; a pipeline that runs it on every commit keeps the cluster where the file says.

~/learn/notebook.shc.yaml
stack: notebook
app: learn/notebook
expose:
- notes.learn.test=page:80
environments:
dev: {}

app is the app’s directory, relative to where shc deploy runs. expose takes what --expose takes. A hostname is written as prod serves it and moves with the environment: dev.notes.learn.test for dev, notes.learn.test for prod. The file is the deployment’s whole desired state: a route, variable, integration or label it does not name is removed on the next deploy.

--dry-run is the plan: install, no changes, or each change the update would make against what runs. It exits 3 when it would change something and 0 when it would not, so a pipeline can tell drift from a no-op.

home01
$ shc deploy -f learn/notebook.shc.yaml -e dev --dry-run
...
Plan: 1 to install, 0 to update, 0 unchanged.
$ shc deploy -f learn/notebook.shc.yaml -e dev
...
$ shc deploy -f learn/notebook.shc.yaml -e dev --keep-going
...
home01
$ curl -sk --resolve dev.notes.learn.test:443:127.0.0.1 https://dev.notes.learn.test/
...

${NAME} in a deployfile is read from --env-file, the environment and --set, each beating the one before, so a pipeline passes its commit or a review slug without editing the file. An undefined name is refused.

~/learn/notebook.env
NOTES_VERSION=1.0.0
~/learn/notebook.shc.yaml
stack: notebook
app: learn/notebook
vars:
release: ${NOTES_VERSION}
expose:
- notes.learn.test=page:80
environments:
dev: {}
home01
$ shc deploy -f learn/notebook.shc.yaml -e dev --env-file learn/notebook.env --dry-run
...
Plan: 0 to install, 1 to update, 0 unchanged.
$ shc deploy -f learn/notebook.shc.yaml -e dev --set NOTES_VERSION=1.0.1 --dry-run
...
Plan: 0 to install, 1 to update, 0 unchanged.
$ shc uninstall notebook -e dev --yes
...

A review environment gets a host of its own, <slug>.review.<host>, for a branch under review; --storage picks the backend of a first install.

explained, not walked: a review app needs a branch and a second storage backend
$ shc deploy -f learn/notebook.shc.yaml -e review --slug feat-login-42 --storage nfs

-f can be given more than once, or name a directory, which means every *.shc.yaml directly inside it. The files deploy as one set. Every deployment starts at once, except one whose integrate: names another deployment of the set in the same tenant and environment: that one waits until its provider has deployed.

deploy/postgres.shc.yaml deploys the catalogue’s postgres:

stack: postgres
catalog: postgres
environments:
prod: {}

deploy/gitea.shc.yaml connects gitea’s postgres plug to it:

stack: gitea
catalog: gitea
expose:
- git.example.com
integrate:
postgres: postgres
environments:
prod: {}
explained, not walked: this ladder builds notebook alone, and a set needs a second app
$ shc deploy -f deploy/ -e prod --dry-run
$ shc deploy -f deploy/ -e prod

The dry run prints waits on postgres under gitea. postgres starts first and gitea once postgres is healthy; a third file that names neither would start beside postgres. Each deployment gets its own block, live on a terminal and printed as it settles in a pipe.

If postgres fails, gitea never starts, and the run ends with one line per deployment: deployed, failed, or not started and why. Without --keep-going the first failure also keeps every deployment that has not started yet from starting; with it, anything that does not wait on a failure still starts. -o json prints one document for the set, a row per deployment with its status, waits_on, started_at and finished_at.

Two files that name one deployment are refused before anything deploys (X400428DPFSET), and so are integrate: lines that wait on each other in a cycle (X400427DPFCYC), the dry run included.

A move or a rename killed half way leaves a record on the node it ran on. The daemon reverts an interrupted move and finishes an interrupted rename when it starts again; what it will not do by itself is listed here with the command that does it. The list is this node’s alone.

home01
$ shc interrupted
...

A move killed after its source was torn down is one the daemon will not revert: the target may hold the only running copy. shc finish-forward finishes it, with the operation id shc interrupted lists. It reads the target’s health and the bytes it holds again before it removes anything else, and refuses if it cannot.

explained, not walked: it needs a move killed after its source was torn down, which this ladder does not stage
$ shc finish-forward 3f2c9a1e-7b4d-4c58-9e21-6a0d5b8c1f47

A rename whose new name is a system deployment’s name in another tenant is one the daemon will not finish. A rename is refused that name before it starts, but an older daemon could leave such a record, and the deployment then stays down at the step the rename reached. shc roll-back puts it back under the name it ran under: it undoes each step the rename reached, starts the deployment under its own name and retires the record. A rename’s operation id is rename-<tenant>-<environment>-<name>. If the roll-back stops part way, the record is kept and the next daemon start or shc roll-back again carries it on. --drop, which would retire the record and restore nothing, is refused (X409682CLNDRP): the record is the only map of what the rename moved.

explained, not walked: it needs a rename an older daemon left on a system deployment's name, which this ladder does not stage
$ shc roll-back rename-prod-prod-trial
$ shc roll-back --drop rename-prod-prod-trial

Next: Migrating from another platform.