sjat/boma
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity
boma/docs/CAPABILITIES.md
sjat 175777e36a docs: reconcile 2026-06-14 review findings (O1-O7,O18,O22) 
- STATUS: docker_host is built+applied, not scaffold-only (O1)
- ADR-004: backup points to ADR-022, not "out of scope"; service-role file
  table gains ACCESS.md + BACKUP.md rows (O2, O5)
- Finish Traefik->Caddy: ADR-008/011/017/019, CAPABILITIES, TODO (O3); scope
  ADR-024's custom-image/NetBird claims to the deferred DNS-01/M4b paths (O22)
- ADR-016/017/018 now lead with ## Status per ADR-023 (O4)
- ADR-002: caveat `PLAYBOOK=upgrade` as planned/unbuilt (O6)
- CAPABILITIES: carve out ubongo's dev_env from the nvim/tmux exclusion (O7)
- ADR-007: one authoritative boma.baobab.band -> boma.wingu.me transition note (O18)
- new-host Part E: note ubongo is managed as sjat, ansible-user bootstrap pending (O15)

O9 (hosts.yml header) left open: the file is generator-owned (hook-protected);
fixing it needs a tf_to_inventory.py change or a tf-inventory run, not a hand-edit.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-06-14 19:06:33 +02:00

11 KiB
Raw Blame History

boma capabilities overview

A high-level, living map of what boma is intended to do — organised by capability domain, decided on boma's own terms. This is the frame of reference for "what does what" alignment, for judging which tools/plugins are relevant, and (later) for planning what runs on which node. It is intent, not status — see STATUS.md for what actually exists.

Decided fresh per ADR-013 (V4 is not a source of scope); a V4 completeness check is recorded at the bottom. Individual service picks (e.g. Jellyfin vs Plex) and node placement are surfaced here, not resolved here — they are downstream decisions this frame enables.

Legend

  • Tier — P platform (others depend on it) · A user-facing app · S supporting
  • Commitment — core (foundational, committed) · planned (intended) · candidate (wanted, option not settled) · maybe-later (nice to have)
  • ⚠️ = interacts with an existing ADR; reconcile before building.

1. Edge & networking — [P]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Reverse proxy / TLS Caddy (ADR-024) P core Edge routing + ACME certs for everything exposed Spin-up order names it (TODO 12)
Internal DNS dns role → dns1/dns2 P core Authoritative internal zone (ADR-007) Ansible-rendered zone
Public DNS public_dns role → Gandi LiveDNS P core wingu.me zone as code (ADR-007) anti-spoof baseline; mesh/LAN-only default; applied (M1)
VPN / remote access NetBird (self-hosted on askari) P core Secure mesh remote access to srv/mgmt Decided (ADR-016): NetBird mesh replaces ADR-007 OPNsense WireGuard
Service portal / dashboard Homepage A candidate One landing page listing all services — a "what does what" front door Gap surfaced by V4; fits boma's legibility goal

(DHCP, firewall, mDNS reflection live on OPNsense — Ansible-managed, not containers.)

Firewalling is two-layer (ADR-020): OPNsense at the perimeter + inter-VLAN, plus per-host nftables (default-deny inbound + east-west allowlist) rendered by the base role from a shared group_vars service catalog. The host nftables layer is built (the base firewall concern); the OPNsense layer is still to be built.

2. Identity & access — [P]

Capability Candidate service(s) Tier Commitment What it does Notes / open
SSO / identity provider Authentik P planned Central auth / forward-auth for exposed services Named in spin-up order (TODO 12)
Secrets / password vault Vaultwarden P core Personal vault; also holds the Ansible vault master password Already used by rbw (ADR-002)

3. Observability — [P]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Metrics Prometheus P planned Time-series metrics + alert rules TODO 3.6
Logs Loki (cluster all-logs + off-site security subset on askari) P core Central log aggregation; a security subset ships write-only off-site (append-only) Decided (ADR-018)
Log shipping agent Grafana Alloy (in base) P core Collects journald + container + security logs on every host; ships to Loki (ADR-018) Decided (ADR-018)
Dashboards Grafana P planned Visualisation + alerting (incl. AIDE/auditd/fail2ban/Suricata + log-silence — ADR-018) TODO 3.6
Uptime checks Uptime Kuma P planned Endpoint up/down checks TODO 3.6
External watchdog askari (Hetzner VPS) P core Off-site monitoring that survives a homelab outage ADR-007
Notify / alerting ntfy · Matrix · email (multi-channel) S planned Deliver alerts to the user across channels TODO 9; Matrix homeserver in §8
Metric exporters node_exporter, cAdvisor, … S planned Feed Prometheus per host/service

4. Source & CI — [P/A]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Git hosting Forgejo P/A core Repo hosting + off-machine backup Live (ADR-010)
CI runner Forgejo Actions (act_runner) P planned Pipelines (lint/test/deploy) ADR-010 / ADR-008

5. Home automation & IoT — [A]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Automation hub Home Assistant A planned IoT controller; bridges srv↔iot ADR-007 (10.20.0.13)
Device messaging MQTT broker (Mosquitto) S candidate Messaging backbone for HA/devices Only if devices need it
Radio / firmware bridges Zigbee2MQTT · ESPHome S maybe-later Zigbee/ESP device integration Hardware-dependent

6. Media — [A]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Media server Jellyfin · vs Plex A candidate Stream media to the household Jellyfin = FOSS default
Library automation *arr stack (Sonarr/Radarr/…) A candidate Acquire/organise media ADR-011 example
Download client qBittorrent (+ VPN) S candidate Fetching Egress isolation needed
Indexer helper FlareSolverr S candidate CAPTCHA/Cloudflare for indexers ADR-011 example
Books / audiobooks / podcasts Audiobookshelf · Calibre-Web · (Readarr) A candidate Ebook + audiobook + podcast library Gap surfaced by V4; video-only was too narrow
Download VPN egress Gluetun S candidate Routes the download client through a commercial VPN Pairs with qBittorrent

7. Personal cloud & files — [A]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Files / sync Nextcloud A planned Personal cloud, file sync & share; CalDAV/CardDAV (contacts & calendar) ADR-011
Photos PhotoPrism · vs Immich A candidate Photo library + phone backup ADR-011 lists PhotoPrism; Immich is the modern alt
Office documents Collabora Online A candidate In-browser document editing for Nextcloud Gap surfaced by V4
LAN file shares Samba · NFS S candidate Raw SMB/NFS shares (distinct from Nextcloud sync) Gap surfaced by V4; only if a direct-share need exists

8. Communications — [A]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Real-time chat Matrix homeserver (Synapse · vs Conduit) A planned Self-hosted messaging; also an alert route Stateful + internet-facing → careful exposure, own SECURITY.md
Bridges mautrix-* S maybe-later Bridge other networks into Matrix After the homeserver is stable
Self-hosted email Poste.io · Mailcow A maybe-later Run boma's own mail server ⚠️ Deliverability + security are heavy; V4 ran one — re-justify hard before committing

9. Data & backup — [P/S]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Databases Postgres/MariaDB — central vs per-app P candidate Backing store for stateful apps Open: central server vs per-service (TODO 3.9)
Backup engine restic (data-only) S planned Per-service state: file dirs + logical DB dumps, pulled by fisi ADR-022 (PBS deferred)
Off-site target pCloud (via rclone) S planned Encrypted off-site copy of the restic repo (3-2-1) ADR-022; sync-coupled
Air-gap target USB hard drives S planned Rotated offline cold copy — the immutable backstop ADR-022; udev-triggered restic copy

10. Operations & support — [S]

Capability Candidate service(s) Tier Commitment What it does Notes / open
Update watcher DIUN S planned New-image alerts driving the update process ADR-011
Scheduled jobs scheduled_jobs role + claude -p jobs S planned Declarative cron: /review-repo, security/capacity reviews, sanity checks TODO 8
Sanity / smoke whoami + health checks S planned Verification endpoints + "is it actually working" checks ADR-011 / TODO 8.2
Service-UI verification /verify-service skill S planned Claude-driven exploratory Level 4 acceptance check of a deployed service's UI Decided (ADR-017); running deferred on ubongo + playwright + Authentik
  • Targeted runs (ADR-019): playbooks are sliced with --tags along two axes — role/service (tag = role name) or a closed list of cross-cutting concerns (firewall, logging, config, deploy, …); the vocabulary is lint-enforced.

V4 completeness check

Run against AnsibleBaobabV4's role set per ADR-013/014 — used only as a coverage check, not a source of scope. Each finding was re-justified on boma's terms before it changed anything here.

Strong alignment (confirms the fresh frame). Most of boma's picks correspond to services V4 actually ran: Traefik, DNS, Vaultwarden, Forgejo (+runner), Prometheus, Grafana, Grafana-Alloy, Loki, Uptime Kuma, exporters, ntfy, DIUN, Nextcloud (+db), PhotoPrism (+db), Jellyfin, the *arr stack, qBittorrent, FlareSolverr, Home Assistant, a Matrix homeserver (V4: Conduwuit) + Element web client, WireGuard, backups (incl. cloud). That overlap is reassuring — these were arrived at independently and match.

Gaps it surfaced (added above as candidate/maybe-later, re-justified): books/ audiobooks/podcasts library; Gluetun download-VPN egress; Collabora office docs; Samba/NFS LAN shares; CalDAV/CardDAV via Nextcloud; a service portal (Homepage); self-hosted email (parked maybe-later — heavy). Also noted: a Matrix deployment needs a client (Element web), not just the homeserver.

Long-tail surfaced but parked (maybe-later, not added as rows): local self-hosted AI/LLM, a game server (Minecraft), generic static-site hosting. Plausible someday; none are committed.

Confirmed exclusions (V4 had them; boma deliberately does not). V4 mixed in a lot of workstation/desktop config — XFCE/GNOME desktops, kiosk mode, LibreOffice, antivirus, remote desktop. boma's managed cluster/server hosts stay server-only, so these are correctly absent. (One scoped exception: the control / AI-worker host ubongo runs an interactive dev_env — zsh/tmux/neovim — per ADR-015; that is the developer environment of an infrastructure worker host, not a personal desktop, and does not apply to managed service hosts.) Likewise the removed Knowledge domain (Discourse, Snipe-IT, MRBS booking) and V4-specific project websites — out of boma's scope by design. The narrower surface is intentional, not an oversight.