Documentation

What

Community Cloud is a multi-node, multi-site Kubernetes platform built on K3s, designed to provision and manage distributed infrastructure with automated storage, networking, and application lifecycle management.

Out of the box it provides access to CPU compute, GPU compute, and storage. Using these resources it can optionally deploy back office applications for authenitication, customer relationship management (CRM), chat, and other services which can be useful when running an online service or business.

On the back-end it bundles databases, work queues, and other services which can be easily deployed using Community Cloud's default architecture. Choices have been made with distributed compute in mind, and it's assumed that a location may not be available at any given time. We leverage Kubernetes tools and networking to provide high availability as much as possible.

Architecture Overview

Community Cloud deploys a K3s cluster across heterogeneous hardware, organizing nodes into functional roles:

Role Purpose
gateway Publicly routable nodes serving as cluster ingress/egress via Traefik (Gateway API)
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 CSI provisioning
storage-distributed Nodes participating in distributed storage pools (Rook-Ceph)

Storage Architecture

Community Cloud offers two complementary storage layers:

Layer Technology Use Case
Local SSD TopoLVM (LVM-based CSI driver) Fast, node-local storage — default StorageClass cc-local-ssd-fast
Distributed Garage Replicated data available in S3

Local Storage

Storage in Community Cloud is based on Logical Volume Manager (LVM). This provides an incredible amount of adaptability in storage configuration including:

LVM support is built with TopoLVM. The Community Cloud installer automatically configures storage classes based on the following setup:

Device Class Volume Group Medium
ssd cc-ssd-vg M.2 NVMe (fastest)
ssd-sata cc-ssd-sata-vg SATA SSD
ssd-cache cc-ssd-cache SSD cache tier
hdd cc-hdd-vg Spinning disk (capacity)

Each device class maps to a corresponding Kubernetes Storage Class. This makes it trivial to map services to underlying storage to get predictable performance without needing to think to hard about all of the underlying mechanics.

Services in Community Cloud are designed to use sensible underlying storage classes by default. i.e. databases will default to using Solid State Drives, large volume storage will use spinning disks, etc. If necessary, new volume groups can be created depending on application needs.

Networking

Database Services

Service Technology Details
PostgreSQL + PostGIS CloudNative-PG Single-instance, 30Gi SSD, PostGIS 3.6 extension
Redis Opstree Operator Standalone, 5Gi SSD
MariaDB (planned) Configuration directory prepared

Project Structure

community-cloud/
├── installer/          # CLI tool for cluster provisioning
│   ├── src/
│   │   ├── cli/        # React/Ink-based interactive UI
│   │   ├── commands/   # Node-level setup commands (LVM, K3s, Ceph, etc.)
│   │   ├── controller/ # Webapp CRD manifest generator
│   │   ├── remote/     # SSH/remote host abstraction
│   │   └── util/       # K3s installation logic, GPU detection, helpers
│   └── package.json
├── k8s/                # Kubernetes manifests & Helm values
│   ├── ai/             # vLLM GPU inference (AMD MI300)
│   ├── apps/           # Application deployments (Twenty CRM, Authentik, Mattermost, etc.)
│   ├── certs/          # cert-manager issuers & certificates
│   ├── crd/            # Custom Resource Definitions (Webapp, Sites)
│   ├── database/       # PostgreSQL, PostGIS, Redis clusters
│   ├── gateway/        # Gateway API resources & Traefik config
│   ├── k3s-config/     # K3s node configuration (registries)
│   ├── networking/     # Networking (Tailscale cross-site)
│   └── storage/        # TopoLVM, Rook-Ceph, Garage, StorageClasses
├── cc-headlamp/        # Headlamp Kubernetes UI plugin
├── docs/               # Documentation
└── README.md

Installer

The installer (installer/) is a Bun-based CLI that automates multi-node K3s cluster deployment:

Building the Installer

cd installer

# Development
bun run build

# Production binaries
bun run build:linux        # → build/community-cloud-linux-x64
bun run build:macos:arm    # → build/community-cloud-macos-arm
bun run build:macos:x64    # → build/community-cloud-macos-x64
bun run build:windows      # → build/community-cloud-win-x64

Kubernetes Manifests

Custom Resource Definitions

CRD Scope Purpose
Webapp Namespace Declarative webapp lifecycle — deployment, service, PVC, database, Gateway API route, TLS cert
Site Cluster Multi-site configuration management

The Webapp CRD controller (installer/src/controller/WebappController.ts) auto-generates deployment manifests from a simple spec, handling storage, databases, networking, and TLS provisioning.

Applications

App Namespace Status
Twenty CRM cc-office Deployed — server + worker deployments, Postgres, Redis, Garage S3
Authentik cc-office Helm values configured — Postgres-backed auth, Garage S3 storage
Mattermost cc-office Operator values + secret/database/storage manifests prepared
Office (Back Office) cc-office Namespace prepared
Umami (Analytics) — Template directory prepared
Headlamp — K8s plugin values (watchPlugins) prepared

Quick Start

  1. Run the installer to provision your K3s cluster across nodes
  2. Apply k8s manifests in order: CRDs → storage → gateway → certs → databases → apps
  3. Deploy applications using the Webapp CRD or individual manifests

Tech Stack