Skip to content
SHC Docs

Variables

A variable is a setting the person installing an app may change. app.yaml declares it with a type, vars.yaml gives it a default, and shc.yaml reads it as {{ vars.<name> }}. Replace guestbook’s app.yaml and add vars.yaml on home01.

~/learn/guestbook/app.yaml
name: guestbook
version: "1.1.0"
title: Guestbook
description: A page, an API under its path and a counter
category: demo
license:
id: MIT
vars:
greeting@string!: the line the page answers at /greeting
maxSigners@int: how many people may sign
open@bool: whether signing is open
apiPort@port: the port the API listens on
dataPath@path: where the counter keeps its data
theme@json: colours the page uses
owner:
email@email: who runs the guestbook
homepage@url:endpoint: the owner's page
password@secret: the owner's password
~/learn/guestbook/vars.yaml
greeting: Sign the guestbook.
maxSigners: 100
open: true
apiPort: 8080
dataPath: /data
theme: '{"background": "white"}'
owner:
homepage: https://example.com
password: "ref+vault://owner_password?autogen"

title, description and category are new too: they are what listings and the catalogue show. Each leaf under vars is <name>@<type>. ! makes it required. @secret keeps the value in the vault, and ?autogen makes one on the first install. @url also names what a move of the app does to it: endpoint is replaced by the new address. owner groups three variables, read as vars.owner.email and so on. See Variables and App variables.

Use them in shc.yaml. Only the lines that change are new: site answers /greeting, api listens on apiPort, counter keeps its data at dataPath, and web gets the owner’s address and the signing settings. api’s expose stays a number: SHC reads the port a route goes to before it fills in variables, so change apiPort and expose together.

~/learn/guestbook/shc.yaml
where:
- location=learn/home
configs:
site:
content: |
server {
listen 80;
root /usr/share/nginx/html;
location = /healthz { return 200 "ok\n"; }
location = /greeting { return 200 "{{ vars.greeting }}\n"; }
}
services:
web:
image: nginx:1.27-alpine
primary: true
replicas: 2
expose: [80]
hostname: guestbook-web
domainname: learn.test
environment:
TZ: UTC
OWNER_EMAIL: "{{ vars.owner.email }}"
OWNER_HOMEPAGE: "{{ vars.owner.homepage }}"
SIGNING_OPEN: "{{ vars.open }}"
MAX_SIGNERS: "{{ vars.maxSigners }}"
env_file:
- ./web.env
labels:
tier: front
configs:
- name: site
path: /etc/nginx/conf.d/default.conf
volumes:
- source: ./site
path: /usr/share/nginx/html
read_only: true
tmpfs:
- /var/cache/nginx
- /var/run
- /tmp
init: true
cap_add: [NET_BIND_SERVICE]
pull_policy: missing
stop_signal: SIGQUIT
stop_grace_period: 20s
post_start:
- command: ["sh", "-c", "date -u > /tmp/started"]
quota:
cpu: "0.25"
memory: 64M
healthcheck:
test: ["SHC-HTTP", ":80/healthz"]
interval: 10s
timeout: 3s
retries: 3
health:
restart_after: 30s
api:
image: traefik/whoami:v1.10
command: ["--port", "{{ vars.apiPort }}", "--name", "guestbook-api"]
expose: [8080]
healthcheck:
test: ["SHC-HTTP", ":8080/"]
interval: 10s
timeout: 3s
retries: 3
path: /api
path_strip: true
user: "65534:65534"
group_add: ["65534"]
working_dir: /
platform: linux/amd64
read_only: true
security_opt: ["no-new-privileges:true"]
dns: ["1.1.1.1"]
dns_search: [learn.test]
extra_hosts:
- printer.learn.test:192.0.2.10
counter:
image: redis:7-alpine
command: ["redis-server", "--appendonly", "yes", "--dir", "{{ vars.dataPath }}"]
expose: [6379]
restart: always
networks:
default:
aliases: [store]
volumes:
- name: data
path: "{{ vars.dataPath }}"
sysctls:
net.core.somaxconn: 1024
ulimits:
nofile:
soft: 4096
hard: 8192
shm_size: 64m
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 5s
timeout: 3s
retries: 12
scale:
max: 1
peek:
image: redis:7-alpine
entrypoint: ["sh", "-c"]
command: ["sleep infinity"]
network_mode: service:counter
pid: service:counter
ipc: service:counter
volumes_from: [counter]
read_only: true
tty: true
depends_on:
counter:
condition: healthy

Update the deployment, then read what the variables became.

home01
$ shc update guestbook
...
$ shc exec -s guestbook -S web -- printenv OWNER_EMAIL SIGNING_OPEN MAX_SIGNERS
...
$ shc vault ls -s guestbook
...

The owner’s password is in the vault, not in any file. --var changes a variable at install or update, and the deployment keeps the new value for every later update.

home01
$ shc update guestbook --var greeting="Welcome back."
...
home01
$ curl -sk --resolve guestbook.learn.test:443:127.0.0.1 https://guestbook.learn.test/greeting
Welcome back.

--check says whether the app’s files changed since the deployment was last rendered, and changes nothing. --quiet drops an update’s progress lines.

home01
$ shc update guestbook --check
...
$ shc update guestbook --quiet
...

Install and update take the same flags for what a deployment may use and how it starts. --cpu-quota and --memory-quota set one service’s quota over the file’s. --naming-exception records why a deployment keeps a name that is not the hostname it serves. --no-rollback leaves a failed install in place to inspect, and --no-wait returns before the containers report healthy. Try them on a spare copy and remove it.

home01
$ shc install ~/learn/guestbook -s spare --cpu-quota web=0.5 --memory-quota web=128M --naming-exception "a spare copy for this page" --no-rollback --no-wait --quiet
...
$ shc uninstall spare --no-backup --yes --quiet
...

--config-set writes a config row at the deployment’s own scope, and on an update key! removes it. --interactive opens the variables form, prefilled with the deployment’s values.

explained, not walked: a deployment config row would ride every later page, and the form needs a terminal
$ shc update guestbook --cpu-quota web=0.5 --memory-quota web=128M --naming-exception "the hostname is the app's" --no-wait
$ shc update guestbook --config-set deploy.limit_ratio=2
$ shc install ~/learn/guestbook -s spare --config-set deploy.limit_ratio=2
$ shc install ~/learn/guestbook -s spare --interactive
$ shc update guestbook --interactive

Next: Your own catalogue.