2c72caf614
- Add CLAUDE.md with Gitea integration, development guidelines, and wiki interaction instructions - Add comprehensive README.md with service overview, quick start, and configuration details - Add service directories: gitea/, openai/, immich-app/, and setup scripts (install-cuda.sh, nvidia-docker-install.sh) - Update docker-compose.yml structure and immich configuration - Include restore example script for Immich database backups This repository now serves as the source of truth for Docker Compose configurations and deployment automation for Agap home server services (Immich, Gitea, Open WebUI). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
128 lines
4.1 KiB
Markdown
128 lines
4.1 KiB
Markdown
# 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`
|