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.
| Step | Command | Defined in (ce) |
|---|---|---|
| 1. Package deps | apt-get update && apt-get install -f | none |
| 2. More app repos | shc repo add <name> <url> | modules/repo/commands/add.go |
| 3. DNS connection | shc connection connect <name> --type <provider> --zone <zone> --purpose public|private | modules/connections/commands/connect.go |
| 4. Entrypoint | shc config set <key> <value> | modules/config/commands/set.go |
| Redeploy | shc update <stack> [<version>] | modules/app/commands/update.go |
| Fix a node’s public IP | shc 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:
sudo apt-get updatesudo apt-get install -y ./dist/shc_*_linux_amd64.debapt-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:
sudo apt-get updatesudo apt-get install -fsudo dpkg --configure shcOn 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:
shc repo add shc https://selfhostedcloud.org/apps/0.1/index.yamlOn 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:
shc repo add <name> <url>shc repo sync <name>shc repo lsBoth 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 itWith -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.
shc connection connect <name> --type <provider> --zone <zone> --purpose public|private--typeis the capability implementation (cloudflare,route53,hetzner,pfsense,bind,powerdns-local, …). It defaults to<name>, soshc connection connect cloudflareworks with no--type.--zoneis 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 withX400941DNSZVIS, the answershc connection zonesgives, and nothing is stored. With no--zone, acloudflareconnection 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--zoneowns none, and no hostname matches it.--credis repeatable and carries the provider’s credentials into vault. A coordinate (endpoint,region,zone_id, …) is typed inline askey=value. A secret never is: it comes from a file named with--value-file, the flagshc vault settakes. 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 withX400548CRDSEC. Without--value-filethe same forms read standard input.--purpose public|privatedeclares whether those zones are delegated at a registrar or answer only on a LAN/VPN. It is required whenever--zoneis 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 connectionsnames each one and theshc 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:
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 istoken,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 retireddns.hetzner.com, which now answers301 → console.hetzner.comand yields an HTTP 200 carrying an HTML page. A success code with no data. The correct variable isHETZNER_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:
shc doctor run --category dnsdns.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.
4. Declare the entrypoint
Section titled “4. Declare the entrypoint”On a LAN cluster, the address SHC writes into those records is
dns.public_address:
shc config set dns.public_address 10.10.1.1The 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:
applyis manual and default-branch only. So isdestroy.- A
destroyjob does not exist unless the pipeline was started to run it. Run the pipeline on the default branch with aDESTROY_CONFIRMvariable set to the root’s exact<cloud>/<loc>/<root>string; exactly onedestroy:job then appears. Without it, or with a typo, no destroy job is rendered at all. The gate lives ingenerate.shin the parent job, becausetrigger:forward:pipeline_variablesdefaults to false and a child-side rule could never see the variable.
Full reference: the cicd
repo’s README, “Estate pipeline (infra + deployments)”.
See also
Section titled “See also”- Quick start: init, install, back up, remove
- Core concepts: tenant, environment, stack, deployment
- The cluster entrypoint
- Troubleshooting