- Python 54.5%
- Shell 21.7%
- HTML 18.8%
- Jinja 2.4%
- CSS 1.6%
- Other 1%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
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. |
||
| admin-panel | ||
| ai | ||
| ansible | ||
| bookstack | ||
| docs | ||
| flint2 | ||
| landing | ||
| llm-prompts | ||
| models/bonsai | ||
| netbird | ||
| profiles | ||
| scripts | ||
| searxng | ||
| secrets | ||
| systemd | ||
| wireguard | ||
| workspace | ||
| .env.example | ||
| .gitignore | ||
| AGENTS.md | ||
| docker-compose.override.yml | ||
| docker-compose.yml | ||
| quickstart.md | ||
| README.md | ||
| specification.html | ||
| specification.json | ||
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:
- Remove IPv6 addresses from
Address/DNSlines. - 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/moviesandtv→/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/tvor/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, Port8080 - 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, categorybooks) and/or qBittorrent (http://gluetun:8080, usertim/ passasdfasdf, categorybooks) - Indexers: Newznab NZBgeek (
https://api.nzbgeek.info+ API key fromsecrets/.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:
- Uncomment
FIREWALL_VPN_INPUT_PORTSin the compose file and set the port. - For providers with a NAT-PMP API also uncomment
VPN_PORT_FORWARDINGandVPN_PORT_FORWARDING_PROVIDER. - 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 internalarr-netbridge; 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 versionv3— read its release notes before jumping majors. - Optional media extras (commented in compose): Jellyseerr.
- After architecture changes:
./scripts/generate-specification.pyand commit bothspecification.jsonandspecification.html.