# CLAUDE.md

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

## Overview

This repository manages Docker Compose configurations for the **Agap** self-hosted home server. It is not a software project — it is infrastructure-as-config for several independent services.

## Services

| Directory | Service | Port | Notes |
|-----------|---------|------|-------|
| `immich-app/` | Immich (photo management) | 2283 | Main compose via root `docker-compose.yml` |
| `gitea/` | Gitea (git hosting) + Postgres | 3000, 222 | Standalone compose |
| `openai/` | Open WebUI + Ollama (AI chat) | 3125 | Requires NVIDIA GPU |

## Common Commands

All services use Docker Compose. From each service directory:

```bash
# Start a service
docker compose up -d

# Restart
docker compose restart

# View logs
docker compose logs -f

# Pull latest images
docker compose pull
```

The root `docker-compose.yml` is an alias that includes `immich-app/docker-compose.yml`.

### Immich-specific

Environment variables are in the root `.env` file (referenced by `immich-app/docker-compose.yml` as `../.env`):
- `UPLOAD_LOCATION`, `THUMB_LOCATION`, `ENCODED_VIDEO_LOCATION` — media storage paths
- `DB_DATA_LOCATION` — Postgres data directory

**Restore from backup** (see `immich-app/restore_example.sh`):
```bash
docker compose down -v   # destroys all data
docker compose create
docker start immich_postgres
sleep 10
gunzip --stdout "/home/alvis/dump.sql.gz" | \
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | \
  docker exec -i immich_postgres psql --dbname=postgres --username=postgres
docker compose up -d
```

## GPU / NVIDIA Setup

Before running GPU-dependent services (Open WebUI/Ollama, Immich ML with CUDA):

1. Run `sudo ./nvidia-docker-install.sh` — installs Docker + NVIDIA Container Toolkit
2. Run `./install-cuda.sh` — installs CUDA toolkit (toolkit only, not driver)

## Storage Layout

| Path | Purpose |
|------|---------|
| `/mnt/media/upload` | Immich uploaded originals |
| `/mnt/ssd1/media/thumbs` | Immich thumbnails |
| `/mnt/ssd1/media/encoded-video` | Immich transcoded video |
| `/mnt/ssd1/media/postgres` | Immich Postgres data |
| `/mnt/misc/gitea` | Gitea data |

## Gitea Integration

When changes are made to infrastructure (services, config, setup), update the relevant Gitea wiki pages at `http://localhost:3000/alvis/AgapHost/wiki`.

### Gitea Instance Details
- **URL**: `http://localhost:3000`
- **Repo**: `alvis/AgapHost`
- **Wiki**: `http://localhost:3000/alvis/AgapHost/wiki`
- **API token**: Read from `$GITEA_TOKEN` environment variable — never hardcode it

### Wiki Pages Reference

| Page | Topic |
|------|-------|
| Hello | Overview of Agap — services, stack |
| Home | Index — links to all pages |
| Network | Netplan bridge setup, Caddy reverse proxy |
| Storage | LVM setup and commands |
| Home-Assistant | KVM-based Home Assistant setup |
| 3X-UI | VPN proxy panel |
| Gitea | Git hosting Docker service |

### Read Wiki Pages (API)

```bash
# List all pages
curl -s -H "Authorization: token $GITEA_TOKEN" \
  http://localhost:3000/api/v1/repos/alvis/AgapHost/wiki/pages

# Read a page (content is base64 in content_base64 field)
curl -s -H "Authorization: token $GITEA_TOKEN" \
  http://localhost:3000/api/v1/repos/alvis/AgapHost/wiki/page/Home
```

### Edit Wiki Pages (Git)

The Gitea REST API does not expose wiki write endpoints. Use git directly:

```bash
# Clone the wiki repo
git clone http://alvis:$GITEA_TOKEN@localhost:3000/alvis/AgapHost.wiki.git /tmp/AgapHost.wiki

# Edit files, then commit and push
cd /tmp/AgapHost.wiki
git config user.email "allogn@gmail.com"
git config user.name "alvis"
git add <files>
git commit -m "<message>"
git push http://alvis:$GITEA_TOKEN@localhost:3000/alvis/AgapHost.wiki.git main
```

### Wiki Style Guidelines
- Use minimalistic style: clean headings, code blocks, brief descriptions
- Remove outdated or redundant content when updating
- Create a new page if a topic doesn't exist yet
- Wiki files are Markdown, named `<PageTitle>.md`