chore: initial homelab stack config and sync tooling

Mirror the three production files (docker-compose.yml, .env, Caddyfile) that live on valhalla, plus the push/pull PowerShell scripts, CLAUDE.md, .gitignore/.gitattributes, and .claude/skills for ssh/apply/sync.
2026-06-02 22:12:07 -05:00
commit 56d834ede9
11 changed files with 1426 additions and 0 deletions
@@ -0,0 +1,51 @@
+---
+name: homelab-ssh
+description: Connect to and run commands on the valhalla homelab server (ginnoir@valhalla) over SSH, including docker-compose operations through the `dc` alias. Use when inspecting the live stack, tailing logs, restarting a service, reloading Caddy, or checking container/file state on the server.
+---
+
+# homelab-ssh
+
+The production homelab runs on a headless Ubuntu host reachable at `ssh ginnoir@valhalla` (key-based auth; resolves and works from this Windows host directly).
+
+## Connect (non-interactive / safe for automation)
+
+Always pass `-o BatchMode=yes` so a missing key or password prompt fails fast instead of hanging:
+
+```powershell
+ssh -o BatchMode=yes -o ConnectTimeout=8 ginnoir@valhalla "<command>"
+```
+
+The first `Bash` command of a session is gated by a GateGuard hook — state the user request + what the command does, then retry.
+
+## docker-compose via the `dc` alias
+
+The stack is Docker Compose **v1.27.4** (`docker-compose`, hyphenated — `docker compose` v2 is not installed). On the server, `dc` is aliased in `~/.bashrc` to:
+
+```
+docker-compose -f ~/htpc-download-box/docker-compose.yml --env-file ~/htpc-download-box/.env
+```
+
+It's a shell alias, so it only exists in an interactive shell. Invoke it with `bash -ic`:
+
+```powershell
+ssh ginnoir@valhalla "bash -ic 'dc ps'"
+ssh ginnoir@valhalla "bash -ic 'dc logs -f --tail=200 <service>'"
+ssh ginnoir@valhalla "bash -ic 'dc restart <service>'"
+ssh ginnoir@valhalla "bash -ic 'dc up -d'"
+ssh ginnoir@valhalla "bash -ic 'dc exec caddy caddy reload --config /etc/caddy/Caddyfile'"
+```
+
+Use the compose **service name** (`sonarr`, `caddy`, `app`, …). Without `bash -ic`, `dc` is "command not found".
+
+## Key paths on the server
+
+- `~/htpc-download-box/docker-compose.yml`, `~/htpc-download-box/.env` — stack definition
+- `/config/caddy/Caddyfile` — Caddy config (mounted into the `caddy` container at `/etc/caddy/Caddyfile`)
+- `/config/<service>/` — per-service persisted config; `/storage1/` — media & data; plus named Docker volumes
+- `~/htpc-download-box/` also holds unrelated legacy files (`*.bak`, old `.git`, `README.md`, `Vagrantfile`) — don't modify them
+
+## Notes
+
+- Read-only exploration of `/config`, `/storage1`, and container state is fine for answering questions.
+- Avoid destructive commands against the live stack without explicit confirmation.
+- To push config changes and apply them, use the `homelab-apply` skill; to pull prod config into the repo, use `homelab-sync`.