Homelab Documentation¶
Welcome to my homelab docs. This covers the k3s cluster running on a self-hosted Proxmox server, managed via GitOps with Flux CD.
Cluster overview¶
| Component | Details |
|---|---|
| Hypervisor | Proxmox |
| k3s version | v1.34.x |
| Nodes | 1 server + 2 agents |
| Networking | Flannel (VXLAN) + Tailscale operator |
| Storage | Longhorn (distributed) |
| GitOps | Flux CD |
| Ingress | Traefik (Cloudflare Tunnel *.example.com) + Tailscale operator (*.tailnet.ts.net) |
| TLS | cert-manager + Let's Encrypt (Cloudflare path); Tailscale (Tailscale path) |
Key services¶
| Service | URL | Notes |
|---|---|---|
| Authentik | authentik.tailnet.ts.net |
SSO / identity provider |
| AdGuard Home | adguard.tailnet.ts.net |
DNS ad-blocking + LAN DNS via MetalLB |
| Dashy | dashy.tailnet.ts.net |
Service dashboard |
| Uptime Kuma | uptime-kuma.tailnet.ts.net · uptime.example.com (public) |
Uptime monitoring |
| Jellyfin | jellyfin.tailnet.ts.net · jellyfin.example.com (public) |
Media server |
| FileBrowser | jellyfin-files.tailnet.ts.net |
Web file manager |
| Transmission | jellyfin-transmission.tailnet.ts.net |
BitTorrent client |
| Metube | jellyfin-ytdl.tailnet.ts.net |
YouTube downloader |
| Calibre-Web | calibre-web.tailnet.ts.net · calibre.example.com (public) |
Ebook library |
| Stalwart Mail | mail.tailnet.ts.net · mail.example.com (public) |
Mail server |
| Ntfy | ntfy.tailnet.ts.net |
Push notifications |
| Grafana / Prometheus | grafana.tailnet.ts.net / prometheus.tailnet.ts.net |
Monitoring (see monitoring.md) |
| Docs (this site) | docs.chronobyte.net (public, GitHub Pages) |
Documentation |
| Fail2ban | - | DaemonSet on all nodes - managed via Ansible |
Guides¶
- GitOps with Flux CD - Bootstrap, adding services, patched secrets
- Adding a New Service - End-to-end guide: manifests → Flux → ingress → Authentik
- Cloudflare Tunnels - Public ingress via Cloudflare Tunnel
- Tailscale Operator - Exposing services on the tailnet
- Flannel over Tailscale - Cross-node pod networking via Tailscale IPs
- Manifests & Helm - Cluster overview and manual
kubectl/helmescape hatches - Monitoring - Prometheus, Grafana, and alerting
- Disaster Recovery - Full rebuild from scratch
- Fail2ban - DaemonSet deployment, jail config, ban management, troubleshooting
Authentik & Identity¶
Authentik manages all SSO, OIDC, LDAP, and ForwardAuth for this cluster. Its configuration
(flows, providers, applications, outposts) is managed declaratively via OpenTofu IaC in
opentofu/authentik*.tf. New users are onboarded via an invitation workflow
(.github/workflows/authentik-invite.yml) that emails a single-use enrollment link.
See authentik.md for the full architecture, IaC structure, and invitation process.