Overview
A multi-node, multi-site Kubernetes platform built on K3s, for provisioning and managing distributed infrastructure with automated storage, networking, and application lifecycle management.
What is Community Cloud?
Community Cloud turns a collection of ordinary machines — in one room or spread across many sites — into a single Kubernetes cluster. Out of the box it provides access to CPU compute, GPU compute, and storage.
On top of those resources it can optionally deploy back office applications for authentication, customer relationship management (CRM), chat, and other services useful when running an online service or business. Behind them it bundles databases, caches, and object storage that follow Community Cloud's default architecture.
Choices throughout have been made with distributed compute in mind. It's assumed that any location may be unavailable at any given time, and Kubernetes tooling and networking are used to provide high availability wherever possible.
Community Cloud is currently in alpha. It is usable, but under heavy active development. See the roadmap for what's coming.
How it fits together
There are two halves to the project:
- The installer — a single executable that builds, inspects, grows, and takes apart clusters over SSH. It carries every manifest it needs inside it, so the machine running it needs no Bun, no Node, and no checkout of the repository.
- The manifests — the Kubernetes resources and Helm values that make up a cluster: storage, networking, certificates, databases, and applications. They're templates, rendered against your cluster's configuration.
A cluster is described by one configuration file, cc.config.json. Every installer command takes its path, and the file is the record of what the cluster is.
Node roles
Community Cloud deploys K3s across heterogeneous hardware and organizes nodes into functional roles. Roles become node-role.kubernetes.io/<role> labels, which is what the manifests select on.
| Role | Purpose |
|---|---|
gateway |
Publicly routable nodes serving as cluster ingress, via the Gateway API on Cilium's Envoy |
worker |
General-purpose workload nodes |
worker-gpu |
GPU-equipped nodes for AI/ML inference (AMD MI300, NVIDIA, Intel) |
storage-local |
Nodes with local block devices for TopoLVM to provision volumes from |
storage-distributed |
Nodes participating in distributed storage pools |
Some roles are worked out rather than written down: a node with a GPU gets worker-gpu, and one marked as a gateway gets gateway.
At a glance
| Area | What Community Cloud uses |
|---|---|
| Kubernetes | K3s, with Traefik, ServiceLB and local-path storage replaced |
| Networking | Cilium as the CNI, kube-proxy replacement, Gateway API implementation, and load balancer |
| Certificates | cert-manager with Let's Encrypt |
| Cross-site | A Nebula mesh through Defined Networking, or Tailscale |
| Local storage | TopoLVM, carving volumes from LVM volume groups sorted by disk type |
| Object storage | Garage, S3-compatible |
| Databases | CloudNative-PG (PostgreSQL + PostGIS), Redis (Opstree operator) |
| Applications | Twenty CRM, Authentik, Mattermost, Headlamp, Picoclaw |
| AI | vLLM on AMD GPUs via ROCm |
Each area has its own page — see Storage, Networking, and Applications.
Where to go next
- Getting Started — build the installer and bring up your first cluster
- Configuration — every key in
cc.config.json - The Installer — commands, bundles, and how the installer works
- Cluster Operations — installing, adding nodes, uninstalling, and cleaning up
- Plugins — extending the installer without forking it
Tech stack
| Category | Technology |
|---|---|
| Runtime | Bun (installer), K3s (Kubernetes) |
| Language | TypeScript, YAML |
| CLI | Ink (React), Commander.js, Inquirer |
| SSH | node-ssh, ssh2 |
| Kubernetes client | @kubernetes/client-node |
| Storage | TopoLVM, Garage |
| Networking | Cilium, cert-manager, Nebula, Tailscale |
| Databases | CloudNative-PG, Redis (Opstree) |
| AI | vLLM (ROCm/AMD GPU) |
| Development | Vagrant (3× Ubuntu 24.04 VMs with 3× 25GB disks) |
Licensing
The repository is MIT licensed, except the installer, which is licensed under the GNU Lesser General Public License, version 3 or later (LGPL-3.0-or-later).
Contributing with AI
Using AI to contribute is completely fine. If you do, please keep the following in mind:
- You are responsible for your contribution and ensuring its quality.
- You fully understand what you're contributing. If you can't explain it to someone with reasonable knowledge of what you're trying to do, it won't be accepted.
- AI can write your code, but it should never speak on your behalf. Write your own PRs, and make sure the corresponding documentation is accurate.
- Try not to waste our time, or yours. 🕰️