Skip to content
SHC Docs

The first node

A cluster starts as one node. shc init makes the cluster’s certificate authority, its control-plane database, its vault and its backup repository key, then installs the platform apps on this node. Check the version first.

home01
$ shc version
shc version 0.1.51
build: embedded-tui

Initialize home01. --name is the node’s name in the cluster. --cloud and --location say where it is; every node joined later names its own. The vault password seals every secret the cluster keeps, and the backup password is the key of the backup repository. --label gives the node an operator label. --control-plane seeds it into the control plane, which is where a genesis node goes anyway. --nic names the interface the cluster’s own traffic uses; --runtime the container runtime; --address-block the IPv4 block every SHC range is carved from and --fabric the workload network. --repo is the app repository registered once the platform apps are up, the public catalogue as shc. Each of these is typed here with the value SHC would pick on its own. --yes skips the confirmation.

Five flags of shc init are not typed on this ladder. --public-address records the address internet traffic reaches the node at when that is not the interface address, a NAT or a floating address; the joins page types it on far01. --ingress-host names the hostname the cluster’s ingress answers on and --acme-provider, --acme-email and --acme-directory the account that certifies it, which need a public DNS name these machines do not have.

explained, not walked: the interface address is the public one on these machines, and they have no public DNS name
$ shc init --name home01 --cloud learn --location home --public-address home01.example.net --vault-password P@ssw0rd --backup-password P@ssw0rd --yes
$ shc init --name home01 --cloud learn --location home --ingress-host cloud.example.net --acme-provider letsencrypt --acme-email [email protected] --acme-directory https://acme-v02.api.letsencrypt.org/directory --vault-password P@ssw0rd --backup-password P@ssw0rd --yes

A sixth, --reserve, keeps room on the node for work outside SHC, as cpu=<cores>,memory=<size>,disk=<size>. Placement and admission never hand that room to a deployment. shc cluster init takes the same flag, and the joins page sets it on a running node.

explained, not walked: these machines run nothing beside SHC, so they keep no room back
$ shc init --name home01 --cloud learn --location home --reserve cpu=1,memory=4Gi,disk=50Gi --vault-password P@ssw0rd --backup-password P@ssw0rd --yes
$ shc cluster init --name home01 --cloud learn --location home --reserve cpu=1,memory=4Gi,disk=50Gi --vault-password P@ssw0rd --backup-password P@ssw0rd --yes

shc cluster init is the same command under the cluster group, with the same flags, plus the ingress host and ACME settings a cluster facing the internet takes. This cluster has no ingress host, so they are not typed.

explained, not walked: this cluster has no ingress host
$ shc cluster init --name home01 --cloud learn --location home --label tier=core --control-plane --nic eth0 --runtime docker --address-block 10.0.0.0/8 --fabric shc --repo shc=https://selfhostedcloud.org/apps/0.1/index.yaml --modules-config '{"postgres":{},"keycloak":{},"openobserve":{},"traefik":{}}' --vault-password-file ~/vault-password --backup-password-file ~/backup-password --public-address home01.example.net --ingress-host cloud.example.net --acme-provider letsencrypt --acme-email [email protected] --acme-directory https://acme-staging-v02.api.letsencrypt.org/directory --force --yes
$ shc cluster init --name home01 --cloud learn --location home --vault-password P@ssw0rd --backup-password P@ssw0rd --ingress-host cloud.example.net --yes
home01
$ shc init --name home01 --cloud learn --location home --label tier=core --control-plane --nic eth0 --runtime docker --address-block 10.0.0.0/8 --fabric shc --repo shc=https://selfhostedcloud.org/apps/0.1/index.yaml --vault-password P@ssw0rd --backup-password P@ssw0rd --yes
DNS ownership identity for this cluster: shc-64dc8e78, stored in dns.owner_id
backup repository key sealed at vault backup/password
backup.password = ref+vault://backup/password
backup.repo is not set: shc backup create refuses until it is
warning: skipped 1 module, no node is big enough for them:
[X200916SYSCAP] module openobserve needs 3 CPUs for service openobserve but no node measured more than 2. openobserve was skipped. shc reconcile installs it once a node with the capacity has joined
installing modules postgres, keycloak, traefik for tenant "master"
[postgres] Healthy 1/1
✔ postgres-1 healthy
[keycloak] Healthy 1/1
✔ keycloak healthy
[traefik] Healthy 3/3
✔ forward-auth healthy
✔ traefik healthy
✔ traefik-init healthy
added repository shc from https://selfhostedcloud.org/apps/0.1/index.yaml
✔ initialized cluster on node "home01" with runtime docker

The platform apps belong to tenant master, and each prints its own starting and running lines in the order it gets there. A machine with fewer CPUs than openobserve asks skips it; shc cluster reconcile, on the upgrade page, installs it once a node that fits it has joined.

One node is a cluster of one. It leads, it votes, and it is the only member.

home01
$ shc node ls
NAME STATE CONDITION AVAIL CLOUD LOCATION ROOM BUILD STORE LEADER VOTER
home01 healthy ready active learn learn/home ok 0.1.51 voter yes yes
$ shc node status
NODE ID HOSTNAME CLUSTER STATE AVAILABILITY IS LEADER RUNTIME CLUSTERFS REVISION CLUSTERFS AGE BOOT GATE QUARANTINED
node-1312bc7a966c home01 healthy active true docker 59 1m36s open none
$ shc cluster status
cluster name: shc-cluster
leader: home01
nodes: 1 healthy of 1
voters: 1
quorum: healthy, 1 voter required
leader-only work, recorded by home01 35s ago:
...

--address-block gave the cluster all of 10.0.0.0/8, its genesis block. shc cluster block, or shc cluster block list, prints it and every block added later.

home01
$ shc cluster block
...
$ shc cluster block list
...

A block added later is one more pool of /26 chunks that node fabric addresses, service VIPs and mesh addresses are drawn from once the genesis ranges are full. The add asks every node for its networks and is refused while one cannot be reached, or when the block overlaps the genesis block, a block already added, the docker address pool or a network on any node. A block is never removed, so --yes is the only thing between the command and the cluster.

explained, not walked: the genesis block is already all of 10.0.0.0/8, and an added block is never removed
$ shc cluster block add 192.168.128.0/17 --yes

The configuration init wrote is in the cluster’s store, not in a file. The DNS owner id init printed is one of its rows.

home01
$ shc config get dns.owner_id
shc-64dc8e78
$ shc config get backup.password --show-origin
KEY VALUE FOUND SOURCE SCOPE
backup.password ref+vault://backup/password true row global
$ shc config ls --prefix backup
PATH VALUE SCOPE
backup.password ref+vault://backup/password global

backup.password is a reference into the vault, never the value. Every secret the cluster holds reads that way. backup.repo is still unset; the repository page sets it.

Next: The licence.