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).

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.

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.

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 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.

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.

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.

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 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.