homelab/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Repo Is

A Docker Compose-based homelab infrastructure project. All services are deployed via Portainer — there are no build, test, or lint commands. Configuration files are the primary artifact.

Deployment Model

• Services live in services/<name>/docker-compose.yml
• Each service is deployed as a Portainer stack by copy-pasting (or uploading) the compose file into the Portainer UI
• Portainer itself is managed outside of stacks (deployed manually, not via a stack)
• Secrets and environment variables are injected via Portainer's env var management — never hardcoded (except for existing Traefik credentials, which are a known issue)
• Services that need secrets have a services/<name>/.env.example documenting the required variables

Network Architecture

All services share an external Docker bridge network named proxy. Traefik is the single ingress point listening on :80/:443, routing to subdomains under *.home.jens.pub via Let's Encrypt wildcard certs (DNS-01 challenge via Namecheap API).

Traefik (proxy network)
  ├── traefik.home.jens.pub  → Traefik dashboard
  ├── adguard.home.jens.pub  → AdGuard Home
  ├── portainer.home.jens.pub → Portainer
  ├── vault.home.jens.pub    → Vaultwarden
  ├── beszel.home.jens.pub   → Beszel metrics hub
  └── logs.home.jens.pub     → Dozzle

Beszel agent runs on host network (for direct metrics access) and communicates with the hub via a Unix socket at /var/run/beszel-agent.sock.

Documentation

docs/ contains a markdown file per service plus docs/index.md as the master overview. Always update docs/ when adding or changing a service. The index lists all services, the network topology, and security notes.

Adding a New Service

1. Create services/<name>/docker-compose.yml — attach to the proxy network, add Traefik labels for routing/TLS
2. If secrets are needed, add services/<name>/.env.example
3. Add a docs/<name>.md with purpose, image, ports, volumes, and config details
4. Update docs/index.md to include the new service