Skip to content
SHC Docs

After shc init

Quick start shows the happy path on a box that already has everything. This page is the other one: the places a genuinely fresh cluster stops, each of which looks like a bug and is not, and the app repos it starts with.

Every command below is quoted from source, with the file that defines it.

StepCommandDefined in (ce)
1. Package depsapt-get update && apt-get install -fnone
2. More app reposshc repo add <name> <url>modules/repo/commands/add.go
3. DNS connectionshc connection connect <name> --type <provider> --zone <zone> --purpose public|privatemodules/connections/commands/connect.go
4. Entrypointshc config set <key> <value>modules/config/commands/set.go
Redeployshc update <stack> [<version>]modules/app/commands/update.go
Fix a node’s public IPshc node update <node> --public-address <addr>modules/node/commands/update.go

The --zone-is-required rule and the exact connection connect spelling are not paraphrases: they are the literal remedy hints the DNS doctor prints (modules/dns/doctor_missing_provider.go, noProviderHint / noZoneForHostHint).


1. A fresh Debian needs apt-get update first

Section titled “1. A fresh Debian needs apt-get update first”

dpkg -i does not resolve dependencies. On a fresh image it also has an empty package list, so the usual apt-get install -f repair fails a second time with Unable to locate package and the failure reads like a broken .deb.

The one-liner that works on a box that has never run apt-get update:

Terminal window
sudo apt-get update
sudo apt-get install -y ./dist/shc_*_linux_amd64.deb

apt-get install ./file.deb resolves the package’s dependencies directly: no dpkg -i step, no -f repair. If you have already run dpkg -i and it left the package unpacked-but-unconfigured:

Terminal window
sudo apt-get update
sudo apt-get install -f
sudo dpkg --configure shc

On a node with no container engine the package installs both a Docker engine and a Docker client (docker-ce-cli | docker-cli | docker.io (<< 26~)) plus Compose v2, because the daemon shells docker and docker compose for every stack it deploys. A node that already runs Incus or Podman 5 keeps its engine and gets no Docker. On a distro where the archive cannot satisfy one of those clauses, apt refuses the whole install and names the candidates. That refusal is deliberate: a Compose v1 that cannot answer docker compose would install clean and then deploy nothing.

See Installation.

2. A fresh cluster has the SHC app catalog

Section titled “2. A fresh cluster has the SHC app catalog”

shc init registers the SHC app catalog as the repository shc once the modules are installed, so shc install <app> finds the catalog’s apps on a new box with no shc repo add first. shc repo ls lists it beside shipped.

Two sources fill the catalog, and they are independent:

The shipped repository is the apps that shipped with the node’s package. It is daemon-managed (you cannot add or remove it), and it exists only if the install actually put an apps tree on disk, at /usr/share/shc/apps or /usr/lib/shc/apps (modules/repo/shipped.go). A .deb/.rpm/.apk install has one. A bare-binary or unusual source install may not.

The SHC app catalog is the repository shc. Its index lives on the public site, archives included, so it works from any network. This line registers it by hand, on a cluster whose init left it out:

Terminal window
shc repo add shc https://selfhostedcloud.org/apps/0.1/index.yaml

On a cluster that already has it, the same line answers the repository that is there. A shc repo add, or a Terraform shc_repo, whose name, scope, URL and settings match an existing repository is not a conflict; one that differs in any of them is refused with X409901REPOEX.

shc init --repo <name>=<url> registers your own repositories instead. Repeat it for several; any --repo replaces the catalog, and --repo none registers nothing (modules/cluster/commands/init_repos.go). A repository never fails init. A box that cannot reach the catalog gets a warning, the repository stays registered with an empty catalog, and shc repo sync shc fills it once the network allows.

apps/0.1 is the current line’s catalog. The older catalog at https://selfhostedcloud.org/apps/index.yaml belongs to the 0.0 line and its archives are not public; anyone on the 0.0 line outside our network uses the mirror copy at https://selfhostedcloud.org/shc-apps/apps/latest/index.yaml.

Everything else you register yourself:

Terminal window
shc repo add <name> <url>
shc repo sync <name>
shc repo ls

Both arguments are required (cobra.ExactArgs(2)). Repos are remote only: a filesystem path or a file:// URL is refused client-side with X400927REPFIL, because the catalog rows replicate across the cluster while a local directory would not. Useful flags: --token for a private repository, -t/--tenant and -e/--environment to scope it, --priority to order it against others.

shc repo add runs the repository’s first sync before it answers. On a terminal a live line says what it is waiting on and counts the seconds. If that sync fails, the failure is the command’s result, and it exits 1 with no success line:

shc: [X500903REPSYN] failed to sync repository acme with sync ...
hint: repository "acme" is registered, and its catalog is empty until a sync succeeds; `shc repo sync acme` retries it

With -o json it prints the repository with its sync_error and exits 1.

3. DNS needs a connection that owns the zone

Section titled “3. DNS needs a connection that owns the zone”

SHC creates a managed DNS record for a host only when some connection’s owned-zone set is a suffix of that hostname. With no such connection the create path no-ops: the install is green, the route is real, the certificate issues, and the hostname answers NXDOMAIN with nothing in the estate saying why.

Terminal window
shc connection connect <name> --type <provider> --zone <zone> --purpose public|private
  • --type is the capability implementation (cloudflare, route53, hetzner, pfsense, bind, powerdns-local, …). It defaults to <name>, so shc connection connect cloudflare works with no --type.
  • --zone is repeatable. It is REQUIRED for local/LAN-only DNS types (pfsense, bind, powerdns-local) whose zones cannot be auto-discovered. A public connection owns the zones you name, each confirmed against the provider. A zone the provider can’t see refuses the connect with X400941DNSZVIS, the answer shc connection zones gives, and nothing is stored. With no --zone, a cloudflare connection owns every zone its token lists, and the list is read again every 15 minutes, so a zone added to the account later is picked up. A read that fails or lists no zone keeps the zones the connection had. A zone another connection already owns stays with that connection. Any other public provider with no --zone owns none, and no hostname matches it.
  • --cred is repeatable and carries the provider’s credentials into vault. A coordinate (endpoint, region, zone_id, …) is typed inline as key=value. A secret never is: it comes from a file named with --value-file, the flag shc vault set takes. One field is --cred key=- --value-file <file>, several fields are one JSON object in the file named by --value-file <file> alone, and --cred token=<value> is refused with X400548CRDSEC. Without --value-file the same forms read standard input.
  • --purpose public|private declares whether those zones are delegated at a registrar or answer only on a LAN/VPN. It is required whenever --zone is supplied. Private connections auto-create a zone on demand; public ones never do. Stored connections without a purpose keep their inferred value. shc doctor run --category connections names each one and the shc connection zones <name> --purpose public|private --tenant <tenant> command that declares its purpose without re-entering credentials.

Hetzner, concretely: the credential field is token, and one Hetzner Cloud token covers both the Cloud API and DNS:

Terminal window
printf '%s' "$HCLOUD_TOKEN" | shc connection connect hetzner --type hetzner \
--cred token=- --cred region=fsn1 \
--zone example.com --purpose public

★ Do not reach for HETZNER_API_KEY. It is not the connection’s credential field (that is token, modules/dns/providers/hetzner/register.go), and as a Traefik env var it is the wrong one: lego honours it by routing the ACME challenge down its legacy client against the retired dns.hetzner.com, which now answers 301 → console.hetzner.com and yields an HTTP 200 carrying an HTML page. A success code with no data. The correct variable is HETZNER_API_TOKEN, which SHC emits for you; see DNS provider sync.

When a host still gets no record, the diagnosis is a check, not a log dig:

Terminal window
shc doctor run --category dns

dns.no-provider-for-host compares every host the estate intends to publish against every zone a provider could actually publish through, and tells you which of the two states you are in: no DNS provider wired at all, or one wired that owns none of these zones. The ownership census (dns.record-ownership) structurally cannot see this: a host in a zone no connection reaches is in no zone the census enumerates, so it reads as a clean estate.

On a LAN cluster, the address SHC writes into those records is dns.public_address:

Terminal window
shc config set dns.public_address 10.10.1.1

The default is the created node’s IP, which is correct when Traefik runs on the bootstrap node and wrong behind a firewall that fronts the cluster. On an internet-exposed cluster the key is never read at all. All three cases, with the failure modes: The cluster entrypoint.


Where the pipeline’s plan/apply jobs are

Section titled “Where the pipeline’s plan/apply jobs are”

Not in the pipeline you are looking at.

The estate pipeline is generated. The parent has exactly two jobs: generate, which runs generate.sh and artifacts generated.yml, and run, which triggers that artifact as a child pipeline with strategy: depend. Every plan:<root>, apply:<root> and destroy:<root> job lives in the child. The ops repo’s own .gitlab-ci.yml is a handful of lines: an include: of estate-pipeline/template.yml plus CLUSTER_DIR and CLUSTER_FQDN.

So: open the parent pipeline, click through run into the downstream pipeline, and the per-root plan/apply columns are there. An empty-looking parent is the design, not a misconfiguration.

Two consequences worth knowing before you go looking:

  • apply is manual and default-branch only. So is destroy.
  • A destroy job does not exist unless the pipeline was started to run it. Run the pipeline on the default branch with a DESTROY_CONFIRM variable set to the root’s exact <cloud>/<loc>/<root> string; exactly one destroy: job then appears. Without it, or with a typo, no destroy job is rendered at all. The gate lives in generate.sh in the parent job, because trigger:forward:pipeline_variables defaults to false and a child-side rule could never see the variable.

Full reference: the cicd repo’s README, “Estate pipeline (infra + deployments)”.