Files

T

Frank c353725ea5 docs: cross-link the vllmScripts project (model endpoints + git host)

- README: fix broken 'Also See' placeholder URL -> live Gitea LAN URL
- index.md: expand vllmScripts See Also with the endpoints it serves
- OpenWebUI.md: :7770 backend is the llama.cpp PP head (split to the
  3090), managed by vllmScripts; note the FLM NPU :52625 alternative;
  fix the broken [[llama.cpp Server]] wikilink
- Gitea.md: hosted repositories table (both projects)
- Dankclaw Stack.md: host-level LLM endpoints in the service inventory
- AGENTS.md: runtime note — LLM endpoints live in vllmScripts, not here

Pre-existing failures (untracked ComfyUI WIP): tests 6, 8, 9, 10.
Docs seams green: ok 19 (compose service docs), ok 20 (index links).

2026-08-16 23:19:54 -07:00

3.7 KiB

Raw Blame History

AGENTS.md — serverAppConfigs Agent Rules

Overview

This repository tracks the Podman container stacks for two homelab servers. Dankserver runs the media/library stack (RomM, Copyparty, Calibre-Web). Dankclaw runs the AI/search/development stack (SearXNG via Gluetun, ComfyUI, OpenWebUI, Hermes, Gitea, Grafana, Prometheus) plus the observability stack. Caddy reverse-proxies everything on both hosts.

Git Workflow

All config edits flow through git. Do not edit files on the remote machine directly.

Protocol

Source the config from the target machine — fetch the live compose/Caddyfile from the server where it runs
Place it in this repo — commit the fetched version (redact secrets into .env)
Edit here — make all changes locally in the working tree
Run the tests — ./tests/run.sh must pass
Commit and push — push to origin (Gitea on dankclaw)
Pull on the target — git pull on the remote machine
Restart the stack — use scripts/deploy.sh to pull + restart + healthcheck

Deployment

Use scripts/deploy.sh to deploy committed changes to a target.

./scripts/deploy.sh dankclaw        # Dankclaw stack
./scripts/deploy.sh dankserver      # Dankserver stack
./scripts/deploy.sh dankclaw --dry-run   # preview without changes

Testing

Tests are mandatory before commit. bats must be installed on the development machine.

./tests/run.sh

Test seams: compose validity, env consistency (no leaked secrets), Caddyfile validity, docs completeness, script syntax, deployment flow. See [docs/Architecture/Testing Policy.md](docs/Architecture/Testing Policy.md).

Secret Rules

Never commit real secrets. The live Gitea database password is test-enforced as a leak check.
.env files are git-ignored; commit only .env.example with placeholders.
Do not document passwords in this repo, including sudo passwords. SSH keys are the auth mechanism.

Runtime & Troubleshooting

The LLM endpoints are bare-metal systemd services managed by the sibling vllmScripts repository (../vllmScripts), not by this repo: llama.cpp PP head :7770 and FastFlowLM NPU :52625 on Dankclaw, RPC worker :50052 on Dankserver. Do not edit their scripts here.
Model load on the LLM servers takes 3–8 minutes; 503 Loading model is normal during load. Do not kill the process.
sudo on both boxes needs a tty. Do not use echo password | sudo -S in committed scripts; run sudo interactively.
Never run pkill -f with a pattern that appears in your own command line. Use pkill -x <exact-name>.
ComfyUI on Dankclaw runs CPU-only (--cpu); ROCm wheels do not support gfx1151. Do not use CUDA images.
SearXNG outbound traffic must stay on the Gluetun tunnel; do not move its ports off the gluetun service.

Why

Direct edits on the remote drift from version control. Future agents will not know what changed. Git is the single source of truth.

Summary

Context	Action
Editing a compose/Caddyfile	Work through git — fetch, commit, edit, test, push, pull, restart. Never edit on the remote directly.
Config exists only on remote	Pull it into the repo first — commit the fetched version (redacted) before making changes.
Unstaged local changes	Commit or discard — check `git status` before starting work. Ask the user if unsure.
Deploying a committed change	Run `scripts/deploy.sh <target>` — it pulls on the target, restarts the stack, and checks health.
Tests exist	Run them — verify tests pass after every change. Do not commit failing tests.
Real secrets	Never commit — use host `.env` files; `.env.example` holds placeholders only.

3.7 KiB Raw Blame History Unescape Escape