feat: initialize serverAppConfigs with podman stacks for Dankserver and Dankclaw

- Dankserver stack: RomM, Copyparty, Calibre-Web, node-exporter
- Dankclaw stack: Gluetun VPN (SearXNG tunnel), SearXNG+Valkey, ComfyUI
  (CPU backend), OpenWebUI, Hermes, Gitea+Postgres (migrated), Caddy
  reverse proxy, Grafana+Prometheus+Loki+Alloy observability
- Caddyfiles with .local hostname convention and basicauth homepage
- bind-mount storage policy, no named volumes
- deploy.sh mirroring vllmScripts git workflow (push -> pull -> restart -> health)
- docs/ Obsidian vault: per-service docs from frank-default-small research
  subagents (promtail EOL -> Alloy; gitea SECRET_KEY preservation; ComfyUI --cpu)
- bats test suite at 6 seams — 22 tests green
This commit is contained in:
Frank committed 2026-08-13 20:19:41 -07:00
commit e3eb5334cb
57 files changed
+3033

No files matched your search

+68
View File
@@ -0,0 +1,68 @@
# 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
1. **Source the config from the target machine** — fetch the live compose/Caddyfile from the server where it runs
2. **Place it in this repo** — commit the fetched version (redact secrets into `.env`)
3. **Edit here** — make all changes locally in the working tree
4. **Run the tests** — `./tests/run.sh` must pass
5. **Commit and push** — push to origin (Gitea on dankclaw)
6. **Pull on the target** — `git pull` on the remote machine
7. **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
- 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. |