Homelab: Current Architecture

Four hosts. 50+ containers. One Tailscale mesh. One Mac as control plane. Diagrams first, words second.

By the numbers

Fleet

Host roles

• hetzner : single ingress. Runs traefik, mail, media UI, observability stack, secrets vault, auth, DNS. Only host with public ports 80/443 (Cloudflare proxied).
• oci : distributed worker. ARM64 box on Oracle's free tier. Runs unmanic transcoding workers, secondary technitium DNS, and an experimental Coolify PaaS install. Now also publicly exposed (80/443) for Coolify-deployed preview apps.
• transmission : torrent client behind a Mullvad WireGuard tunnel, fully isolated. Other hosts reach it over Tailscale only.
• rpi : Raspberry Pi 5 sitting in my apartment on residential internet. Runs bar-app (cocktail recipe tool) and meilisearch. Doesn't mount the storagebox.

Host capacity

Hetzner service map

Subdomain reference

*.kanishksachdev.com points at hetzner public IP via Cloudflare proxy. *.preview.kanishksachdev.com is gray-clouded and points at OCI public IP directly (free-plan nested-wildcard SSL limitation).

Request flow

Defense in depth

Media pipeline

Observability data plane

Ansible (the control plane)

Ansible is the only thing that touches all 4 hosts. It lives in ansible/ inside the parent repo. Control node is the Mac, deliberately, so we never have the circular problem of "manage hetzner from a process running on hetzner".

Playbook reference

Role reference

Inventory

# ansible/inventory/hosts.yml (IPs redacted)
all:
  children:
    homelab:
      hosts:
        hetzner:       { ansible_host: <tailscale-ip>, ansible_user: root }
        oci:           { ansible_host: <tailscale-ip>, ansible_user: opc }
        transmission:  { ansible_host: <tailscale-ip>, ansible_user: root }
        rpi:           { ansible_host: <tailscale-ip>, ansible_user: kanishk }

# ansible/inventory/host_vars/hetzner.yml (excerpt)
repo_dest:     /root
compose_dir:   /root
env_prefix:    <PREFIX>_              # all <PREFIX>_* Infisical secrets land here
env_file_path: ~/.env
infisical_files:                      # arbitrary single-file secrets
  - secret: <PREFIX>_<SECRET_NAME>
    dest:   ~/.some-credentials
    mode:   "0600"

Each of the 4 hosts has its own host_vars/<host>.yml. That file is the contract: what user to SSH as, where the git checkout lives, where to render the .env, what secret prefix to scope to in Infisical.

Conventions

• No global become. Tasks declare become: true only when they actually need root. OCI's opc user has docker group + passwordless sudo; root users (hetzner, transmission) don't need escalation.
• Idempotency is non-negotiable. Every playbook here is safe to run repeatedly. changed_when: false on read-only tasks, HEAD-comparison gates on expensive ones (image prune).
• Host key checking is disabled. Tailscale already authenticates the network. Don't re-enable without seeding known_hosts first.
• Per-host deploy keys, read-only. One compromised VPS can only read its own repo. No push, no access to siblings.
• result_format: yaml in ansible.cfg so playbook output is readable instead of the default Python repr.

Common operations

# from ~/personal/homelab-config/ansible/

ansible all -m ping                                       # liveness
ansible-playbook playbooks/status.yml                     # fleet health
ansible-playbook playbooks/deploy.yml                     # deploy to all
ansible-playbook playbooks/deploy.yml --limit hetzner     # one host
ansible-playbook playbooks/restart.yml --limit hetzner -e service=crowdsec
ansible-playbook playbooks/bootstrap.yml --limit newhost  # set up a fresh host
ansible-playbook playbooks/backup.yml --limit hetzner     # refresh borg units

Deploy pipeline (GitOps)

What git push actually triggers

Adding a new app

PaaS sublayer (Coolify on OCI)

State / data lifecycle

Backups

Failure modes / blast radius

The single highest-impact single point of failure is the Hetzner Storage Box because it's both the media data plane AND the backup target. Top of the deferred-work list to fix.

CrowdSec mechanics

Authentik blueprint mechanics

Everything in Authentik is declarative YAML in hetzner-vps-config/authentik/blueprints/. Blueprints get discovered on a polling interval, applied automatically, status visible in the admin UI.

Recovery flow

Invitation enrollment flow

Authentik access matrix

Dependency & freshness loop

Cost breakdown

Comparable managed equivalents: $20 Vercel + $15 1Password + $10 Auth0 + $15 Notion + $10 Bitwarden + $30 Plex Pass + $20 ProtonMail = $120+/month easily.

Things that look weird but are intentional

Submodule layout

Deferred work

These are known and intentionally not yet fixed (in priority order).

1. No backups for OCI / transmission / rpi. Hetzner-only. Tooling exists (just need to install borg + systemd units + a separate borg repo).
2. Storagebox itself unbacked. Both the media library and the borg backup target. Single failure domain.
3. No DB-consistent dumps. Postgres and MariaDB volumes captured mid-write by borg. Restores are best-effort.
4. No off-provider backup destination. Hetzner VPS and Hetzner Storage Box are the same vendor. Migrating borg to Backblaze B2 or similar is next.
5. A couple of remaining services to wire through the Authentik forward-auth layer. Pattern is documented and trivial; just queued up.
6. SSH deploy key bootstrap is manual. Adding a key to a new VPS requires generating it on the box and pasting the pubkey into GitHub via browser.
7. Coolify state on OCI not in git. Coolify manages its own DB. Losing OCI means redoing the Coolify config + redeploying every app.
8. text_readonly vs conditional locking on enrollment email. Currently email field is always read-only on invite enrollment (admin must always set it). Could be made conditional with a policy.

Stack at a glance

Operating principles

• If it's not committed, it's not deployed. The Mac is the trigger, never the source of file content. The VPS pulls from GitHub.
• Idempotency is non-negotiable. Every Ansible playbook is safe to re-run. Re-running deploy.yml on an unchanged HEAD is a true no-op.
• No global become. Tasks declare become: true only when they actually need root.
• Per-host deploy keys, read-only. One compromised VPS can only read its own repo, not push, not access other repos.
• Named volumes only. State stays out of the git checkout; backups handle the rest.
• One ingress. All public HTTP enters through hetzner traefik (except Coolify previews, which intentionally bypass).
• One source of truth per concept. Secrets in Infisical, code in git, runtime state in named volumes, bulk in storagebox. No duplication.