Skip to content
SHC Docs

Environments

A deployment is one app in one tenant in one environment. The ladder’s deployments are all in environment prod, which is where a licensed cluster puts an install that names no environment. A second environment holds a second copy of the same deployment, with its own data and secrets.

Install the catalogue Postgres as db again, into staging. There is no command that creates an environment: the first deployment named into it does.

home01
$ shc install postgres -s db -e staging
installing deployment "db"
[db] Healthy 1/1
✔ postgres-1 healthy
✔ installed deployment "db"
home01
$ shc ls
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
db prod staging postgres running home01
$ shc ls -e staging
STACK TENANT ENV APP STATUS NODE
db prod staging postgres running home01

The two db rows are two deployments. A table made in one is not in the other:

home01
$ shc exec -s db -e staging -S postgres-1 -- psql -U postgres -c 'create table staging_only (n int)'
CREATE TABLE
$ shc exec -s db -e staging -S postgres-1 -- psql -U postgres -tAc "select count(*) from pg_tables where tablename = 'staging_only'"
1
$ shc exec -s db -S postgres-1 -- psql -U postgres -tAc "select count(*) from pg_tables where tablename = 'staging_only'"
0

-e on every deployment command picks the environment, and --tenant on the ones that take it picks the tenant the same way. Read the staging database’s logs and its vault to see the flag at work on two more commands.

home01
$ shc logs -s db -e staging
...
$ shc vault ls -e staging
...
$ shc vault ls
...
explained, not walked: the flag means the same on every command that takes it, and this ladder types it where the page has a reason to
$ shc deploy -f ~/learn/notes.shc.yaml -e staging
$ shc doctor origin-probe web -e staging --tenant prod
$ shc import postgres -e staging
$ shc inspect db -e staging
$ shc integration -e staging --tenant prod
$ shc protect db -e staging --tenant prod
$ shc unprotect db -e staging --tenant prod
$ shc recover -e staging
$ shc repo add mirror https://example.com/apps -e staging --tenant prod
$ shc repo ls --tenant prod
$ shc repo sync mirror -e staging --tenant prod
$ shc repo update mirror -e staging --tenant prod
$ shc repo rm mirror -e staging --tenant prod
$ shc repoint db postgres -e staging --tenant prod
$ shc schedule add nightly '0 2 * * *' -s db -e staging
$ shc schedule info nightly -s db -e staging
$ shc schedule edit nightly '0 3 * * *' -s db -e staging
$ shc schedule disable nightly -s db -e staging
$ shc schedule enable nightly -s db -e staging
$ shc schedule rm nightly -s db -e staging
$ shc shell db -e staging
$ shc update db -e staging
$ shc validate ~/learn/nginx -e staging
$ shc vault set app.key --value-file ~/learn/app.key -e staging
$ shc vault get app.key -e staging
$ shc vault exists app.key -e staging
$ shc vault rm app.key -e staging
$ shc vault export ~/learn/staging-vault.json -e staging --tenant prod
$ shc vault import ~/learn/staging-vault.json -e staging --tenant prod

The context sets the environment for every command that follows:

home01
$ shc ctx -e staging
...
$ shc exec -s db -S postgres-1 -- psql -U postgres -tAc "select count(*) from pg_tables where tablename = 'staging_only'"
1
$ shc ctx
...
$ shc ctx --reset
...
$ shc ctx -t prod
...
$ shc exec -s db -S postgres-1 -- psql -U postgres -tAc "select count(*) from pg_tables where tablename = 'staging_only'"
0

shc ctx with no flags prints the resolved context: the cluster, the tenant, the deployment name and the environment every command will use. --reset puts the defaults back, and the defaults name no tenant, so -t prod selects prod again. -t and -s set the tenant and the deployment the same way, and --cluster picks one of the clusters a workstation has logged in to. --token stores one bearer, here the one shc auth token prints; --token-exec names a command that prints a fresh token each call instead, --insecure skips TLS verification, and --color pins the HUD tint of that cluster.

explained, not walked: tenant prod is the context already, and a second cluster login needs a bearer from a browser
$ shc ctx --tenant prod --stack db
$ shc ctx login lab --url https://home01 --token "$(shc auth token)" --ca ~/learn/ca.pem
$ shc ctx login lab --url https://home01 --token-exec 'cat ~/learn/token' --insecure --color 3
$ shc ctx --cluster lab
$ shc ctx logout lab

shc ctx login stores a cluster under a name on a workstation, with the bearer the users page explains; logout forgets it.

A deployment can carry a lease. Install nginx into staging with a lease of two hours; when the lease expires, SHC uninstalls the deployment.

home01
$ shc install ~/learn/nginx -s web -e staging --expose 18082=nginx:80 --ttl 2h
installing deployment "web"
[web] Healthy 1/1
✔ nginx healthy
✔ installed deployment "web"
exposure: lan
$ shc lease show web -e staging
...
$ shc lease renew web -e staging --ttl 4h
...
$ shc lease show web -e staging
...
$ shc lease clear web -e staging
...
$ shc lease show web -e staging --tenant prod
...

shc lease renew stamps the lease to now plus the duration; shc lease clear removes it, so the deployment stays. The prod environment is protected: a lease there is refused; --force on the renew, or on an install that names a lease, overrides that.

home01
$ shc lease renew web --ttl 24h
shc: [X400996LSEPRT] lease operation on stack web refused, environment prod is protected, pass --force to override
explained, not walked: it would lease prod web, which the gated page needs running
$ shc lease renew web --ttl 24h --force

Remove the leased nginx and keep the staging database for the next pages.

home01
$ shc uninstall web -e staging --yes
uninstalling deployment "web"
[web] Complete 4/4
✔ remove from home01
✔ take the safety backup
✔ leave every node's service VIP table
✔ tear down
✔ uninstalled deployment "web"
home01
$ shc ls
STACK TENANT ENV APP STATUS NODE
cloud prod prod nextcloud running home01
db prod prod postgres running home01
pgweb prod prod /root/learn/pgweb running home01
placed prod prod notes running home01
store prod prod /root/learn/versitygw running home01
web prod prod /root/learn/nginx running home01
db prod staging postgres running home01

Tenant prod now holds one more deployment than the app ladder left, the staging db, in a second environment. The context names prod and no environment.

Next: Users and SSO.