homelab-docker-compose-prod/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is a personal homelab running 21 Docker Compose stacks on a single Linux host. Each service lives in its own subdirectory with an independent compose.yaml (or docker-compose.yaml). There is no CI/CD, no Makefile, and no shared orchestration layer — everything is managed manually.

Common Commands

All commands must be run from within the relevant service directory:

# Start a stack (detached)
docker compose up -d

# Stop a stack
docker compose down

# Restart a single service within a stack
docker compose restart <service>

# Pull latest images and recreate
docker compose pull && docker compose up -d

# View logs
docker compose logs -f [service]

Architecture

Directory Layout

Each service is self-contained in its own directory. The pattern is:

• compose.yaml or docker-compose.yaml — service definition
• .env — secrets/overrides (only Authentik and SparkFitness use this; most others embed values inline)
• compose.env — Komodo-specific env file loaded via --env-file

Storage

Two storage tiers are used across all stacks:

• /docker/<service>/ — Local persistent data (databases, config, app state)
• /nfs/media/ — NFS-mounted shared library for large binary data:
  • Movies/, Shows/, Musics/, Podcasts/ — consumed by Jellyfin, ARR stack, Navidrome
  • photo/library/ — Immich photo library
  • Books/Kavita Library/ — Kavita ebook collection
  • /nfs/torrent/ — qBittorrent download target (Radarr/Sonarr pick up from here)

Authentication

Authentik (authentik/) is the central SSO/OIDC provider. Currently integrated with:

• Paperless-NGX — OIDC via PAPERLESS_SOCIALACCOUNT_PROVIDERS
• Komodo — OIDC via KOMODO_OIDC_* vars

When adding OIDC to a new service, the Authentik provider/application must be configured separately in the Authentik admin UI, and the client ID/secret wired into the service's compose file.

Key Service Relationships

• ARR stack (Sonarr → qBittorrent → Radarr/Bazarr → /nfs/torrent) feeds content into Jellyfin
• Komodo manages container lifecycle across the host; the periphery agent mounts /var/run/docker.sock
• Immich uses pgvecto-rs (not stock PostgreSQL) — image version pinning matters for DB compatibility
• Paperless-NGX depends on Gotenberg (PDF rendering) and Tika (content extraction) sidecar containers

Ports

Services are exposed on localhost:80xx ports (see individual compose files). A reverse proxy (not in this repo) sits in front and handles TLS/domain routing.

Conventions

Commit Messages

Follow the format used throughout git history:

add: <description>      # new service or feature
fix: <description>      # corrections
remove: <description>   # deletions

Environment Variables

• TZ: Asia/Ho_Chi_Minh is set on all containers
• LinuxServer.io images use PUID/PGID for file permission mapping
• All credentials go inline in compose files — never use .env files for new stacks

Image Pinning

Most services pin to a specific tag or latest. When upgrading images that have associated databases (Immich, Paperless-NGX, Gitea), check upstream migration notes before pulling.