add: add CLAUDE.md for homelab guidance and add compose files for karakeep, nginx-proxy-manager, and pihole services

CLAUDE.md

@@ -0,0 +1,88 @@
+# 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.