Skip to content
SHC Docs

shc cluster init

initialize a new cluster

Bootstrap a new cluster on this node: detect the container runtime (docker/podman), generate the cluster CA and node certificate, enable and start the shc service, set the vault master password, and install the platform’s modules. On a terminal an interactive wizard collects the settings; for scripted installs every step can instead come from flags (--vault-password-file, --yes). Each --connection-file connection is made before the modules install, and --storage puts their durable volumes on one of them; later connections are made with shc connection connect. Once the modules are installed, init registers each --repo, by default the SHC app catalog, so shc install <app> finds its apps.

Re-running init on a bootstrapped node is safe: it resumes an unfinished module install and is a no-op when everything already completed; --force wipes local cluster state and re-initializes from scratch. Grow the cluster with shc node token here, then shc node join <token> on the new node.

shc cluster init [flags]
shc init
shc init --ingress-host cloud.example.com --acme-provider letsencrypt --acme-email [email protected]
--acme-directory string ACME directory URL for --acme-provider (blank = Let's Encrypt production; e.g. the LE staging URL)
--acme-email string ACME contact email (the global acme.email fallback contact)
--acme-provider string name of a named ACME provider to define + set as the cluster default (acme.providers.<name> + acme.default)
--address-block string the IPv4 block, a /8 to a /16, every SHC range is carved from by fractions: its first eighth is left to the operator's own networks, service VIPs take its third 1/16, mesh addresses its fourth, deployment networks its second quarter and the fabric its second half; nodes take the fabric in /26 chunks as they fill, 511 of them in the default /16 and 2047 in a /14; the nodes' other networks must sit in the first eighth or outside the block; another block later is a fresh genesis (default "10.64.0.0/16")
--backup-password string set the backup repository encryption key non-interactively. Honoured at genesis only. Afterwards the key lives in the vault and is changed with 'shc backup key rotate'. Unset generates one
--backup-password-file string read the backup repository encryption key from a file (mode 0600 expected); use '-' to read from stdin. Takes precedence over --backup-password and SHC_BACKUP_PASSWORD
--cloud string who runs this node (hetzner, aws, proxmox, or your own name); recorded on the node row, else detected from cloud metadata
--connection-file stringArray a connection to make before the modules install, from a YAML or JSON file holding the document shc.provider.connect takes (name, type, tenant, scope, endpoint, creds, zones, purpose, location; scope defaults to system); credentials come from the file, never the command line; repeatable
--control-plane whether this node is in the control plane (needs the voter capability). A voter genesis node is seeded into it; this flag refuses a host that cannot vote
--fabric string the workload network: shc (the default, on Linux where the runtime attaches it and on a Mac running apple), none (an explicit opt-out, refused where shc is the default)
-f, --force wipe local cluster state and re-initialize even if this node is already clustered
-h, --help help for init
--ingress-host string public host where Traefik fronts SHC's apps
--label stringArray an operator label key=value written on this node after bootstrap; repeatable, one value per key
--location string this node's location as its cloud names it (hel1, us-east-1a, or your own site name); shown and selected as <cloud>/<location> (e.g. incus/home), or the bare location without a cloud; recorded on the node row, else detected from cloud metadata
--modules-config string module selection plus per-module overrides as a compact JSON object keyed by module name, e.g. '{"keycloak":{"host":"auth.example.com"},"traefik":{}}'. The key set is the install selection; traefik is always installed with the selection because nodes join through it on 443, so '{}' installs traefik alone; each value seeds modules.<name>.{host,base_path,vars.*,integrate.*} before the install pass; integrate maps plug to provider and is bound on the module's first install only. Unset falls back to the daemon's SHC_MODULES default set.
-n, --name string node name
--nic string network interface for all cluster-internal traffic (raft, internal API, mesh0 underlay); blank = auto-detect (private-preferred)
--public-address string public IP or stable public hostname internet traffic reaches this node at (recorded on the node row; managed DNS for internet exposure reads it)
--repo stringArray an app repository to register once the modules are installed, as <name>=<url>; repeatable, any --repo replaces the default, and none registers no repository (default [shc=https://selfhostedcloud.org/apps/0.1/index.yaml])
--reserve string room this node keeps for work outside SHC, as cpu=<cores>,memory=<size>,disk=<size>; placement and admission never use it
-r, --runtime string container runtime (docker|podman|incus|apple)
--storage string the volume connection the modules' durable volumes go on, set as storage.volumes.provider before they install
--vault-password string set the vault master password non-interactively
--vault-password-file string read the vault master password from a file (mode 0600 expected); use '-' to read from stdin. Takes precedence over --vault-password and SHC_VAULT_PASSWORD
-y, --yes skip confirmation prompt
--config stringArray extra YAML config file to layer on top of auto-discovered config; repeatable, later files win
-d, --debug enable debug mode (default: $SHC_DEBUG)
-e, --environment string environment name (default: "prod", or "default" on an estate with no licence and no trial; $SHC_ENVIRONMENT and shc ctx -e override it, and the "master" tenant is always "default")
--exclude string comma-separated dotted paths to drop
--fields string comma-separated columns/keys to show (and their order)
--filter string comma-separated dotted paths to keep (drops everything else)
-o, --output string output format: tty|text|json|yaml (default: $SHC_OUTPUT)
-s, --stack string stack name (default: $SHC_STACK)
-t, --tenant string tenant name (default: $SHC_TENANT)
-v, --verbose verbose output (default: $SHC_VERBOSE)