Homelab

Infrastructure-as-code and documentation for Colin's homelab — a single Beelink mini-PC running containerised services behind Tailscale and Cloudflare Tunnel, deployed via GitHub Actions.

Quickstart

mise install          # Install Python, uv, shellcheck, actionlint, trivy
mise run lint         # Lint everything (Python, bash, YAML, Actions)
mise run typecheck    # Type-check Python
mise run test         # Run pytest
mise run ci           # All of the above + validate compose files

On the server:

mise run deploy:all          # Deploy all stacks
mise run check:health        # Health check all services
mise run check:vulnerabilities  # Scan images for CVEs

Current Services

Service	Purpose	Managed By
Flight Tracker	Real-time aviation dashboard (FastAPI + React)	Docker Compose (stacks/flight-tracker/)
Cloudflared	Public ingress via Cloudflare Tunnel	Docker Compose (stacks/flight-tracker/)
Home Assistant	Home automation (Bluetooth, mDNS)	Docker Compose (stacks/home-assistant/)
MQTT (Mosquitto)	Message broker for HA sensors	Docker Compose (stacks/mqtt/)
Grafana	Dashboards — metrics, logs, alerts	Docker Compose (stacks/observability/)
Prometheus	Metrics storage (30d retention)	Docker Compose (stacks/observability/)
Loki	Log aggregation (30d retention)	Docker Compose (stacks/observability/)
Grafana Alloy	Unified collector (host + container metrics/logs)	Docker Compose (stacks/observability/)
CrowdSec	Collaborative IDS + firewall bouncer	Docker Compose (stacks/crowdsec/)
Knowledge Base	Postgres 17 + pgvector — semantic search over personal notes	Docker Compose (stacks/knowledge/)
Homelab Agent	AI review + issue implementation via Copilot CLI (GPT-5.4)	Docker Compose (stacks/agents/)

Hardware

• Beelink mini-PC — Ubuntu 24.04 LTS, ~16 GB RAM, 466 GB SSD (10% used)
• Network — LAN, Tailscale mesh, IPv6 via ISP (no public IPv4)

Network Topology

Internet
  │
  ├─ Cloudflare Tunnel ──→ Public services (flight-tracker API)
  │
  └─ Tailscale ──→ Admin access (SSH, Home Assistant, Grafana)
         │
         └─ ACLs: desktop=full, mobile=HA only

Deploy Flow

Push to main
  → Self-hosted runner on beelink detects changed stacks
  → Generates .env from GitHub secrets + .env.example templates
  → docker compose up

Tooling

Tool	Purpose
mise	Task runner + tool version manager
uv	Python package management
ruff	Python lint + format
ty	Python type checking
pydantic	Structured models for audits
trivy	Docker image CVE scanning
Renovate	Automated dependency PRs

Observability

Grafana (:3001) ← Prometheus (metrics) ← Alloy (host + container scraping)
                ← Loki (logs)          ← Alloy (Docker log collection)
                                        ← CrowdSec (security metrics)

• Dashboards: Container Overview, Agent Tasks, Security (pre-provisioned)
• Alerting: CPU >80%, RAM >90%, Disk >80% → private Discord channel
• Security: CrowdSec IDS with collaborative threat intel + UFW firewall bouncer
• External: Healthchecks.io heartbeat (alerts on full server outage)

Security

UFW firewall active (deny all except Tailscale), CrowdSec IDS with collaborative threat intel and UFW firewall bouncer, automatic security patches enabled, Tailscale ACLs enforcing least-privilege access. Full audit and hardening details in security.md (encrypted — clone + git-crypt unlock to read).

Documentation

All docs are plain markdown — open docs/ as an Obsidian vault if you prefer.

Documentation ownership rules and refresh triggers live in ADR-008.

Surface	Purpose
README.md	Repo map, operator quickstart, and index into deeper docs
docs/roadmap.md	Active work, planned items, and current limitations
docs/decisions/	Accepted architecture, security, and repeating-pattern decisions
docs/runbooks/	Copy-pasteable operational procedures
docs/private/	Encrypted sensitive docs (security posture, topology, credentials-adjacent ops)
.github/	Agent-facing authoring guide, instructions, and skills

• Roadmap — active work, planned items, and known limitations
• Architecture Overview — top-level map of the Beelink, stacks, networking, and deploy path
• Agent Lifecycle — end-to-end /implement and /review flow, trust model, and worker ownership
• Observability — where logs, metrics, dashboards, and alerts live when things break
• Security — audit findings, hardening status, periodic checklist (encrypted)
• Network — topology, interfaces, traffic monitoring plan (encrypted)
• Copilot Authoring Guide — how agent-facing .github docs are organized

Decisions (append-only ADRs)

Browse docs/decisions/ for the full list. ADRs are numbered sequentially — each captures an architecture, security, or repeating-pattern decision with tradeoffs and alternatives considered.

Runbooks

Browse docs/runbooks/ for operational procedures — deploying services, operating the agent stack, and migration references.