Skip to content
SHC Docs

Learn SHC

The ladders are what you type. Start with one empty machine and keep the cluster between pages; each step uses what the previous steps left running. A ladder stays on that one machine until a page needs another: a group with members in two locations, a node failing, a port answered in a second place, a drain, a runtime of its own. That page adds the machine as its first step and says why, and the pages after it keep it. The app ladder follows an app from its first install to connected services. The cluster ladder runs the cluster itself on four machines: it initializes, licenses and joins the nodes, moves work between them, breaks them and brings them back, upgrades them and restores everything onto wiped machines. Each under-the-hood page only reads, and it reads what its app page left running, so read it right after that page.

Before page 00, prepare one Debian 13 machine with 2 CPUs and 8 GB of memory. Install SHC and its container runtime on it, following Installation. Don’t initialize it yet. Have a root shell and curl available. The machine needs internet access to pull images. Prepare a machine a later page adds the same way, and let the machines reach one another on the cluster ports listed in Installation.

Have a Pro licence that covers four nodes and put its file at ~/shc-license.token on the first machine. These ladders use disposable machines and the example password P@ssw0rd.

A console block’s title names the machine where you type its commands. A file block’s title is a path: create the file there, on the machine of the console block that follows it, including its parent directories. Every file an app of yours needs is shown that way. Catalogue apps ship their files with SHC; the pages that use one print the files that matter with a command. ~ is root’s home directory. Type the lines beginning with $, without the $; the lines below are the output. ... omits output. Use home01 for deployment commands and leave the default tenant selected throughout.

Every ladder is also a workshop on the training portal, which makes the machines for your session. Sign in there and start a workshop to follow its pages in the browser.

To follow them in tmux on your own machine, run shc workshop with the workshop’s name. It signs you in to the portal in your browser and attaches to the session the browser shows, or starts one when you have none. A command typed in either shows in both.

explained, not walked: typed on your own machine, not on a lab node
$ shc workshop learn-app

--local opens the tabs on machines of your own instead, the ones your ssh config names node1, node2 and so on, with no portal. shc workshop logout signs you out of the portal and removes what shc workshop kept of it on your machine.

explained, not walked: typed on your own machine, not on a lab node
$ shc workshop cluster --local
$ shc workshop logout

Pages 00 to 07 run on home01 alone, on the 30-day trial. The licence comes before page 08, which adds home02 and far01.

  1. One node to learn on. home01 initialized into a cluster of its own, and the trial.
  2. A compose file. nginx from a directory, served on a published port.
  3. A simple Postgres. A catalogue app installed by name, and the files it ships.
  4. A Postgres socket. pgweb’s four files, and the catalogue socket its plug asks for a database and user.
  5. A label and a location. An app of your own with a job, placed by a location rule and selected by label.
  6. A backup and an export. Your app gets a backup.yaml and an exporter; back up, restore, export and import.
  7. Nextcloud on Postgres. The public catalogue, an S3 gateway from four files with a socket, and Nextcloud on both.
  8. A vapp and an add-on. Your app gets a database vapp from four files and an add-on that presets it.
  9. Postgres members across locations. home02 and far01 join; three members, two in home and one in far, from the catalogue’s members block.
  10. A node failing. Your app moved to far01 with its data, then SHC stopped on far01 and brought back.

This ladder builds apps of your own from the smallest there is, one idea a page and every file written by you. It starts on one machine: pages 0 to 24 run on home01 alone, page 25 joins three more nodes, and pages 26 and 27 use them.

  1. One node to build on. shc init on one machine and the licence.
  2. Your first app. One nginx service from a compose file, behind a hostname.
  3. Your own page. A file of the app mounted read-only, picked up by an update.
  4. A second service. An API beside the page, reached by name; x-shc-primary picks the front door.
  5. A path under the hostname. The API at /api with x-shc-path, then x-shc-path-strip.
  6. A volume. A Redis counter whose count outlives its container.
  7. A healthcheck. Services SHC can call ready instead of only running.
  8. A seed job. A job that puts the counter’s first value in once Redis is up.
  9. Replicas and scale. Two copies of the page, --scale, and x-shc-scale.max keeping the counter to one.
  10. Restarting what is unhealthy. x-shc-health.restart_after, and a frozen nginx restarted by its node.
  11. The same app in shc.yaml. The compose file converted, then the service keys shc.yaml adds.
  12. Variables. Typed variables with defaults, read in shc.yaml and changed at update.
  13. Your own catalogue. A repository of your own, installs by name and a new version.
  14. Stop, start, protect and rename. A deployment’s lifecycle verbs, what a move leaves behind and the global flags.
  15. Secrets and the vault. A key in the vault, mounted from shc.yaml and compose, exported and rotated.
  16. Jobs, hooks and schedules. Three more jobs run by hand, from hooks and on a schedule.
  17. Volumes. Named volumes with a mode and an owner, app files, scratch space and what SHC refuses.
  18. Back up and restore your app. notebook’s backup.yaml with a converter and a restore job; back up, verify, browse, restore and hand over.
  19. Schedules, retention and the repository. Scheduled backups, how many are kept, the repository moved and its key rotated.
  20. Exporters. An exporter with parameters, an export browsed and imported back three ways.
  21. Your own socket and plug. guestbook’s counter as a socket with jobs, and tally, an app that plugs into it.
  22. Add-ons. A named, versioned set of guestbook’s variables, published and installed by name.
  23. Your own vApp. A board vApp from four files, installed into a running guestbook.
  24. Copies and deployfiles. notebook cloned, deployed from a deployfile the way a pipeline would, and the moves a node left half done.
  25. Migrating from another platform. A Dockge stack loaded as it is, then moved into notebook through a migration recipe.
  26. Groups and HA. Three more nodes join; a Redis replica set as numbered members with a writer check, a label and a witness, scaled across locations.
  27. A drain and a disruption budget. deploy.disruption set to never, and a drain of far01 refused instead of taking kv-3 down.
  28. A privilege. The replica set in shc.yaml, a service asking for NET_ADMIN and the grant that lets it.
  1. Four machines. What to prepare: four machines, SHC installed, the licence file and the package kept.
  2. The first node. shc init on home01, what it made and the configuration it starts with.
  3. The licence. The unlicensed posture, the trial, the Pro file installed, dropped and installed again.
  4. Joining nodes. Tokens, two control-plane joins and a worker, the cluster pinged.
  5. The control plane and its voters. Who leads and who votes, a vote moved to far01 and back.
  6. Locations and labels. The labels SHC derives, labels of your own, a described location, a reserved value.
  7. Placement rules. One app installed five ways by --where, --prefer and --scale; rules at a scope; a named node selector.
  8. Cordon, drain, undrain, uncordon. A node closed, emptied, half-emptied and reopened, a deployment leaving and returning.
  9. Nodes failing and rejoining. A voter and then the leader stopped and started; a node leaving and joining again.
  10. Upgrading the daemon. The package installed again on every node inside a maintenance window, leader last.
  11. Repositories. App repositories added and removed; the backup repository, its key, a backup verified, imported and scheduled.
  12. Restoring the whole cluster. Every app backed up, the machines wiped, the cluster rebuilt and every app recovered.
  13. The daemon’s settings. Backup retention, timeouts, the scheduler, maintenance and the log level set with shc config and read back where they take effect; the keys the daemon reads for itself.

Run the cluster ladder’s pages 00 to 10 first, then the app ladder’s pages 01 to 07 on that cluster, then the cluster ladder’s pages 11 and 12.

  1. Underneath the nginx deployment, after page 1. What SHC stored, the compose file it rendered, and who answers the published port.
  2. Underneath the simple Postgres, after page 2. The two services, the member’s two addresses and the socket it offers.
  3. Underneath the socket, after page 3. The plug, the integration, the password and the role.
  4. Underneath the label and the location, after page 4. Where location labels come from and what the rule on placed keeps.
  5. Underneath the backup, after page 5. The repository, its snapshots and the backup the restore took first.
  6. Underneath Nextcloud, after page 6. The two integrations, the bucket and where Nextcloud runs.
  7. Underneath the vapp, after page 7. Your app file by file, the audit record and why one database stayed.
  8. Underneath the members group, after page 8. Where each member runs, Patroni’s view and the etcd cluster.
  9. Underneath a node failing, after page 9. What the leader decided while far01 was gone.
  10. Render once on the leader, after page 9. The leader keeps every rendered deployment; a node keeps only its replicas’ files, in memory.

Start it after page 7 of the app ladder, on home01 alone; it keeps that node and its deployments and adds its own. Page 2 adds far01, because which node answers a port only shows with a second node in a second location.

  1. A port and a VIP. What a compose file declares, what --expose publishes, and the address every service gets.
  2. Who answers a port. Which nodes listen, the listener moved to a location, spread across replicas, and the cluster default.
  3. A hostname and a certificate. A route through the system Traefik, the rendered ingress, the chain it serves, exposure and ACME.
  4. A zone SHC writes. A PowerDNS of your own as the DNS provider, the record SHC writes for a route, and the names nodes answer.
  5. The fabric and its policy. The WireGuard fabric, what one deployment may reach, and a second tenant refused from inside a container.
  6. The mesh under it all. mesh0 and shc0, each node’s addresses, the probe between every pair of nodes, and a key rotation.
  7. Your own ingress. An app of your own with gRPC behind the hostname, a raw TCP port on the system Traefik, a service ending TLS with the certificate SHC delivers, and the exposure app.yaml sets.

Starts after page 7 of the app ladder, on home01 alone. Each page uses what the last left. Page 5 adds home02, to link a storage provider to a second node and move the NFS server between nodes.

  1. Tenants. Two more tenants, the same app under one of them, and what a tenant owns.
  2. Environments. The same deployment in a second environment, -e and the context, and a lease.
  3. Users and SSO. Users in the tenant’s realm, roles granted and revoked, a session ended, a service client for automation.
  4. Gated apps. The SSO gate on a hostname route, the 302 and 401 an anonymous request gets, LAN-only and internet.
  5. Connections. An S3 key pair stored as a connection, shown without its secret, granted to the tenant and bound by an app.
  6. Storage providers. The local provider, a second one on one node, the managed NFS share and a deployment on it.

Start this ladder after page 7 of the app ladder, on home01 alone. Page 0 adds obs01, a machine with the CPUs the observability app needs.

  1. A node for the observability app. A second machine with the CPUs the system OpenObserve needs, its admin password, and reconcile installing it.
  2. Status. The node, queue and deployment tables of shc status, what each column means when it is not green, and the node, leader and cluster answers beside it.
  3. Doctor. The diagnoses, three faults made on purpose, the report, one fix applied and a destructive one named.
  4. Events. The event listing, its filters, three events caused live, the follow stream in tmux, the audit chain and a notification rule.
  5. Logs. A deployment’s logs, one service’s, one replica’s, a live follow, the daemon’s own log and the node collector.
  6. Metrics. Live resource use, a metric and a log line queried from OpenObserve, one change read as an event, a log line and a metric, and the support bundle.

The HUD is its own tutorial. Its screens are read with tmux so that every one of them can be typed again. Start it after page 7 of the app ladder, on home01 alone. Page 3 adds home02, because a drain needs a node to empty and another to take its work.

  1. Opening the HUD. The header, the legend, the command bar, help, and every key that moves without changing anything.
  2. Deployments, services and containers. The deployment table, filters, sorts, detail, the drill to services and containers, the views picker and the links between tables.
  3. A cluster changing under the HUD. An install, a restart, a stop, a backup, a protect and an uninstall from the HUD and from another shell, with the tables moving.
  4. Nodes. The node table, a cordon and a drain from the HUD with the deployments moving, and the cluster, pressure, label and constraint tables.
  5. Every other table. Apps to notifications, every remaining table opened and every key it binds pressed.

The runtimes ladder starts after page 7 of the app ladder, on home01 alone, and adds a node per engine.

  1. The default runtime. home01 runs docker; read it, and prepare two machines.
  2. A podman node. Podman and podman-compose on pod01, joined with --runtime podman, nginx running on it.
  3. An incus node. Incus and incus-compose on inc01, joined with --runtime incus, nginx running on it.
  4. An apple node. A Mac with Apple’s container CLI joins as an apple node; needs a Mac.

Each cloud page adds one node that company runs to the one-node cluster of the app ladder’s page 0, connects the account, and takes the node out again, so each page stands alone.

  1. A Hetzner node. A server in hel1 joins, the hetzner connection, a deployment’s data on a Hetzner volume, the node leaves.
  2. An Alibaba Cloud node. An ECS instance joins, its cloud and zone set by hand, the alibaba connection, an ESSD disk. Not walked yet.
  3. A Scaleway node. An instance joins and the scaleway connection serves DNS only. Not walked.
  4. A Google Cloud node. A Compute Engine instance joins, a service account connects, a persistent disk and its snapshot. Not walked yet.
  5. An AWS node. An EC2 instance joins, the aws connection, an EBS volume. Not walked.
  6. An Azure node. A virtual machine joins, a service principal connects, a managed disk. Not walked.
  7. A DigitalOcean node. A droplet joins, the digitalocean connection, a block volume. Not walked.
  8. An Exoscale node. An instance joins and the exoscale connection serves DNS only. Not walked.
  9. A Hostinger node. A VPS joins a cloud with no connection type. Not walked.
  10. An OpenStack node. A Nova instance joins, the openstack connection and what each cloud of the family runs. Not walked.
  11. An Oracle Cloud node. A compute instance joins, its availability domain set by hand, the oci connection, a block volume. Not walked.
  12. An UpCloud node. A server joins and is detected, the upcloud connection, block storage. Not walked.
  13. A Vultr node. An instance joins, the vultr connection, block storage. Not walked.

This ladder starts from nothing: one Debian machine to work from and a Hetzner token in its environment. Terraform builds the cluster, grows it, manages what runs on it, upgrades it and takes it down. After page 07 each page takes another example root and shows only what differs from the Hetzner front door you wrote.

  1. A workstation for Terraform. One machine with OpenTofu, the shc provider, the module library and a Hetzner token in its environment.
  2. The root module. Write versions.tf, variables.tf, main.tf, outputs.tf and a tfvars file, then plan and apply the four machines.
  3. The cluster. Add the bootstrap block, apply, read the outputs, log in and see four nodes in two locations.
  4. Grow by a count. Change one number, read a plan that adds one machine and one node, apply, and see five nodes.
  5. Deployments through the provider. Configure the shc provider over SSH, add the public catalogue, install two apps and a database vapp, and change a deployment.
  6. DNS through the provider. Connect a DNS zone, make it the cluster’s DNS provider, publish a record, and compute the licence record.
  7. Upgrade. Bump the package version, read a plan that touches every node, and watch the roll go one node at a time.
  8. Destroy. Consent to removing occupied nodes, destroy everything, and check that the project holds nothing of the cluster.
  9. Example: hetzner-shc. The canonical Hetzner root, with two node groups, a per-group firewall and the lb topology through the module.
  10. Example: hetzner-lan. Three nodes on a private network with the cluster plane pinned to the private NIC and an SSH-only firewall.
  11. Example: hetzner-lan-lb. The private-plane cluster plus a Hetzner connection, a load balancer on the system traefik and a volume provider.
  12. Example: hetzner-wan-mesh0. Three nodes with no private network at all, the cluster plane on public addresses over mesh0.
  13. Example: mixed-proxmox-hetzner. Two infra-only front doors, one Hetzner node and Proxmox VMs at home, joined by one root call of modules/core.
  14. Example: proxmox-lan. A cluster of Proxmox VMs with static addresses on a flat LAN, no cloud at all.
  15. Example: aws-shc. EC2 in one availability zone, a scoped IAM user and S3 bucket for the daemon, Route53 or Cloudflare DNS, and demo apps.
  16. Example: azure-shc. One resource group with a VNet, three VMs, Cloudflare or Azure DNS, and Postgres with Gitea on top.
  17. Example: gcp-shc. GCE instances in one zone, a pinned module version, Cloudflare DNS, and Postgres with Gitea on top.
  18. Example: digitalocean-shc. Droplets in a region VPC with reserved IPs, one DigitalOcean connection for DNS, load balancer and volumes, and two demo apps.
  19. Example: linode-shc. Three instances in a region VPC behind cloud firewalls, with the bootstrap gated on a vault password.
  20. Example: scaleway-shc. Four instances with flexible IPs on a Scaleway private network, Cloudflare DNS, and two demo apps.
  21. Example: vultr-shc. Instances on one Vultr network, a vultr connection for the load balancer and volumes, Cloudflare DNS, and two demo apps.
  22. Example: exoscale-shc. Instances in one Exoscale zone, the key pair and vault password minted in the root, Cloudflare DNS, and two demo apps.
  23. Example: alibaba-shc. ECS instances on a VPC and VSwitch in one zone, with the bootstrap gated on a vault password.
  24. Example: cloudstack-shc. Instances on an isolated CloudStack network with public IPs, static NAT and firewall rules, bootstrap gated on a vault password.
  25. Example: openstack-shc. Instances on an OpenStack project with floating IPs, Cloudflare DNS, and the platform gated on a vault password.