89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 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.
|