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

```bash
# 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.