add claude.md

2026-01-25 14:33:27 +00:00
parent ec7b34f47a
commit 57590e63b1
1 changed files with 81 additions and 0 deletions
@@ -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