# 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