Skip to content
SHC Docs

A workstation for Terraform

This ladder builds a four-node SHC cluster on Hetzner Cloud with Terraform and takes it down again. You start with nothing: no cluster, no machines. You need one Debian 13 machine to work from, with a root shell and internet access. Call it work. Every console block in this ladder runs on it.

Terraform needs two things from you before page 01.

  • A Hetzner Cloud project of your own with nothing in it, and an API token on it with read and write permission. The ladder creates its machines in that project, on your account, and destroys them on page 07. The token lives in your login shell as HCLOUD_TOKEN.
  • The Pro licence token you were issued, covering five nodes, at ~/shc-license.token on work: the file the app ladder installs by hand.

SHC itself comes from the Based apt repository, by version: each machine the ladder makes installs the release your root module names. You need nothing from it here.

Put the token in ~/.profile, the file your login shell reads. Open it in an editor and add the line below at its end, with your own token in place of your-token. It stays there for the whole ladder and appears in no file this ladder shows.

shown, not walked: the token is yours, and only you type it
$ nano ~/.profile
Terminal window
export HCLOUD_TOKEN=your-token

A shell reads ~/.profile when it starts. Read it into the one you have open, then check the token is set without printing it, and the licence is in place:

work
$ . ~/.profile
$ test -n "$HCLOUD_TOKEN"
$ test -s ~/shc-license.token

Install OpenTofu from its own package repository. terraform works the same way everywhere in this ladder; the commands say tofu.

work
$ apt-get install -y curl git gpg dnsutils
...
$ curl -fsSL https://get.opentofu.org/install-opentofu.sh -o install-opentofu.sh
$ sh install-opentofu.sh --install-method deb
...
$ tofu version
OpenTofu v1.13.1
on linux_amd64

The shc provider is not on the public registry. It is published on a network mirror, and the OpenTofu configuration file points at it. The include and exclude pair keeps every other provider on the public registry.

~/.tofurc
provider_installation {
network_mirror {
url = "https://selfhostedcloud.org/terraform/0.1/"
include = ["registry.terraform.io/selfhosted-cloud/shc",
"registry.opentofu.org/selfhosted-cloud/shc"]
}
direct {
exclude = ["registry.terraform.io/selfhosted-cloud/shc",
"registry.opentofu.org/selfhosted-cloud/shc"]
}
}

The mirror is public: tofu init on page 01 installs the provider from it.

The modules are published beside the provider, one archive each. This ladder’s root modules name two of them by path: the Hetzner front door and license-dns. Unpack both under learn/shc/terraform/modules, beside the directory your root module will live in.

work
$ mkdir -p learn/shc/terraform/modules/shc/hetzner learn/shc/terraform/modules/license-dns
$ curl -fsSL https://selfhostedcloud.org/terraform/0.1/modules/0.1.3/shc-hetzner-0.1.3.tgz -o shc-hetzner.tgz
$ tar -xzf shc-hetzner.tgz -C learn/shc/terraform/modules/shc/hetzner
$ curl -fsSL https://selfhostedcloud.org/terraform/0.1/modules/0.1.3/license-dns-shc-0.1.3.tgz -o license-dns.tgz
$ tar -xzf license-dns.tgz -C learn/shc/terraform/modules/license-dns
$ ls -1 learn/shc/terraform/modules
license-dns
shc
$ ls -1 learn/shc/terraform/modules/shc
hetzner

modules/shc/<cloud> is a front door: one module call creates the cloud’s machines, network and firewalls, then hands the node list to the core module, which installs SHC on every node and forms the cluster over SSH. A published front door fetches the core it was released with by itself. You write the root module that calls modules/shc/hetzner.

Every other cloud’s front door is published the same way, as shc-<cloud>-0.1.3.tgz. The example roots the pages after 07 describe are in the SHC repository under terraform/examples, which is private today, so those pages are for reading.

Every tofu command in this ladder runs from your home directory and names the root module with -chdir, so each command stands on its own.

Next: The root module.