Personal infrastructure-as-code for Docker Compose stacks: media automation, document management, shell history sync, shared coding-agent memory, lightweight host monitoring, container management, analytics, a Netflix IE acquisition feed, workflow automation (n8n), push notifications (Gotify and optional iGotify assistant for iOS), web-change monitoring (changedetection.io), DNS-level ad blocking, and a self-hosted dashboard.
flowchart TB
subgraph ingress["Public ingress"]
cf["Cloudflare Tunnel"]
ts["Tailscale Funnel"]
end
subgraph docker["Docker Compose host"]
traefik["proxy/traefik"]
homepage["homepage/"]
analytics["analytics/"]
documents["documents/"]
subgraph local["Other local stacks"]
direction LR
media["media/"]
monitoring["monitoring/"]
management["management/"]
terminal["terminal/"]
notifications["notifications/"]
dns["dns/"]
aimemory["ai-memory/"]
pulsearr["pulsearr/"]
resonarr["resonarr/"]
teslamate["teslamate/"]
n8n["n8n/"]
n8nsandbox["n8n-sandbox/"]
end
end
subgraph desktop["Desktop (LAN)"]
ollama["Ollama :11434"]
end
cf -- tunnel --> traefik
ts -- funnel --> traefik
traefik -- HTTP --> homepage
traefik -- HTTP --> analytics
documents -- LAN --> ollama
See docs/STRUCTURE.md for a directory tree of the whole repo and each stack (compose files, data/, systemd units).
| Directory | Purpose |
|---|---|
media/ |
Servarr stack (qBittorrent over WireGuard PIA, Sonarr, Radarr, Lidarr, Bazarr, Seerr, Prowlarr, FlareSolverr, SuggestArr, deunhealth) — see media/README.md. |
documents/ |
AI-powered document management (paperless-ngx + paperless-gpt with Ollama OCR and tagging) — see documents/README.md. |
monitoring/ |
Beszel hub plus co-located agent — see monitoring/README.md. |
management/ |
Dockge Compose stack manager with click-to-update workflows — see management/README.md. |
terminal/ |
Atuin self-hosted shell history sync server — see terminal/README.md. |
analytics/ |
Your Spotify self-hosted Spotify listening statistics — see analytics/README.md. |
homepage/ |
Homepage self-hosted dashboard with service widgets and Docker integration — see homepage/README.md. |
notifications/ |
Gotify plus optional iGotify assistant for iOS push, and changedetection.io for web-page change monitoring — see notifications/README.md. |
pulsearr/ |
Pulsearr API, worker, PostgreSQL, and backups — see pulsearr/README.md. |
teslamate/ |
LAN-only Tesla vehicle telemetry, Grafana dashboards, PostgreSQL, Mosquitto, and backups — see teslamate/README.md. |
n8n/ |
LAN-only n8n workflow automation with SQLite storage — see n8n/README.md. |
n8n-sandbox/ |
Code-execution sandbox for n8n Assistant: sandbox-api, privileged Docker-in-Docker runner, and bundled SearXNG (n8n-searxng.lexcode.dev; sandbox API at n8n-sandbox-api.lexcode.dev) — see n8n-sandbox/README.md. |
ai-memory/ |
ai-memory server for shared coding-agent context — see ai-memory/README.md. |
proxy/ |
Cloudflare Tunnel + Nginx Proxy Manager + optional Tailscale Funnel for video/high-bandwidth services — see proxy/README.md. |
dns/ |
LAN DNS / filtering (AdGuard Home) — primary on Raspberry Pi 5, secondary on Unraid; DHCP DNS via UniFi Dream Machine Pro — see dns/README.md. |
resonarr/ |
Resonarr API and persistent download worker, published from GHCR — see resonarr/README.md. |
systemd/ |
Optional systemd units to start each stack at boot — see Boot with systemd below. |
Each stack owns its compose.yml, .env.example, and runtime data under ./data/ (not committed).
- Docker and Docker Compose v2
jqfor the read-only stack status command- Separate
.envfiles per stack (copy from each.env.example)
Networks are isolated by design (for example media on 172.39.0.0/24, monitoring on 172.39.1.0/24, analytics on 172.39.2.0/24, AdGuard Home on 172.39.5.0/24, and management on 172.39.8.0/24). Adjust subnets in .env if they clash with your LAN or other projects.
Run the repository-wide validation gate to validate every stack from its committed .env.example without starting containers or printing rendered configuration. It reports one pass or fail per stack and exits non-zero when any Compose configuration is invalid.
bash scripts/validate.shUse bash scripts/validate.sh --list to show the discovered stack directories.
Use the read-only status command to compare the services selected by the
rendered Compose configuration with the containers Docker reports. It exits
non-zero when an expected service is missing, exited, restarting, or unhealthy.
Services without a healthcheck are reported as no-healthcheck.
bash scripts/status.sh analytics
bash scripts/status.sh --allCompose profiles are opt-in here just as they are during startup. Pass each profile explicitly when its services should be expected; otherwise optional services are excluded and cannot cause false missing-service failures.
bash scripts/status.sh --profile tailscale proxySee media/README.md for environment variables, ports, qBittorrent/VPN notes, an example /data directory tree (libraries and download folders), and optional persistent CIFS mounts when movies and TV live on a remote NAS under /data.
Quick start:
cd media
cp .env.example .env # edit with your secrets and LAN/VPN settings
docker compose up -dSee documents/README.md for the full setup including Ollama LAN configuration, how to generate the paperless-ngx API token, model roles, and the tag-based processing workflow.
Ollama runs on a separate, more powerful machine on the LAN. paperless-ngx and paperless-gpt run on the server (e.g. Raspberry Pi).
Quick start:
cd documents
cp .env.example .env # set PAPERLESS_SECRET_KEY, PAPERLESS_API_TOKEN, OLLAMA_HOST
docker compose up -d broker paperless-ngx
docker compose exec paperless-ngx python3 manage.py createsuperuser
docker compose exec paperless-ngx python3 manage.py drf_create_token <username>
# paste token into .env, then:
docker compose up -dSee monitoring/README.md for Beszel hub and agent setup, environment variables, extra filesystem mounts, remote agents, and Dozzle container actions.
Quick start:
cd monitoring
cp .env.example .env # set BESZEL_URL; add BESZEL_AGENT_KEY / TOKEN from the UI after first visit
docker compose up -dSee management/README.md for Dockge setup, stack discovery, update guidance, reverse-proxy configuration, and Docker socket security considerations.
Quick start:
cd management
cp .env.example .env # set HOMELAB_ROOT to this repository's absolute host path
mkdir -p data/dockge
docker compose up -dSee terminal/README.md for Atuin sync server setup, Postgres notes, and how to point shell clients at this server.
Quick start:
cd terminal
cp .env.example .env # set ATUIN_DB_NAME, ATUIN_DB_USERNAME, ATUIN_DB_PASSWORD
docker compose up -dSee analytics/README.md for Spotify developer app setup, Cloudflare Tunnel configuration, DNS notes, and ARM/Raspberry Pi specifics.
Quick start:
cd analytics
cp .env.example .env # set YOUR_SPOTIFY_API_ENDPOINT, YOUR_SPOTIFY_CLIENT_ENDPOINT, SPOTIFY_PUBLIC, SPOTIFY_SECRET
docker compose up -dSee homepage/README.md for config file layout, Docker integration via dockerproxy, background image setup, and service widget variables.
Quick start:
cd homepage
cp .env.example .env # set HOMEPAGE_ALLOWED_HOSTS and service URLs/keys
docker compose up -dSee notifications/README.md for ports, persistent data under ./data/gotify, ./data/igotify, and ./data/changedetection, iOS assistant env vars, clients, and *arr Connect.
Quick start:
cd notifications
cp .env.example .env # set GOTIFY_DEFAULTUSER_PASS; for Local iGotify set GOTIFY_* / SECNTFY_* per README
docker compose up -dSee teslamate/README.md for the LAN-only Traefik route, Tesla API token setup, Grafana dashboards, and database backup guidance.
Quick start:
cd teslamate
cp .env.example .env # set generated encryption/database/Grafana secrets
docker compose up -dDo not add tesla.lexcode.dev to Cloudflare Tunnel; it is intentionally available only through the LAN DNS and Traefik.
See n8n/README.md for the LAN-only Traefik route, SQLite data layout, webhook URL, and the N8N_ENCRYPTION_KEY used to encrypt workflow credentials. n8n Assistant's sandbox is a separate stack — see n8n-sandbox/README.md.
Quick start:
cd n8n
cp .env.example .env # set N8N_ENCRYPTION_KEY (openssl rand -base64 48); keep it permanent
mkdir -p data/n8n data/files && sudo chown -R 1000:1000 data
docker compose up -dDo not add n8n.lexcode.dev to Cloudflare Tunnel; it is intentionally available only through the LAN DNS and Traefik. The Assistant sandbox in n8n-sandbox/ has two more LAN-only names: n8n-searxng.lexcode.dev (search UI + JSON API) and n8n-sandbox-api.lexcode.dev (the X-Api-Key protected control plane). Do not add those to the Tunnel either.
See ai-memory/README.md for Raspberry Pi setup, bearer-token configuration, native-data migration, and desktop client integration.
Quick start:
cd ai-memory
cp .env.example .env # set AI_MEMORY_AUTH_TOKEN and AI_MEMORY_ALLOWED_HOSTS
mkdir -p data
docker compose up -dSee proxy/README.md for Cloudflare Tunnel setup, adding public hostnames, and the optional Tailscale Funnel sidecar for publicly exposing a single service (for example Jellyfin) outside the Cloudflare CDN — Cloudflare’s terms prohibit proxying video.
Quick start:
cd proxy
cp .env.example .env # set CLOUDFLARED_TOKEN; TS_AUTHKEY only if using Tailscale Funnel
docker compose up -dThis starts Cloudflare Tunnel and Traefik only. After configuring
the optional variables, enable Tailscale Funnel
with docker compose --profile tailscale up -d.
See dns/README.md for bridge networking, port defaults vs Traefik, systemd-resolved, and UniFi DMP DHCP DNS (primary = Pi dns/ stack, secondary = Unraid AdGuard).
Quick start:
cd dns
cp .env.example .env # adjust ADGUARD_DNS_PORT / ADGUARD_HTTP_PORT if needed
docker compose up -dUnit files live in systemd/. They run each stack with docker compose up -d from the matching directory as oneshot services and are suitable for enabling stacks at boot on a single host. Successful activation means detached Compose startup completed; container health and restart behavior remain Docker/Compose responsibilities.
An active unit is therefore an orchestration result, not a health assertion.
Use bash scripts/status.sh <stack> (or --all) as the repository health
authority. The units intentionally have no ExecStartPost health hook because
application warm-up times vary, and a fixed delay or immediate health check
would turn normal startup into an unreliable unit failure.
The default proxy.service startup excludes the optional Tailscale Funnel
profile.
Install (paths assume this repo at /home/lexcode/git/homelab; edit the unit files if your clone lives elsewhere):
sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now media.service documents.service monitoring.service management.service analytics.service terminal.service homepage.service notifications.service pulsearr.service teslamate.service n8n.service dns.service ai-memory.service resonarr.service proxy.servicen8n-sandbox.service is optional: enable it only when n8n Assistant's sandbox is in use. It is ordered after n8n.service, because n8n owns n8n-sandbox-network.
After pulling systemd unit updates: The files in this repository are source
copies; systemd uses the installed copies under /etc/systemd/system/. Reinstall
them and reload systemd after pulling changes:
git pull
sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reloadAlready-enabled units do not need to be enabled again. Updated behavior takes
effect the next time each unit starts, such as after a reboot. To apply changes
immediately, restart the affected units during a maintenance window; restarting
one of these units runs docker compose down before starting it again.
Why proxy.service lists other stacks in After=: The proxy stack includes Nginx Proxy Manager joined to external Docker networks (servarrnetwork, documentsnetwork, etc.). Those networks are created when each respective docker compose stack starts. If proxy.service runs first, Compose fails with “network … not found.” The producer units use oneshot activation, so their After= ordering holds proxy startup until each docker compose up -d command has completed and created its network.
pulsearr.service similarly starts after media.service and
notifications.service, whose external networks it imports. It has no public
proxy or Tailscale Funnel route; access is LAN-only plus the private tailnet.
teslamate.service creates teslamatenetwork, so proxy.service starts after
it. TeslaMate is routed at tesla.lexcode.dev only on the LAN and deliberately
has no Cloudflare Tunnel hostname. n8n.service creates n8nnetwork and
n8n-sandbox-network the same way; n8n is LAN-only at n8n.lexcode.dev, and the
n8n Assistant sandbox is LAN-only at n8n-searxng.lexcode.dev (search UI + JSON API)
and n8n-sandbox-api.lexcode.dev (X-Api-Key protected control plane).
n8n-sandbox.service then joins n8n-sandbox-network as external, so it is the one
unit ordered after another stack's unit (After=n8n.service) rather than before
proxy.service.
Cross-stack ordering is encoded in proxy.service, pulsearr.service, and
n8n-sandbox.service; other units only need After=docker.service and
Requires=docker.service.
Requires= vs After=: Other stacks do not use Requires= on each other so one failing service does not block Docker or unrelated stacks. Only proxy needs strict ordering relative to the stacks whose networks it imports.
Do not commit real .env files or credentials. Never put tunnel tokens, API keys, or passwords in compose.yml comments. Runtime database and agent state under media/data, documents/data, monitoring/data, management/data, terminal/data, analytics/data, notifications/data, pulsearr/data, teslamate/data, n8n/data, n8n-sandbox/data, dns/data, ai-memory/data, and similar paths are intended to stay local.
.cursor/ is listed in .gitignore so editor-specific rules stay on your machine and are not shared via the repo; remove that line if you intentionally want to version Cursor project config.