Getting Started
Build the installer, describe your machines in a configuration file, check it, and bring up a cluster.
What you'll need
- One or more machines you can reach over SSH, with a user that has passwordless
sudo. Exactly one of them will be the K3s server; the rest join as agents. - Unused disks, on any node that should offer storage. The installer only ever touches a disk that is demonstrably unused — see Storage.
- A domain, if applications should be reachable from the internet, and a way for traffic to reach a gateway node — a public address, or a router forwarding ports.
- Bun, to build the installer from source. The finished binary needs nothing.
Build the installer
The installer ships as a single executable. The manifests and values files under k8s/ are embedded in it, so the result runs on a machine that has never seen the repository.
Executables land in installer/build/. Every target cross-compiles from whatever machine you build on:
| Target | File |
|---|---|
| Linux x64 (glibc) | community-cloud-linux-x64 |
| Linux arm64 (glibc) | community-cloud-linux-arm64 |
| Linux x64 (musl/Alpine) | community-cloud-linux-x64-musl |
| Linux arm64 (musl/Alpine) | community-cloud-linux-arm64-musl |
| macOS Apple silicon | community-cloud-macos-arm64 |
| macOS Intel | community-cloud-macos-x64 |
| Windows x64 | community-cloud-windows-x64.exe |
| Windows arm64 | community-cloud-windows-arm64.exe |
The examples throughout these docs call it community-cloud. To run from source without building, use bun run cc <args> from the installer directory.
Quick start
Four commands take you from nothing to a running cluster you can check on:
1. Build a configuration
Run community-cloud with no arguments and it walks you through describing your cluster — nodes, networking, storage, and packages — and writes cc.config.json. Run it again to edit an existing file, or jump straight to one section:
The file holds secrets — the cluster token, registry passwords, a Nebula API key — so keep it out of version control. See Configuration for every key it can contain.
2. Check it
preflight reads the configuration and connects to every node to say what would stop an install: no server, two servers, a missing token, a node that can't be reached, a gateway with no addresses. It changes nothing.
3. Install
install builds the whole cluster, every node in lock step. Use --dry-run first to see every step without running any of them.
If a step fails, every node stops at the same place. Fix the cause and run the install again. See Cluster Operations for how that works.
4. Check on it
doctor asks every node at once how it's doing, and compares the running cluster against your configuration file. It only runs checks that change nothing, so it's safe to point at a cluster people depend on.
Deployment order
The installer works out most of the ordering for you. If you're applying pieces by hand, this is the order they depend on each other in:
- Provision nodes —
preflight, then the base packages and K3s - Networking — Cilium → Gateway API → the cluster Gateway → cert-manager
- Storage — TopoLVM and the StorageClasses → Garage
- CRDs — Webapp, Site
- Databases — CloudNative-PG → Redis
- Applications — Twenty CRM → Authentik → Mattermost → Headlamp
- Routes — Gateway API HTTPRoutes for each domain
Trying it locally
The repository includes a Vagrantfile describing a local development environment: three Ubuntu 24.04 VMs, each with three 25GB disks — enough to exercise multi-node installs and storage classes without any hardware.