# 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