Agap Installation

Steps to set up a fresh Agap server from scratch.

1. Storage

Set up LVM volumes and mount points before anything else. See Storage for the full layout and LVM commands.

Required mount points:

Mount	Purpose
`/mnt/ssd`	DB data, thumbnails, encoded video
`/mnt/backups`	All backups
`/mnt/misc`	Gitea data
`/mnt/media`	Immich photo originals

2. Network

See Network for full setup: Netplan bridge, Caddy reverse proxy, Pi-hole DNS, and port forwarding requirements.

Hairpin NAT workaround

The router does not support hairpin NAT. Add local /etc/hosts entries for self-hosted domains so the host can reach them without going through the public IP:

echo "127.0.0.1 docs.alogins.net" | sudo tee -a /etc/hosts
echo "127.0.0.1 vw.alogins.net"   | sudo tee -a /etc/hosts

3. GPU & Docker

sudo ./nvidia-docker-install.sh   # Docker + NVIDIA Container Toolkit
./install-cuda.sh                  # CUDA toolkit (no driver)

4. Zabbix Agent (host)

Install agent and plugins:

# Add Zabbix repo
wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest_7.4+ubuntu24.04_all.deb
sudo dpkg -i zabbix-release_latest_7.4+ubuntu24.04_all.deb
sudo apt update

# Install agent and GPU plugin
sudo apt install zabbix-agent2 zabbix-agent2-plugin-nvidia-gpu

Configure /etc/zabbix/zabbix_agent2.conf:

Server=127.0.0.1
ServerActive=127.0.0.1:10051
Hostname=AgapHost
PluginSocket=/run/zabbix/agent.plugin.sock
ControlSocket=/run/zabbix/agent.sock
Include=/etc/zabbix/zabbix_agent2.d/plugins.d/*.conf
Include=/etc/zabbix/zabbix_agent2.d/*.conf

sudo systemctl enable --now zabbix-agent2

In Zabbix UI, link these templates to the AgapHost host:

Linux by Zabbix agent active
Nvidia by Zabbix agent 2 active

5. Custom Zabbix UserParameters

Add backup monitoring to /etc/zabbix/zabbix_agent2.d/gitea_backup.conf:

# Gitea backup
UserParameter=gitea.backup.status,grep -c "Finish dumping" /mnt/backups/gitea/backup.log 2>/dev/null | grep -qx 1 && echo 1 || echo 0
UserParameter=gitea.backup.age,f=$(ls -t /mnt/backups/gitea/gitea-dump-*.zip 2>/dev/null | head -1); [ -n "$f" ] && echo $(( $(date +%s) - $(stat -c %Y "$f") )) || echo -1

# DBS backup
UserParameter=dbs.backup.age,f=/mnt/backups/dbs/.last_sync; [ -f "$f" ] && echo $(( $(date +%s) - $(stat -c %Y "$f") )) || echo -1

# Immich backup
UserParameter=immich.backup.age,f=/mnt/backups/media/.last_sync; [ -f "$f" ] && echo $(( $(date +%s) - $(stat -c %Y "$f") )) || echo -1

6. Root Cron Jobs

sudo crontab -e

Add:

0 3 * * * /home/alvis/agap_git/gitea/backup.sh >> /mnt/backups/gitea/cron.log 2>&1
30 2 * * * /home/alvis/agap_git/immich-app/backup.sh >> /mnt/backups/media/cron.log 2>&1
30 3 * * * rsync -a --delete /mnt/ssd/dbs/ /mnt/backups/dbs/ >> /mnt/backups/dbs/cron.log 2>&1 && touch /mnt/backups/dbs/.last_sync

7. Claude Code

Install Claude Code, then configure:

~/.claude/settings.json — env vars and preferences:

{
  "env": {
    "PATH": "/home/alvis/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "BW_PASSWORD": "<vaultwarden-master-password>",
    "NODE_TLS_REJECT_UNAUTHORIZED": "0",
    "HTTP_PROXY": "http://127.0.0.1:56928",
    "HTTPS_PROXY": "http://127.0.0.1:56928",
    "ALL_PROXY": "http://127.0.0.1:56928",
    "NO_PROXY": "localhost,127.0.0.1,172.17.0.0/16"
  },
  "effortLevel": "low"
}

All API tokens (Gitea, Zabbix, Telegram, HA) are stored in Vaultwarden AI collection and fetched on demand — see Vaultwarden.

~/.claude/CLAUDE.md — global instructions (Gitea wiki integration, Zabbix API, HA API, Vaultwarden token fetch). Copy from existing Agap setup.

~/agap_git/CLAUDE.md — project-level instructions (services, storage paths, common commands). Already in the repo.

8. Services

Start all Docker services:

cd ~/agap_git
docker compose up -d                        # Immich
cd gitea && docker compose up -d            # Gitea
cd ../openai && docker compose up -d        # Open WebUI + Ollama
cd ../zabbix && docker compose up -d        # Zabbix
cd ../seafile && docker compose up -d       # Seafile + SeaDoc + OnlyOffice
cd ../vaultwarden && docker compose up -d   # Vaultwarden
cd ~/adolf && docker compose up -d          # Adolf AI assistant

Seafile post-start

Restore .env from Vaultwarden (credentials: SEAFILE_MYSQL_DB_PASSWORD, SEAFILE_REDIS_PASSWORD, etc.).

WebDAV mount (add to /etc/hosts first — see hairpin NAT note above):

sudo mkdir -p /mnt/seafile
sudo mount -t davfs https://docs.alogins.net/seafdav/ /mnt/seafile -o uid=1000,gid=1000

Root cron jobs (add to existing)

sudo crontab -e

Add:

0 2 */3 * * /home/alvis/agap_git/vaultwarden/backup.sh >> /var/log/vaultwarden-backup.log 2>&1
0 2 */3 * * /home/alvis/agap_git/seafile/backup.sh >> /var/log/seafile-backup.log 2>&1

Store Zabbix token for backup scripts:

# Get token from Vaultwarden and save for root
BW=/home/alvis/bin/bw
SESSION=$($BW unlock "$BW_PASSWORD" --raw 2>/dev/null)
$BW get password "ZABBIX_TOKEN" --session "$SESSION" 2>/dev/null | sudo tee /root/.zabbix_token > /dev/null
sudo chmod 600 /root/.zabbix_token