From 57590e63b16aea0150f56dad266023ab6d84299f Mon Sep 17 00:00:00 2001
From: poprhythm <james.kolpack@gmail.com>
Date: Sun, 25 Jan 2026 14:33:27 +0000
Subject: [PATCH] add claude.md

---
 CLAUDE.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 81 insertions(+)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..afe5cd2
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+This is a homelab Docker infrastructure repository containing ~30 self-hosted services. Each service has its own directory with a `docker-compose.yaml` (or `.yml`) file. All services use pre-built Docker images - there are no custom Dockerfiles.
+
+## Common Commands
+
+```bash
+# Start a service
+cd <service-name> && docker compose up -d
+
+# Stop a service
+cd <service-name> && docker compose down
+
+# View logs
+docker compose logs -f <service-name>
+
+# Reload nginx proxy config after changing vhost.d or conf.d
+docker exec nginx-proxy nginx -s reload
+```
+
+## Architecture
+
+### Network Architecture
+
+All proxied services connect to `npm-network`, an external Docker network shared with the nginx reverse proxy. Services define this in their compose file:
+
+```yaml
+networks:
+  npm-network:
+    external: true
+```
+
+Some services have additional internal networks (e.g., `mqtt-network` for mosquitto).
+
+### Reverse Proxy (nginx-proxy-acme)
+
+The primary ingress is `nginx-proxy-acme/`, which auto-discovers Docker containers and issues Let's Encrypt certificates. To expose a service:
+
+```yaml
+environment:
+  - VIRTUAL_HOST=myapp.kolpacksoftware.com
+  - VIRTUAL_PORT=8080
+  - LETSENCRYPT_HOST=myapp.kolpacksoftware.com
+```
+
+**Access control:**
+- Private hosts: Include `vhost.d/private` which restricts to 192.168.1.0/24 and Docker networks
+- Public hosts: No vhost.d file (only default security headers apply)
+- To make a host private: `echo 'include /etc/nginx/vhost.d/private;' | sudo tee /srv/nginx-proxy-acme/vhost.d/<hostname>`
+
+**Static backends** (non-Docker services) are configured in `conf.d/static-upstreams.conf` and require adding the domain to the `static-certs` container's environment variables.
+
+### Storage Patterns
+
+- **Bind mounts**: Most services use `/srv/<service-name>/` paths
+- **NFS mounts**: Some services (immich, calibre, backrest, filebrowser-colleen-hd) use NFS volumes pointing to 192.168.1.4 or 192.168.1.192
+
+### Automation
+
+- **watchtower**: Monitors and auto-updates container images every 5 minutes
+- **netdata**: Real-time monitoring with alerting at port 19999
+
+## Key Configuration Locations
+
+| Path | Purpose |
+|------|---------|
+| `/srv/nginx-proxy-acme/vhost.d/` | Per-host nginx config (access control) |
+| `/srv/nginx-proxy-acme/conf.d/` | Global nginx config (WAF rules, static backends) |
+| `<service>/docker-compose.yaml` | Service definition |
+| `<service>/.env` | Service-specific environment (when present) |
+
+## Environment Variables
+
+Common patterns across services:
+- `PUID=1000`, `PGID=1000` for file permissions
+- `TZ=America/New_York` for timezone
+- `VIRTUAL_HOST`, `VIRTUAL_PORT`, `LETSENCRYPT_HOST` for proxy integration