docs: publish 2026-04-27

docs/NETWORK.md

@@ -0,0 +1,39 @@
+# Network
+
+## Trust tiers
+
+| Tier | What's on it | Posture |
+|---|---|---|
+| Management | Hypervisor, firewall, backup server, network controllers | Most trusted. VPN-only. No outbound unless required. |
+| Internal services | LXCs and VMs running the app stack | Trusted. Serves clients in adjacent tiers per policy. |
+| LAN | Personal devices on home WiFi/Ethernet | Trusted. Consumes internal services. |
+| Work-from-home | Employer-owned laptop | Untrusted lateral. Internet only. Blocked from everything internal, including DNS. |
+| IoT | Smart devices, cloud-managed appliances | Untrusted. Internet only. Isolated from internal. |
+| Guest | Visitor WiFi | Untrusted. Internet only. |
+| DMZ | Internet-facing services | Treated as compromised by default. Tight inbound allowlist to internal. |
+| VPN (WireGuard) | Authenticated remote clients | Same posture as LAN, plus admin-tier visibility. |
+
+## Policy
+
+- Default deny inter-VLAN. Every cross-tier flow is an explicit allow rule with a reason.
+- WFH and IoT are restricted to internet only. Nothing internal, including DNS for local hostnames.
+- Management is kept minimal. Only what runs the lab lives there.
+- DMZ is one-way. Public services in there can only initiate inward through a firewall-enforced allowlist by source IP + destination port with reverse proxy reinforcing.
+- Admin only accessible via Management + VPN
+
+## DNS
+
+Three layers:
+
+1. **Pi-hole** — first hop for clients on most VLANs. Filters ad/tracker domains and holds local A records. Not used by Management hosts or by the WFH VLAN.
+2. **Unbound on the firewall** — Pi-hole's upstream. Recursive resolver, validates DNSSEC.
+3. **Cloudflare** — Unbound's upstream when needed.
+
+The hypervisor (which is the box Pi-hole runs on) statically resolves through the firewall, not Pi-hole. If it didn't, there'd be a circular dependency at boot.
+
+## Internet exposure
+
+Three ports forwarded from WAN:
+
+- HTTP and HTTPS to the DMZ reverse proxy.
+- WireGuard to the firewall.

docs/SECURITY.md

@@ -0,0 +1,23 @@
+# Security
+
+## Threat model
+
+One-person homelab on a residential connection.
+
+## Update 
+
+- Edge components: patched promptly when CVEs land.
+- Hypervisor and backup server: quarterly review, with security patches applied when needed.
+- Application LXCs: rolling updates on a regular schedule. certain ones take precent
+- Container images: re-pulled on the same rolling schedule.
+
+## Backups
+
+Hypervisor-level backups go to a dedicated backup server. Conservative retentions and backups are verified periofically.The rebuild order is documented. 
+
+## Limitations
+
+This is a learning environment.
+
+- No High Availability - One hypervisor, one firewall
+- One-person ops

docs/SERVICES.md

@@ -0,0 +1,97 @@
+# Services
+
+## Identity & access
+
+| Service | What it does |
+|---|---|
+| Authentik | SSO for internal services, OIDC where supported + caddy forward auth otherwis |
+| Pi-hole | LAN DNS, ad blocking + source of truth for internal hostnames |
+| WireGuard | remote access |
+
+## Reverse proxy & TLS
+
+Two Caddy instances:
+
+- **Internal Caddy** fronts everything internal. LAN or VPN only.
+- **DMZ Caddy** fronts the public services. Lives on its own VLAN with a firewall-enforced allowlist into internal.
+
+Both use Cloudflare DNS-01 for ACME, which lets internal-only services get valid public certs without being exposed for issuance.
+
+## Productivity & knowledge
+
+| Service | What it replaces |
+|---|---|
+| Outline | notion |
+| Vikunja | todoist / asana |
+| Hoarder | pocket / raindrop |
+| Memos | apple nnotes |
+| FreshRSS | feedly |
+| Bytestash | gist / pastebin |
+| Filebrowser | dropbox |
+| Baikal | iCloud calendar/contacts (CalDAV / CardDAV) |
+
+## Money
+
+| Service | What it replaces |
+|---|---|
+| Actual Budget | YNAB |
+| Ghostfolio | personal capital |
+
+## Operations
+
+| Service | What it does |
+|---|---|
+| Grist | lightweight excel type |
+| Glance | personal homepage |
+| Traggo | time tracking |
+
+## Media
+
+| Service | What it does |
+|---|---|
+| Plex | mdia library (legacy clients) |
+| Jellyfin | media library (primary) |
+| *arr stack | library automation |
+| qBittorrent | Downloads |
+| Immich | photo backup and viewing |
+
+## Home / IoT
+
+| Service | What it does |
+|---|---|
+| Home Assistant OS | home automation hub |
+
+## Secrets
+
+| Service | What it does |
+|---|---|
+| Vaultwarden | bitwarden-compatible password manager *Planned, not deployed yet |
+
+## Bots & automation
+
+| Service | What it does |
+|---|---|
+| Vocard | discord music bot |
+| MonitorRSS | rss-to-discord feed |
+| ntfy | push notifications for ops alerts |
+
+## Monitoring
+
+| Service | What it does |
+|---|---|
+| Victoria Metrics | time-series store |
+| Grafana | dashboards |
+| Beszel | host metrics |
+| Uptime Kuma | uptime checks |
+
+## Public services
+
+A small set behind the DMZ reverse proxy on a VLAN with no inbound to internal.
+
+| Service | Why it's public |
+|---|---|
+| Portfolio | it's a portfolio |
+| Self-hosted Git | so you can read this |
+| SSO endpoint | required for the OIDC flow on the Discord bot dashboard. the firewall is enabled so that the public proxy can only reach this one internal backend |
+| Discord bot dashboard | so my friends can use pick tunes. authentik forward auth gates it |
+