43 lines
2.2 KiB
Markdown
43 lines
2.2 KiB
Markdown
# 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
|