alvis/AgapHost
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

Document Agap infrastructure and services

Browse Source 
- 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>
This commit is contained in:
Alvis
2026-02-21 10:24:33 +00:00
parent 348b3009d9
commit 2c72caf614
12 changed files with 413 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
CLAUDE.md Normal file
View File

@@ -0,0 +1,127 @@
# 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`