home-network-k3s/README.md

# Home Platform — k3s + Longhorn Onboarding Platform

> **This repository is a specification, not an implementation.** It defines *what* to build
> and *how the work is organized* so that teams of AI agents (and their human reviewers) can
> implement a self-service onboarding platform for home infrastructure at both the **PaaS**
> (containerized apps) and **IaaS** (virtual machines) level.

## What we are building

A single, GitOps-driven platform, running on a **k3s** Kubernetes cluster backed by **Longhorn**
distributed storage, that lets an operator onboard, run, update, and tear down services — both
**containers** and **virtual machines** — through one consistent Kubernetes API, CLI, and YAML
configuration surface.

The platform must provide:

- **PaaS**: containerized workloads onboarded via GitOps.
- **IaaS**: virtual machines managed through the *same* Kubernetes API/CLI/YAML (via KubeVirt),
  for workloads that cannot be containerized.
- **Network isolation**: default-deny east-west traffic; explicit, port-level allow rules between
  services (firewall-like).
- **Multi-WAN egress**: some services egress the normal internet; others are routed through a
  custom VPN connection. Egress path is a declarative property of a service.
- **Stateful durability**: any service can be destroyed and rebuilt on a whim without losing data.
- **Hands-off updates**: services update to latest stable versions on a schedule — no human,
  no AI, no hand-written GitOps change required.
- **Trusted TLS**: every service gets an auto-issued, auto-renewed, non-self-signed certificate.
- **Observability**: services are monitored; issues are reported by email and on dashboards.
- **A command & control center**: the root of `home.keithjackson.dev` is a UI that surfaces and
  controls everything running in the cluster.
- **Provable conformance**: every requirement is verified by an automated, reproducible, behavior-
  based test — and the specifications themselves are human-owned and immutable to the implementing
  agents.

## Two environments

| Environment | Substrate | Purpose | Status |
|---|---|---|---|
| **dev/test** | Local KVM virtual machines on a workstation, provisioned by IaC | Prove the platform end-to-end before hardware exists | **Active development target** |
| **prod** | 3× mini-PC bare-metal k3s cluster, each with local storage | The real deployment | **Not ready — design for it, do not build on it yet** |

The dev/test environment is the proving ground. Everything must be authored so that the *same*
GitOps configuration promotes to production with only environment-scoped overrides.

## How to use this repository (start here)

1. **Read [`AGENTS.md`](AGENTS.md)** — the rules of engagement for every AI agent working here.
2. **Read [`docs/00-vision-and-scope.md`](docs/00-vision-and-scope.md)** — the north star and the
   non-negotiable requirements (with stable requirement IDs).
3. **Read [`docs/01-architecture-overview.md`](docs/01-architecture-overview.md)** — the chosen
   stack and how the pieces fit.
4. **Consult [`decisions/`](decisions/)** — the Architecture Decision Records (ADRs) that lock in
   every major technology choice and *why*. Do not re-litigate a decision; if you disagree, open a
   superseding ADR per the process in [`decisions/README.md`](decisions/README.md).
5. **Pick up work from [`roadmap/`](roadmap/) and [`agents/task-board.md`](agents/task-board.md)** —
   phased delivery plan, workstreams, dependencies, and the live task board.

## Repository map

```
home-network-k3s/
├── README.md                     ← you are here
├── AGENTS.md                     ← rules of engagement for AI agents
├── CONTRIBUTING.md               ← git workflow (feature branches → main; Gitea/CI-CD to come)
├── GLOSSARY.md                   ← shared vocabulary (read to avoid ambiguity)
├── docs/                         ← the specification, by domain
│   ├── 00-vision-and-scope.md
│   ├── 01-architecture-overview.md
│   ├── 02-environments-and-provisioning.md
│   ├── 03-networking-isolation-and-egress.md
│   ├── 04-storage-and-state.md
│   ├── 05-gitops-and-delivery.md
│   ├── 06-vm-workloads-kubevirt.md
│   ├── 07-security-and-secrets.md
│   ├── 08-tls-and-certificates.md
│   ├── 09-dns-and-ingress.md
│   ├── 10-observability-and-alerting.md
│   ├── 11-automated-updates.md
│   ├── 12-command-center-ui.md
│   ├── 13-service-catalog.md
│   ├── 14-testing-and-conformance.md
│   └── 15-identity-and-access.md
├── decisions/                    ← ADRs (one decision per file) + index/template
├── roadmap/                      ← phases.md, workstreams.md
└── agents/                       ← roles, coordination protocol, DoD, task board
```

## Requirement traceability

Every hard requirement has a stable ID (e.g. `R-NET-01`) defined in
[`docs/00-vision-and-scope.md`](docs/00-vision-and-scope.md). Implementation work, ADRs, and
task-board items must reference the requirement IDs they satisfy. This is how we prove the built
system meets the spec.

## Ground rules (the short version — full detail in `AGENTS.md`)

- **Specs are the source of truth — and are immutable to agents.** Code and tests serve the spec.
  AI agents **may not change** the `docs/`, requirements, or accepted ADRs; a spec that is wrong or
  can't be met is an **escalation to the human**, never an edit (R-TEST-06).
- **Done means a green, reproducible, behavior-based test.** Every requirement is verified by an
  automated, requirement-tagged conformance test ([`docs/14-testing-and-conformance.md`](docs/14-testing-and-conformance.md),
  [ADR-0010](decisions/adr-0010-conformance-testing.md)); a manual demo or "it merged" is not
  acceptance.
- **Everything is GitOps.** No click-ops in the cluster except where an ADR explicitly allows it.
- **Nothing is self-signed, nothing is manual, nothing loses data.** These three properties are
  acceptance gates, not aspirations — and each is proven by a test.
- **Design once, deploy to two environments.** dev/test and prod differ only by scoped overrides.