docs: ARM64 LiteLLM hardening fixes for spark-02 bare-metal setup

[cmdlabtech]

$(cat <<'EOF'

Summary

Four production issues discovered on ARM64 Ubuntu 24.04 (spark-02 bare-metal systemd) that don't affect spark-01 (Docker Compose). Each fix is documented with root-cause explanation and verified expected output.

• Step 3a (install): Uninstall litellm-proxy-extras (prevents prisma migrate deploy conflicts on fresh ARM64 DB); explicitly fetch linux-arm64-openssl-3.0.x prisma query engine binary (auto-discovery fails on aarch64/GB10, causing prisma-query-engine PID N is dead loops)
• Step 3b (systemd service): Add DATABASE_URL to override.conf drop-in — prisma query engine subprocess reads env directly, not from litellm-config.yaml
• Step 3d (Postgres + Prisma schema): Switch postgres container to --network host; replace prisma db push with --force-reset --skip-generate to avoid migration history conflicts; add journalctl verify and Admin UI check; add post-upgrade reminder
• Step 5 (Client Open WebUI): Add callout that OPENAI_API_KEY must exactly match master_key — drift causes 401 Unauthorized on every chat request
• Known issues: Four new ARM64-specific entries covering all four failure modes above

Test plan

• Verify Step 3a code block renders correctly with ARM64 fix comments and prisma py fetch / prisma generate commands
• Verify Step 3b service block includes override.conf creation with DATABASE_URL before daemon-reload
• Verify Step 3d postgres docker run uses --network host (not -p 5432:5432), --force-reset --skip-generate on prisma push, and includes journalctl + curl verify blocks
• Verify Step 5 warning callout appears before the docker run block with the key-mismatch check commands
• Verify 4 new ARM64 issue entries appear in the Known Issues section with correct Symptom/Cause/Fix structure

https://claude.ai/code/session_013uGhhRTYyquQXYrbiWPavA
EOF
)

---

Generated by Claude Code