Skip to content

Platform doctrine package — homelab / farm edge compute

Purpose: First-class doctrine for the wiki’s homelab / farm edge compute layer: what the stack is for, what belongs in early phases, what is deferred, and what high availability means here (not generic Kubernetes marketing). Operator posture: prefer official k3s / Longhorn / Rancher docs and this repo’s captures; pilot-ready and production-ready are explicitly different bars.

Non-goals: Mandating Kubernetes for every workload; multi-cluster or service mesh as defaults; geographic HA without a separate DR story.

What this hub owns

  • Doctrine for Pi / k3s / Longhorn / Rancher on the farm edge and homelab: phases, HA meaning, storage topology, and deferrals.
  • Pointers to provisioning and backup tracks—not duplicate Backup and disaster recovery — doctrine hub or raw kubectl recipes outside the linked runbook.

Integration / package boundary: New k3s / Longhorn / Rancher captures should activate into K3s, Longhorn, Rancher, Raspberry Pi — platform captures (Evidence summary), Platform decision memo, and Operational standards — farm and homelab platform rows when bars change. Observability / secrets ingests route through Observability, secrets, and trust bar — homelab / farm edge—not a parallel platform essay.

Start here

Goal Page
Why this stack Platform strategy for farm and homestead services
What is approved vs deferred Platform decision memo — phase, HA scope, deferrals
Hands-on sequence How to provision k3s, Longhorn, and Rancher on a Raspberry Pi fleet

Canonical vs supporting

Canonical (durable navigation) Supporting (depth, alternatives)
Platform strategy…, Platform decision memo…, HA meaning and constraints…, component role pages (k3s, Longhorn, Rancher) Raspberry Pi fleet provisioning standard, RKE2 narrative captures, Docker, Kubernetes, Compose, and Bake

What this platform is for

Need How the stack serves it
farmOS + PostgreSQL (records, geometry) Stateful workloads on k3s with PVCs (Longhorn or external storage); logical DB dumps still required (Backup strategy comparison).
Telemetry (broker, consumers, optional TSDB) Burstable edge services on the same cluster or a lighter compose stack—doctrine allows either if ops burden matches team size (Field telemetry ref arch).
Backup / DR etcd, Longhorn volumes, app-level backups are different tracks (Kubernetes platform backup / DR, DR package).
Homestead vs farm site Control plane may live at SITE_HOME; edge nodes at SITE_FARM must respect power and WAN reality (Two-site operations).

Entity anchors (durable roles, not hostnames): Edge cluster storage roles — homelab / farm stack, Kubernetes edge control-plane roles, Backup and restore tier labels — farm stack, Edge service deployment classes — pilot vs production.

Doctrine map (read order)

# Page Role
1 Platform strategy for farm and homestead services Why this stack; principles; layered view
2 Platform decision memo — phase, HA scope, deferrals Approved now vs later; anti-patterns
3 HA meaning and constraints — homelab / farm platform What HA does / does not mean here
4 k3s role in the homelab / farm platform Control plane, datastore, boundaries
5 Longhorn role in the homelab / farm platform CSI, replication scope, ops cost
6 Rancher — role and timing Optional UX; when not to install
7 Central vs distributed storage architecture Longhorn vs NAS/object; hybrid
8 Raspberry Pi fleet provisioning standard Per-node checklist; pilot vs production

Runbook (how): How to provision k3s, Longhorn, and Rancher on a Raspberry Pi fleet — sequences from bootstrap through validation.

Provenance: K3s / Longhorn / Rancher / Pi platform captures.

Reference architecture (doctrine layer)

```mermaid flowchart TB subgraph workloads["Workloads — farm / homelab"] farmOS["farmOS / PostgreSQL"] broker["MQTT / consumers"] obs["Optional observability"] end

subgraph k3s["k3s cluster"] api["Kubernetes API"] cp["Control plane + datastore"] end

subgraph storage["Storage topology"] lh["Longhorn — distributed block PVCs"] central["Central NAS / object — media, restic, archives"] end

subgraph optional["Deferred / optional"] rancher["Rancher UI"] end

workloads --> api api --> lh api --> central cp --> rancher lh --> central ```

Legend: Longhorn and central storage are often both present in a hybrid pattern; Rancher is optional and not required for a valid cluster.

Pilot-ready vs production-ready (summary)

Bar Pilot-ready (Phase 0/1) Production-ready
Control plane Single k3s server + embedded datastore acceptable for lab HA servers + tested restore (HA doctrine)
Data One stateful app proven; backups manual but restored once Scheduled backups, monitored disks, patch cadence
Rancher Usually deferred Only if RBAC + ingress + upgrade process owned