Docker and Ansible for homelab stack
  • Python 54.5%
  • Shell 21.7%
  • HTML 18.8%
  • Jinja 2.4%
  • CSS 1.6%
  • Other 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
tim fdaa9990cb Save the Flint 2 bridge plan and a redacted copy of the gateway layout.
The spare stays unprogrammed. Firmware images and the gateway backup stay on this workstation and out of git because the backup holds the Wi-Fi passphrase.
2026-11-15 23:07:31 -08:00
admin-panel Remove the local chat UI, model, and OpenHands from this host. 2026-11-07 11:24:58 -08:00
ai Tell agents they can open the KeePassXC database on Arr-Stack when the workstation mount is down. 2026-11-13 17:40:17 -08:00
ansible Remove the local chat UI, model, and OpenHands from this host. 2026-11-07 11:24:58 -08:00
bookstack Remove the local chat UI, model, and OpenHands from this host. 2026-11-07 11:24:58 -08:00
docs Save the CrowdSec plan without installing it. 2026-11-15 22:48:13 -08:00
flint2 Save the Flint 2 bridge plan and a redacted copy of the gateway layout. 2026-11-15 23:07:31 -08:00
landing Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
llm-prompts Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
models/bonsai Initial commit: arr-stack homelab + local AI 2026-07-22 06:28:49 -07:00
netbird Stop NetBird from becoming the default resolver and bind the routing peer DNS to loopback. 2026-08-15 16:27:14 -07:00
profiles Add Unsloth Qwen3.8-27B 2-bit as qwen38 on every profile that can hold 64k context. 2026-08-25 16:56:57 -07:00
scripts Point the NetBird LAN route at the current stack peer when bootstrap runs again. 2026-11-13 19:57:01 -08:00
searxng Initial commit: arr-stack homelab + local AI 2026-07-22 06:28:49 -07:00
secrets Remove the local chat UI, model, and OpenHands from this host. 2026-11-07 11:24:58 -08:00
systemd Add stack admin panel, dual-LLM switching, and always-open SSH firewall. 2026-07-23 08:24:30 -07:00
wireguard Document gluetun unhealthy caused by stale WireGuard endpoint IP 2026-07-22 11:15:35 -07:00
workspace Keep the BookStack guide in the AI workspace instead of a nested mount. 2026-10-08 17:23:00 -07:00
.env.example Add MemPalace on the LAN so agents can store and search memories. 2026-11-07 09:50:42 -08:00
.gitignore Save the Flint 2 bridge plan and a redacted copy of the gateway layout. 2026-11-15 23:07:31 -08:00
AGENTS.md Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
docker-compose.override.yml Commit Beelink mini defaults: CPU inference, 32k context 2026-07-22 19:11:20 -07:00
docker-compose.yml Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
quickstart.md Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
README.md Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
specification.html Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00
specification.json Store homelab secrets in a KeePassXC database on Arr-Stack and tell agents they may use it. 2026-11-13 17:37:31 -08:00

Arr Stack + Local AI

A dockerized media automation stack (VPN-locked torrents + Jellyfin) plus a local AI stack built around Ternary-Bonsai-27B for the Beelink SER5 PRO (Ryzen 7 7735HS + Radeon 680M).

Services

Service URL / ports Purpose
Landing http://host/ · https://devopshomelab.com/ Dark map of services (Caddy). Public site has basic auth (LANDING_BASIC_* in .env)
Jellyfin http://host:8096 · https://jellyfin.devopshomelab.com/ Media server / playback
qBittorrent http://host:8080 · https://qbittorrent… / https://qbit… Torrents VPN-locked via gluetun/WireGuard (no ISP leak)
Prowlarr http://host:9696 · https://prowlarr.devopshomelab.com/ Indexer manager
FlareSolverr (internal :8191) Cloudflare proxy for indexers
Sonarr http://host:8989 · https://sonarr.devopshomelab.com/ TV shows
Radarr http://host:7878 · https://radarr.devopshomelab.com/ Movies
Bazarr http://host:6767 · https://bazarr.devopshomelab.com/ Subtitles
Lidarr http://host:8686 · https://lidarr.devopshomelab.com/ Music
LazyLibrarian http://host:5299 · https://lazylibrarian.devopshomelab.com/ Books (ebooks / audiobooks)
SABnzbd http://host:8085 · https://sabnzbd.devopshomelab.com/ Usenet NZB downloads
Forgejo http://host:3002 · https://forgejo… / https://git… Self-hosted Git (SSH :2222). One new private repo per project for larger docs and files
MemPalace http://host:8765/mcp Agent memory (LAN + bearer token, not public)
LLM prompts http://host/llm/ Editable prompt library (LAN only, SQLite). Grok .md, Cursor .mdc, pi APPEND_SYSTEM.md
KeePassXC /opt/stack/config/keepass/homelab.kdbx Password database on the stack host. Workstation mount /mnt/arr-keepass. Prompt on the LLM prompts page.
Quoting https://quoting.devopshomelab.com/ Household quoting app (Caddy → QUOTING_UPSTREAM, default 192.168.8.135:8000)
Kasm (lights) https://lights.devopshomelab.com/ · https://192.168.8.125/ Kasm Workspaces on lights.lan (Caddy → LIGHTS_UPSTREAM, default 192.168.8.125:443)
RustDesk 21115–21119 TCP · 21116 UDP · https://rustdesk.devopshomelab.com/ (info) Self-hosted remote desktop (hbbs + hbbr)
NetBird https://netbird.devopshomelab.com/ · UDP 3478 (STUN) · UDP 51820 (WG) Self-hosted mesh VPN; overlay 100.99.0.0/16 + fd99:8:123::/48; advertises LAN 192.168.8.0/24

| Cloudflare DDNS | (host network) | Keeps A records on devopshomelab.com | | Stack admin | http://host:9090/ | Flask control panel (compose, LLM, .env) — LAN only, systemd | | Dozzle | http://host:9999/ | Live Docker logs UI — LAN only (DOZZLE_USER / DOZZLE_PASS) | | BookStack | http://host:6875 · https://bookstack.devopshomelab.com/ | Wiki. Local models share one API token (./scripts/bookstack-bootstrap.sh) |

BookStack (wiki for people and local models)

./scripts/bookstack-bootstrap.sh creates the admin (demo@stack.local / DEMO_PASS), a Stack LLMs user, and one API token. The token is BOOKSTACK_API_TOKEN in .env (id:secret) and in config/bookstack/api.env.

Agents should call http://bookstack-tools:8080 on the docker network (GET /v1/library, POST /v1/pages). From a workstation, use the BookStack API at http://192.168.8.123:6875/api/ with Authorization: Token <id>:<secret>. Update a page when the title already exists. Prefer the Stack, Runbooks, and Decisions books. Do not put secrets in a page. MariaDB (bookstack-db) is not published on the host.

MemPalace and Forgejo (memory vs files)

./scripts/mempalace-bootstrap.sh writes MEMPALACE_MCP_HTTP_TOKEN into .env, starts MemPalace, and mints a Forgejo token at config/agent/forgejo.token (gitignored). The MCP port is bound to MEMPALACE_BIND (default 192.168.8.123) and allowed from the LAN by UFW. It is not on the public Caddy proxy. Containers reach it as http://mempalace:8765/mcp with the same bearer token. This host does not run a chat UI or a model.

On a workstation, ./scripts/install-agent-memory.sh copies ai/memory-prompt.md into every Grok session (~/.grok/rules/mempalace.md), the pi agent (~/.pi/agent/APPEND_SYSTEM.md), and Cursor (~/.cursor/rules/mempalace.mdc, alwaysApply: true), and points both MCP clients at http://192.168.8.123:8765/mcp. Short memories are stored and searched in MemPalace. Larger documentation and project files go in a new private Forgejo repository per project (tim/<repo>, SSH port 2222).

The same prompt, and any you add later, is listed at http://host/llm/ (LAN only). That page is SQLite in config/llm-prompts/. Add or remove prompts there. Download a Grok .md, a Cursor .mdc, or one pi APPEND_SYSTEM.md when you want a session on another machine to carry the same text. It is not on the public HTTPS site.

KeePassXC holds passwords and the other secrets for this stack and the workstation projects. The file is /opt/stack/config/keepass/homelab.kdbx. It is not in git. On the CachyOS workstation, sudo ./scripts/install-keepass-mount.sh adds an sshfs line to /etc/fstab with noauto, nofail, x-systemd.automount, and a 10 second mount timeout, so boot and login do not wait on Arr-Stack. The mount point is /mnt/arr-keepass. The master password is one line in ~/.config/stack/keepassxc.password (and /opt/stack/config/agent/keepassxc.password on the server). ./scripts/install-agent-memory.sh installs the KeePassXC prompt next to the memory prompt. scripts/keepass-import-known.py copies known secrets into the database and prints titles only.

Keeping services documented

New services (compose or host) must update: docker-compose.yml (or unit), scripts/generate-specification.py → regenerate SPEC, landing/site/index.html, README/quickstart, .env.example, UFW ports. Agents: see AGENTS.md checklist and run ./scripts/check-stack-docs.py.

Public HTTPS (Caddy + Let’s Encrypt)

The landing container terminates TLS for public hostnames (grey-cloud DNS + WAN 80/443 → this host). Details: quickstart.md → HTTPS reverse proxy.

RustDesk (remote desktop)

Two containers always start with the stack:

Container Role
rustdesk-hbbs ID / rendezvous server (holds the public key clients need)
rustdesk-hbbr Relay when peers cannot connect peer-to-peer

Public key for clients (paste into RustDesk → Network → Key):

# On the stack host (preferred path):
cat /opt/stack/config/rustdesk/id_ed25519.pub
Client field Value
ID server rustdesk.devopshomelab.com (or 192.168.8.123 on LAN)
Key Full contents of id_ed25519.pub (no trailing spaces)
Relay Advertised by hbbs as RUSTDESK_DOMAIN:21117 — usually automatic

Automated client config (churro) — generate install scripts + config string:

./scripts/RustDeskChurry.py              # uses .env RUSTDESK_DOMAIN + id_ed25519.pub
./scripts/RustDeskChurry.py --ensure-key # create key via hbbs if missing
# Output: config/rustdesk/clients/  (install-windows.ps1, install-linux.sh, churro.txt)

Windows (Administrator for install + password):

rustdesk.exe --silent-install
rustdesk.exe --config "<churro>"
rustdesk.exe --password "YourDesiredPassword123"

Linux: rustdesk --config '<churro>' then sudo rustdesk --password '…'

Router / firewall when used from the internet: TCP 21115–21119, UDP 21116.
The HTTPS page at https://rustdesk.devopshomelab.com/ is only a setup reminder — clients do not talk RustDesk over Caddy.

NetBird (mesh VPN + LAN)

Self-hosted control plane (netbird-server + netbird-dashboard) behind Caddy at https://netbird.devopshomelab.com/, plus a host-network routing peer (netbird) that advertises this house LAN.

Overlay IPv4 100.99.0.0/16 (not 10/8 or 192.168/16)
Overlay IPv6 fd99:8:123::/48 (chosen so it does not collide with Tailscale’s fd7a:115c:a1e0::/48)
Advertised LAN LAN_SUBNET (192.168.8.0/24) so remotes use http://192.168.8.123:port
STUN UDP 3478 on the WAN (cannot go through Caddy)
./scripts/render-netbird-config.sh
docker compose up -d netbird-server netbird-dashboard netbird landing
./scripts/netbird-bootstrap.sh   # overlay CIDRs, setup keys, LAN route

Dashboard login is NETBIRD_OWNER_* in .env (render-netbird-config.sh bcrypts the password for Dex). Phone/laptop clients use config/netbird/household.setup.key. Grey-cloud DNS for netbird.$PUBLIC_DOMAIN.

Public service names (sonarr.devopshomelab.com, radarr…, etc.) are Cloudflare DNS-only A records on the WAN IP, kept current by cloudflare-ddns. NetBird does not intercept DNS. Admin (:9090) and Dozzle (:9999) stay LAN-only. BookStack is bookstack.devopshomelab.com (own login). Its MariaDB and the model writer (bookstack-tools) stay on the docker network.

Full project index (agents + humans): specification.html · specification.json
Regenerate both: ./scripts/generate-specification.py


Media stack

1. Prepare

cd arr-stack
cp .env.example .env          # then edit .env (PUID/PGID, TZ, LAN_SUBNET)

Drop your provider's WireGuard config into wireguard/wg0.conf and make the two edits described in wireguard/wg0.conf.example:

  1. Remove IPv6 addresses from Address / DNS lines.
  2. Endpoint must be an IP, not a hostname (dig +short your.endpoint.host).

Create the data tree (already scaffolded here; on a fresh host run):

mkdir -p config data/media/{movies,tv,music,books} data/torrents/{movies,tv,music,books}

The layout uses a single /data share — this lets the Arrs hardlink finished downloads into the media library instantly (no copy, no double disk usage, torrent keeps seeding):

data/
├── media/            <- Jellyfin libraries (+ books for LazyLibrarian)
│   ├── movies/
│   ├── tv/
│   ├── music/
│   └── books/
└── torrents/         <- qBittorrent downloads here
    ├── movies/
    ├── tv/
    ├── music/
    └── books/

2. Start media

docker compose up -d
docker compose ps            # gluetun must show (healthy)
docker logs -f gluetun       # wait for "You are running on the VPN" style line

qBittorrent waits for gluetun to be healthy before starting.

3. Verify the lockdown (do this once)

qBittorrent always uses gluetun's network namespace (network_mode: service:gluetun). It has no separate NIC: every external packet is forced through gluetun's WireGuard tunnel and firewall. That is the killswitch — the container must not reach the public internet over the host's normal ISP/LAN default route. Do not publish BitTorrent ports on the host WAN.

# IP seen from inside qBittorrent — must be your VPN's IP, NOT your home IP:
docker exec qbittorrent curl -s ifconfig.me && echo

# Your real IP for comparison:
curl -s ifconfig.me && echo

# Killswitch test — kill the tunnel, traffic must die with it:
docker exec gluetun sh -c "ip link del tun0" 2>/dev/null
docker exec qbittorrent curl -s --max-time 8 ifconfig.me || echo "NO CONNECTIVITY (good)"
docker restart gluetun       # bring the tunnel back

Belt-and-suspenders extra: in qBittorrent → Tools → Options → Advanced, set Network interface to tun0. Even in a hypothetical gluetun failure, qBittorrent itself would then refuse to use any other interface.

4. Wire it together

qBittorrent (http://host:8080 — default user admin, temporary password is printed in docker logs qbittorrent on first start; change it):

  • Options → Downloads → Default Save Path: /data/torrents
  • Create categories movies → /data/torrents/movies and tv → /data/torrents/tv

Prowlarr (http://host:9696):

  • Add your indexers under Indexers.
  • Settings → Apps: add Sonarr (http://sonarr:8989), Radarr (http://radarr:7878), each with its API key (found in the Arr under Settings → General). Indexers sync automatically from then on.

Sonarr & Radarr — Settings → Download Clients → add qBittorrent:

  • Host: gluetun, Port: 8080, your qBittorrent credentials
  • Category: tv (Sonarr) / movies (Radarr)
  • Settings → Media Management: root folder /data/media/tv or /data/media/movies; enable hardlinks (on by default with this layout)

Bazarr: point it at Sonarr/Radarr (http://sonarr:8989 / http://radarr:7878 + API keys); paths /data/media/tv, /data/media/movies.

Lidarr (http://host:8686) — music, same patterns as Sonarr/Radarr:

  • Settings → Download Clients → qBittorrent: Host gluetun, Port 8080
  • Category: music → qBittorrent save path /data/torrents/music
  • Settings → Media Management: root folder /data/media/music; hardlinks on
  • In Prowlarr → Settings → Apps: add Lidarr (http://lidarr:8686 + API key)

LazyLibrarian (http://host:5299) — books:

  • Dest dir: /data/media/books (ebooks; audiobooks can share or use a subfolder)
  • Downloaders: SABnzbd (http://sabnzbd:8080, category books) and/or qBittorrent (http://gluetun:8080, user tim / pass asdfasdf, category books)
  • Indexers: Newznab NZBgeek (https://api.nzbgeek.info + API key from secrets/.env)

Jellyfin (http://host:8096): add libraries → Movies: /data/media/movies, Shows: /data/media/tv, Music: /data/media/music (optional Books: /data/media/books). Media is mounted read-write (PUID/PGID) so library deletes work; prefer deleting via Radarr/Sonarr when you want the *arr DB updated too.

5. Optional: provider port forwarding

If your VPN provider gives you a forwarded port (AirVPN, ProtonVPN, …), inbound peers can reach you and swarm connectivity improves:

  1. Uncomment FIREWALL_VPN_INPUT_PORTS in the compose file and set the port.
  2. For providers with a NAT-PMP API also uncomment VPN_PORT_FORWARDING and VPN_PORT_FORWARDING_PROVIDER.
  3. Set the same port as qBittorrent's listening port (Options → Connection) and disable UPnP/NAT-PMP inside qBittorrent.

Never publish qBittorrent's BitTorrent port on the host — inbound connections must arrive through the tunnel only.


Models

This host does not run a chat UI or a local model. Open WebUI, Bonsai, SearXNG, and OpenHands are not in compose. Weights left in models/bonsai/ are unused. Agents on other machines use MemPalace, Forgejo, and BookStack.

Layout after AI setup

arr-stack/
├── docker-compose.yml
├── .env / .env.example
├── secrets/.env             # Usenet + Cloudflare (gitignored)
├── ai/                      # Prism llama-server image
│   ├── Dockerfile
│   └── entrypoint.sh
├── landing/                 # Caddyfile + LAN map site + entrypoint
├── models/bonsai/           # unused GGUF weights, if any remain (gitignored)
├── scripts/                 # bootstrap, usenet, DDNS, generate-specification, …
├── config/                  # app configs (sonarr, rustdesk, bookstack, …)
│   └── rustdesk/
│       ├── id_ed25519       # server private key (do not share)
│       └── id_ed25519.pub   # ← give this string to every RustDesk client
├── data/                    # media + torrents
└── wireguard/wg0.conf

Notes

  • All app-to-app traffic uses container DNS names (gluetun, sonarr, bookstack, …) on the internal arr-net bridge; only WebUIs (and RustDesk ports if you open them) are exposed to your LAN / WAN.
  • Update media stack with docker compose pull && docker compose up -d. The same update runs automatically at 04:00 on the 1st of each month (compose-monthly-update.timer). Gluetun is pinned to major version v3 — read its release notes before jumping majors.
  • Optional media extras (commented in compose): Jellyseerr.
  • After architecture changes: ./scripts/generate-specification.py and commit both specification.json and specification.html.