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

# 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:

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:

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

2.7 KiB Raw Blame History