Skip to content
lexcodePublic

About

My ongoing war against cloud subscriptions

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Homelab

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
Loading

Layout

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).

Requirements

  • Docker and Docker Compose v2
  • jq for the read-only stack status command
  • Separate .env files 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.

Validate configuration

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.sh

Use bash scripts/validate.sh --list to show the discovered stack directories.

Check stack status

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 --all

Compose 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 proxy

Media

See 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 -d

Documents

See 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 -d

Monitoring

See 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 -d

Container management

See 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 -d

Terminal

See 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 -d

Analytics

See 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 -d

Homepage

See 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 -d

Notifications (Gotify + iGotify)

See 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 -d

TeslaMate

See 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 -d

Do not add tesla.lexcode.dev to Cloudflare Tunnel; it is intentionally available only through the LAN DNS and Traefik.

N8n

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 -d

Do 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.

AI memory

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 -d

Proxy

See 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 -d

This starts Cloudflare Tunnel and Traefik only. After configuring the optional variables, enable Tailscale Funnel with docker compose --profile tailscale up -d.

DNS (AdGuard Home)

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 -d

Boot with systemd (optional)

Unit 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.service

n8n-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-reload

Already-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.

Secrets and git

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.

About

My ongoing war against cloud subscriptions

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages