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

docs: refresh CLAUDE.md and README, add swap exhaustion analysis

Browse Source 
CLAUDE.md and README.md catch up with where services actually run -- notably
that Zabbix and Home Assistant live on lizacer, not Agap -- and with the
current service list.

SWAP_EXHAUSTION_ANALYSIS_20260726.md records the 2026-07-26 swap exhaustion
investigation.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
alvis
2026-07-30 04:43:06 +00:00
parent d37801806d
commit e5438ace79
3 changed files with 265 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files

120
README.md
View File

@@ -1,60 +1,108 @@
# Agap Home Server
# agap_git — Agap Server Configuration
Docker Compose configurations for the Agap self-hosted home server infrastructure.
`agap_git` is the **configuration repo** for Agap, the self-hosted home server. It holds:
## Services
- `docker-compose` files for services running on Agap
- host-level config: Caddy (`Caddyfile`), backup/install scripts, `.env` files
- **Immich** (`immich-app/`) — Photo management and backup (port 2283)
- **Gitea** (`gitea/`) — Self-hosted Git server with web UI (port 3000, SSH 222)
- **Open WebUI** (`openai/`) — AI chat interface with Ollama, GPU-accelerated (port 3125)
**Convention:** a Dockerfile, application source, or anything you'd `build:` from an
image belongs in the *service's own Gitea repo* — not here. `agap_git` keeps the
compose file that runs the resulting image, plus whatever config the compose needs.
Third-party services (pulling a public image) live here in full, since there's no
source to split out.
## Self-developed services
Services with source written in-house are meant to be dual: source lives in their
own Gitea repo, and the compose that runs them is described here.
| Service | Own repo | Compose in agap_git |
|---|---|---|
| matrixbot (Matrix bot, Adolf channel adapter) | [`alvis/matrixbot`](http://localhost:3000/alvis/matrixbot) | **not present** — runs from `~/matrixbot/docker-compose.yml` in its own repo |
| moodtracker | [`alvis/moodtracker`](http://localhost:3000/alvis/moodtracker) | **not present** — runs from `~/moodtracker/docker-compose.yml` |
| marketplace-mcp | [`alvis/marketplace-mcp`](http://localhost:3000/alvis/marketplace-mcp) | **not present** — runs from `~/marketplace-mcp/docker-compose.yml` |
| oO | [`alvis/oO`](http://localhost:3000/alvis/oO) | **not present** — runs from `oO/infra/docker/docker-compose.yml`; oO was already a fully separate project before this convention existed |
| mood (mood-archive) | none yet | fully vendored here (`mood/`, source + compose) — Kanboard **#209** will extract it to its own repo |
**Known gap:** the convention calls for compose to be described in `agap_git` *and*
source to live in its own repo. For matrixbot / moodtracker / marketplace-mcp / oO,
extraction (kb#78) moved the compose file along with the source into each new repo,
so `agap_git` currently has zero footprint for these four — no compose, no config.
Not fixed in this doc-only pass; flagged for a follow-up decision: either copy each
compose back into `agap_git`, or formally amend the convention to let self-developed
services keep compose in their own repo.
## Third-party services (compose lives here in full)
| Directory | Service | Port |
|---|---|---|
| `immich-app/` | Immich — photo management | 2283 |
| `gitea/` | Gitea — git hosting + Postgres | 3000, 222 |
| `openai/` | Adolf (OpenClaw gateway) + LiteLLM + Hindsight + Qdrant + Langfuse + Whisper/TTS stack | see `openai/docker-compose.yml` (adolf-llm on 8010) |
| `adolf/` | Adolf config only (`openclaw.json`, design docs) — the `adolf` compose service lives in `openai/docker-compose.yml`; the OpenClaw fork source is a separate tree at `~/adolf` | — |
| `vaultwarden/` | Password manager | 8041 |
| `kanboard/` | Kanban board, task orchestration for the `claude` bot | 4800 |
| `seafile/` | File sync, OnlyOffice, WebDAV (multiple compose files) | 8078 (server), 8077 (Caddy) |
| `matrix/` | Synapse homeserver + coturn + LiveKit (not the `matrixbot` bot — see above) | — |
| `overleaf/` | LaTeX editor (ShareLaTeX/Overleaf CE) | — |
| `linkwarden/` | Bookmark manager | 3012 |
| `vikunja/` | Task manager | 3457 |
| `radicale/` | CalDAV/CardDAV server | 5232 |
| `ntfy/` | Push notifications | 8840 |
| `syncthing/` | File sync | 8384 |
| `qbittorrent/` | Torrent client | 8085 |
| `searxng/` | Metasearch engine | 11437 |
| `ollama/` | Local LLM runtime | 11436 |
| `openwebui/` | AI chat UI | 3125 |
| `anki/` | Anki sync server | 8180 |
| `family/` | MediaWiki (family wiki) | 8099 |
| `freshrss/` | RSS reader | 8091 |
| `iperf3/` | Network throughput testing | 8095 |
| `otter/` | OtterWiki | 8083 |
| `agap-mcp/` | MCP tool server for Claude (Node/Express) — vendored source, no separate repo | 3100 |
| `personal-sensing/` | SQLite store + schema for HA/Health Connect data (no compose; library used by an ETL, see kb#207) | — |
## Removed / moved out
- `windows/` — removed (kb#82): no VM, no container, dead config.
- `zabbix/`, `haos/` — moved to [`alvis/lizacer`](http://localhost:3000/alvis/lizacer) (kb#81). Zabbix runs on the **lizacer** server (`192.168.1.4:81`), not Agap.
## Top-level files
- `Caddyfile` — reverse proxy / TLS routing for all services
- `nvidia-docker-install.sh`, `install-cuda.sh` — GPU host setup
- `users-backup.sh` — host user backup
## Quick Start
### Start Immich (main service)
Each service is standalone; from its directory:
```bash
docker compose up -d
docker compose restart
docker compose logs -f
docker compose pull
```
### Start Gitea (from gitea/ directory)
```bash
cd gitea
docker compose up -d
```
### Start Open WebUI (from openai/ directory)
```bash
cd openai
docker compose up -d
```
## Configuration
Environment variables are in the root `.env` file for Immich:
- `UPLOAD_LOCATION` — where photo originals are stored
- `THUMB_LOCATION` — thumbnail cache directory
- `ENCODED_VIDEO_LOCATION` — transcoded video cache
- `DB_DATA_LOCATION` — Postgres database directory
- `DB_PASSWORD` — Postgres password
The root `docker-compose.yml` is an alias that includes `immich-app/docker-compose.yml`.
## Storage
Media is stored on:
- `/mnt/media/upload` — Immich originals
- `/mnt/ssd1/media/` — Immich thumbnails, encoded video, and Postgres database
- `/mnt/ssd1/media/` — Immich thumbnails, encoded video, Postgres
- `/mnt/misc/gitea` — Gitea repositories and data
## GPU Support
For GPU acceleration (Open WebUI/Ollama, Immich ML):
For GPU acceleration (Ollama/Open WebUI, Immich ML):
1. Install NVIDIA Docker runtime: `sudo ./nvidia-docker-install.sh`
2. Install CUDA toolkit: `./install-cuda.sh`
1. `sudo ./nvidia-docker-install.sh` — Docker + NVIDIA Container Toolkit
2. `./install-cuda.sh` — CUDA toolkit
## Documentation
See [CLAUDE.md](./CLAUDE.md) for detailed developer instructions and Gitea wiki integration guidelines.
See [CLAUDE.md](./CLAUDE.md) for developer instructions, credentials handling, and
Gitea/Zabbix/Home Assistant API integration details.
See the [Gitea wiki](http://localhost:3000/alvis/AgapHost/wiki) for infrastructure documentation (storage, network, services setup).
See the [Gitea wiki](http://localhost:3000/alvis/AgapHost/wiki) for infrastructure
documentation (storage, network, per-service setup).