# Homelab Claude Code Instructions

## Deployment

- When deploying services, always verify the target host before proceeding. Confirm which host a service should run on and check for port conflicts with existing services.
- Check `ss -tlnp | grep <port>` on the target host before deploying.
- Hosts: atlantis (Synology NAS, media/arr), calypso (Synology, DNS/SSO), olares (K3s, GPU), nuc (lightweight), rpi5 (Kuma), homelab-vm (monitoring/dashboard), guava (TrueNAS), seattle (remote), matrix-ubuntu (NPM/CrowdSec).

## Configuration Management

- Before modifying config files (YAML, JSON, etc.), always create a backup copy first.
- Never use sed for complex YAML edits — use a proper parser or manual editing to avoid duplicate keys and corruption.
- For YAML changes, validate with `python3 -c "import yaml; yaml.safe_load(open('file.yaml'))"` after editing.
- Never empty or overwrite a config file without reading it first.

## Homelab SSH & Networking

- For homelab SSH operations: if MCP SSH times out on large outputs, fall back to Bash with `ssh` directly.
- Always use the correct Tailscale/LAN IP for each host. When Ollama or other services aren't on localhost, check the memory or ask for the correct endpoint before guessing.
- After making infrastructure changes (Tailscale, DNS, networking), always verify connectivity from affected hosts before marking complete.
- Never run a second instance of a network daemon (tailscaled, etc.) — it will break host networking.
- homelab-vm IS localhost — never SSH into it, use local commands.

## LLM Services

- When working with LLM model deployments (Ollama, vLLM), always verify: 1) GPU access, 2) context length meets the consumer's requirements, 3) tool-calling support if needed.
- Ollama is at `http://192.168.0.145:31434` (Olares LAN NodePort), NOT localhost.
- HAMI vGPU on Olares causes ffmpeg segfaults — do NOT request `nvidia.com/gpu` resources, use `runtimeClassName: nvidia` directly.

## Olares (K3s)

- Olares admission webhook blocks hostNetwork and reverts custom NetworkPolicies.
- Use Calico GlobalNetworkPolicy for LAN access (it can't be overridden by the webhook).
- The Olares proxy adds ~100ms latency — use direct LAN NodePorts for streaming/high-throughput services.
- Marketplace app patches (NFS mounts, GPU) are lost on app updates — re-apply after updates.

## Git & Commits

- Never add Co-Authored-By lines to git commits.
- Always run `detect-secrets scan --baseline .secrets.baseline` before committing if secrets baseline exists.
- Use `pragma: allowlist secret` comments for intentional secrets in private repo files.

## Documentation

- After completing each task, immediately update the relevant documentation in the repo and commit with a descriptive message before moving to the next task.
- Key docs: `docs/services/individual/dashboard.md`, `docs/services/individual/olares.md`, `scripts/README.md`.

## Portainer

- API uses `X-API-Key` header (NOT Bearer token).
- Portainer URL: `http://100.83.230.112:10000` (Tailscale IP).
- Endpoints: atlantis=2, calypso=443397, nuc=443398, homelab=443399, rpi5=443395.
- GitOps stacks use Gitea token for auth — if redeploy fails with "authentication required", credentials need re-entry in Portainer UI.

## Dashboard

- Dashboard runs at `http://homelab.tail.vish.gg:3100` (Next.js on port 3100, FastAPI API on port 18888).
- API proxied through Next.js rewrites — frontend calls `/api/*` which routes to localhost:18888.
- 16 glassmorphism themes with Exo 2 font.
- To rebuild: `cd dashboard/ui && rm -rf .next && BACKEND_URL=http://localhost:18888 npm run build && cp -r .next/static .next/standalone/.next/static && cp -r public .next/standalone/public`.