The previous version was tightly coupled to the Hostinger VPS at
46.202.92.250 — hardcoded IP, Traefik/Let's-Encrypt assumption,
specific Docker-volume paths. Rewriting ahead of the Proxmox migration
so a fresh clone on any Linux host (LXC, VM, bare metal, VPS) can
stand up a working dev environment without pre-baked assumptions about
topology.
Structural changes:
- Introduces Option A (all-in-one host) / Option B (Docker Compose) /
Option C (split services) topology choice up front, so readers
commit to one shape before touching commands.
- Adds a "per-host configuration" template the reader fills in once
(DEV_HOST, POSTGRES_PORT, SECRET_KEY, API keys), referenced by name
throughout the rest of the doc. No more hardcoded IPs.
- Adds an explicit verification section (Section 6) with concrete
expected outcomes: alembic head, reversibility, prompt-cache hit,
frontend build, /assistant→/pilot redirect, dispatcher routing, CORS.
- References the Phase 0 TODO(phase0-verify) in ai_provider.py and
the expected alembic head (f07010f17b01) as of the current branch.
- Adds a troubleshooting section pulling in CLAUDE.md lessons that
bite people repeatedly: stale Vite env vars, RLS policy violations,
EACCES on dist/, multi-head alembic state, invisible cache misses.
- Documents the structured log events the backend emits
(anthropic.cache, mcp.turn, mcp.fallback) so readers know what to
grep for during verification.
Deliberately excluded:
- Production deployment (lives in CLAUDE.md Deployment section).
- Reverse-proxy configuration (whatever the reader prefers).
- code-server install specifics (Docker vs LXC vs native is reader's
choice; once running, this doc applies).
- Proxmox-specific instructions — the doc is host-agnostic so it
survives the next migration as well.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
