Docs
SSO-protectedHomelab documentation. Architecture, plans, runbooks, security, and recovery procedures.
architecture
Overview
Hardware, services, and architecture at a glance.
Network
DNS, routing, and external access configuration.
Observability
Prometheus, Grafana, Loki, Alloy, and Tempo configuration.
Build pipeline
How images are built, pushed, and deployed across the homelab.
Infrastructure as code
The standard every host and guest follows: which tool owns which layer, how a host's role is laid out and named, how Ansible reaches it, where secrets and version pins live, the gate, what done means, and the checklist for moving a host off its scripts.
plans
AI gateway and per-app chat
The AI stack's design: one LiteLLM gateway for every model call, the Vercel AI SDK at each app's edge, Open WebUI as household chat, and the stages still ahead.
Testing the configs against the programs that load them
Unscheduled plan: static checks that refuse at the commit, a booted Grafana that refuses at the deploy, and CI for what needs Docker.
Consolidating the NAS stacks onto pve-one
The plan of record for moving the Synology stacks into one apps VM on pve-one: guest layout, the decisions with their evidence, the migration phases, and what stays unverified.
runbooks
Change Flow
How a change reaches the NAS, pve-one's host, the OpenTofu guests and the VPS: who does each step, the exact commands, where secrets live, and the overrides.
Daily Operations
Common deployment and update workflows.
Authentik
SSO management, restart, OIDC, upgrades.
Deploy
Deploying the NAS and pve-one from verified commits: the normal run, a refusal, the override, and the Deploy Lag alert.
CrowdSec
IP unblock, decision listing, alerts.
Traefik
Reverse proxy debugging, certificates, routing.
Pi-hole
DNS operations and cache management.
WireGuard
Tunnel status and troubleshooting.
VPS
The Ansible role that configures it, the nginx proxy, WireGuard traffic control and the fallback page.
DSM Update
What a DSM or Container Manager update resets: nginx ports, UDP buffers, buildx.
Loki
Log queries, retention, Alloy reload and DSM syslog forwarding.
Immich
Photo server maintenance.
Registry
The Zot image registry: push, pull, retention, garbage collection and integrity checks.
Sites
The site-* images: shipping an update, adding a site, deploy keys, the Site Stats Stale alert, the port inventory.
Cash Money
Personal finance app — household FI dashboard, booking pipeline, mileage.
Useful Commands
General Docker and NAS commands.
Home Assistant
The HAOS VM — how to reach it from the shell, where its config and backups actually live, and the health checks worth running.
Media
Jellyfin, the *arr suite, qBittorrent, and the family request flow.
Homepage
The dashboard at dashboard.gread.uk — config, icons, widgets, and why a change hasn't shown up.
Docker Wedge
A container stops answering the Docker API; recovery without a reboot.
Garden
Garden planner app — deploys, backups, restore, metrics and logs.
AI Gateway
LiteLLM gateway for every app's model calls — deploy, keys, budgets, spend.
Chat
Open WebUI household chat — first deploy, users, models, backups and restore.
Proxmox
pve-one: apply config, runners, network and firewall changes, and the host's failure modes.
Host Alerts
A disk, temperature, link, clock or systemd alert on the NAS, the VPS, pve-one or its runner VM.