dev-env(proxmox): switch compose to direct-port exposure; document homelab topology

- docker-compose.dev.yml: drop Traefik/dev.resolutionflow.com labels, expose
  backend:8000 and frontend:5173 directly; swap relative bind mounts for
  ${REPO_ROOT}/... so compose works when driven from inside a code-server
  container with the host Docker socket mounted; default POSTGRES_PORT to
  5433 host-side; add explicit uvicorn/npm run dev commands; add
  ENABLE_MCP_MICROSOFT_LEARN and docker-01/Tailscale CORS origins.
- frontend/vite.config.ts: replace dev.resolutionflow.com with
  allowedHosts=['docker-01', '.ts.net', 'localhost'] for direct-port access
  over the private network.
- DEV-ENV.md: add Section 11 reference topology for the homelab Proxmox +
  code-server Option B setup, plus troubleshooting entries for the
  REPO_ROOT-empty-mount trap and the Vite allowedHosts rejection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

DEV-ENV.md

@@ -83,7 +83,7 @@ DEV_HOST              = <hostname or IP your browser uses, e.g. dev.internal, 10
 DEV_HOST_SCHEME       = <http or https; http is fine for internal dev, https if behind a TLS proxy>
 FRONTEND_PORT         = 5173
 BACKEND_PORT          = 8000
-POSTGRES_PORT         = 5432  # or 5433 if you're avoiding conflict with a host Postgres
+POSTGRES_PORT         = 5433  # host-side port. 5433 is the recommended default on any shared host to avoid collision with a host-level Postgres. The container's internal port stays 5432.
 POSTGRES_DB_NAME      = resolutionflow
 POSTGRES_USER         = postgres
 POSTGRES_PASSWORD     = <local-dev-password; anything, this is not prod>
@@ -149,7 +149,7 @@ sudo -u postgres psql -c "ALTER USER postgres PASSWORD 'postgres';"
 # Adjust pg_hba.conf if you need non-local connections.
 ```
 
-**Option B (Postgres via Docker Compose):** The repo has a `docker-compose.dev.yml` at the root. Check its Postgres service for the container name, port mapping, and volume. CLAUDE.md Lesson 65 notes the local compose defaults use container name `resolutionflow_postgres`, database `resolutionflow`, port `5433` mapped to the host. Confirm what the compose file actually says on your branch before trusting those values.
+**Option B (Postgres via Docker Compose):** The repo has a `docker-compose.dev.yml` at the root. Check its Postgres service for the container name, port mapping, and volume. The local compose defaults use container name `resolutionflow_postgres`, database `resolutionflow`, and host-side port `5433` (mapped to the container's internal `5432`) — see CLAUDE.md Lesson 65. The host-side `5433` is the recommended default on any shared host: it keeps the port free for a host-level Postgres if you ever need one. The compose file also defines explicit `command:` directives on both `backend` and `frontend` to force `--host 0.0.0.0`, and expects the caller to pass `REPO_ROOT` (see 5.4) for bind-mount resolution. Confirm what the compose file actually says on your branch before trusting these values.
 
 ```bash
 docker compose -f docker-compose.dev.yml up -d db
@@ -217,6 +217,15 @@ SECRET_KEY=<SECRET_KEY>
 ANTHROPIC_API_KEY=<ANTHROPIC_API_KEY>
 GOOGLE_AI_API_KEY=<GOOGLE_AI_API_KEY or leave unset>
 POSTGRES_PORT=<POSTGRES_PORT>
+# Absolute host-side path to the repo root. REQUIRED whenever docker-compose is
+# invoked from inside a container (e.g. a code-server container with the host
+# Docker socket mounted in). Without it, the bind mounts in
+# docker-compose.dev.yml (`${REPO_ROOT}/backend:/app`, `${REPO_ROOT}/frontend:/app`)
+# resolve against the CLI's CWD — a path the host daemon cannot see — and
+# Docker silently creates empty directories there instead of mounting the code.
+# If you run docker compose directly on the host shell, you can set this to `.`
+# or the absolute path of the repo; being explicit is safer either way.
+REPO_ROOT=/absolute/path/to/resolutionflow
 ```
 
 > **Never commit any `.env` file.** The `.gitignore` already covers this.
@@ -487,6 +496,14 @@ Only on a local branch that has diverged from `origin/main`. Production `main` h
 
 Filesystem permission issue inside the code-server container (CLAUDE.md Lesson 105). TypeScript compilation itself completes — use `npx tsc -b` to verify cleanliness without needing to write to `dist/`.
 
+### Backend/frontend containers start but `/app` is empty (no code mounted)
+
+Almost always a `REPO_ROOT` problem. `docker-compose.dev.yml` uses `${REPO_ROOT}/backend:/app` and `${REPO_ROOT}/frontend:/app` bind mounts. If `REPO_ROOT` is unset, or set to a path that doesn't exist *on the Docker host* (not inside the code-server container), Docker silently creates an empty directory at that path and mounts it — the containers come up but have no source code. Symptom: backend returns import errors, or frontend serves a default Vite page. Fix: set `REPO_ROOT` in the repo-root `.env` to the absolute host-side path to the repo, then `docker compose down && docker compose up -d`. See 5.4 for the full note. This matters specifically when `docker compose` is invoked from inside a container (e.g. code-server with the host Docker socket mounted) — the CLI's CWD is container-local but the daemon resolves paths against the host filesystem.
+
+### Frontend shows "Blocked request. This host is not allowed" in the browser
+
+Vite 5+ ships DNS-rebinding protection that rejects any `Host:` header not in `server.allowedHosts`. The browser's hostname must be in that list. Edit `frontend/vite.config.ts` — the `server.allowedHosts` array should include every hostname you reach the dev server from (e.g. `'docker-01'`, `'localhost'`, `.ts.net` as a wildcard for Tailscale MagicDNS). Restart the Vite dev server (for Option B: `docker compose restart frontend`). This is unrelated to CORS — Vite blocks the request before any app code runs.
+
 ### `docker` command not found inside code-server
 
 If your code-server is itself inside a container, Docker is probably not exposed to it. CLAUDE.md Lesson 103 was written for this case on the old VPS. On Proxmox, the fix depends on topology — either SSH to the host to run Docker commands, or mount the host's Docker socket into the code-server container.
@@ -516,8 +533,139 @@ This doc is about dev, not production. But:
 ## 10. What's not in this doc
 
 - **Production deployment.** This is a dev-env doc. Production lives on Railway — see `CLAUDE.md`'s Deployment section.
-- **How to set up Traefik or any particular reverse proxy.** Whichever proxy you use is your choice; the dev stack just needs something that routes `<host>:5173` and `<host>:8000` to the right services.
+- **How to set up Traefik or any particular reverse proxy.** Whichever proxy you use is your choice; the dev stack just needs something that routes `<host>:5173` and `<host>:8000` to the right services. **Direct port exposure over a private network** (Tailscale, WireGuard, a VPN, or a LAN behind a firewall) is a fully supported option for dev and is what the homelab reference topology in Section 11 uses — no reverse proxy, no TLS, just `http://<host>:5173` and `http://<host>:8000` reachable only from the private network. That's a perfectly reasonable choice; it's just not the only one.
 - **How to configure code-server itself.** Install it however you prefer (native, Docker, LXC); point it at the repo, and the rest of this doc applies.
 - **Where to host the Proxmox instance.** Up to you.
 
 If something in this doc turns out to be wrong on your host, fix the doc. This is a living document — the whole point of rewriting it from the Hostinger-specific version was to make it survive host changes.
+
+---
+
+## 11. Reference topology: homelab Proxmox + code-server (Option B)
+
+This section documents the first concrete host instantiation since the April 2026 host-agnostic rewrite. It's a worked example, not the canonical topology — Section 3's Option A/B/C framing still stands. If your setup looks different, follow Sections 1–10 and ignore this appendix.
+
+### 11.1 Host
+
+- **Hypervisor:** Proxmox (homelab).
+- **VM:** `docker-01`, Debian 13, running Docker Engine + Docker Compose natively.
+- **Tailscale IP:** `100.64.78.44`. MagicDNS hostname: `docker-01` (and the full `.ts.net` FQDN).
+- **code-server:** runs on the same VM in its own container, with the host's Docker socket mounted in so it can drive `docker compose`. Its workspace bind-mounts the repo at `/opt/docker/code-server/workspace/resolutionflow`.
+
+This is a concrete instance of Option B from Section 3: Postgres, backend, and frontend all run as containers from `docker-compose.dev.yml`; the editor lives outside that compose network.
+
+### 11.2 Access pattern — direct port over Tailscale, no reverse proxy
+
+The browser reaches the dev stack directly:
+
+- Frontend: `http://docker-01:5173`
+- Backend: `http://docker-01:8000`
+- Backend API docs: `http://docker-01:8000/api/docs`
+
+There is **no Caddy, no Traefik, no nginx, no TLS, no basic auth** in front of either service. The tailnet provides the wire encryption and access control — only devices on the tailnet can resolve `docker-01` or reach `100.64.78.44`, and Tailscale ACLs decide which of those devices are allowed to connect.
+
+Why this choice:
+
+- **Zero routing config to maintain.** There is no proxy rulebook to keep in sync with new services. Add a container, expose a port, you're done.
+- **Backend-to-backend services stay private.** Redis, Celery workers, the planned ConnectWise proxy, the MCP server — none of them need to be reachable from the browser, so none of them need proxy rules. They stay inside the `resolutionflow` Docker network and talk by service name. The proxy would only ever have carried frontend and backend traffic, so the proxy's value was small relative to its maintenance cost.
+- **Debuggability.** `curl http://docker-01:8000/api/docs` from any tailnet device works without auth headers, TLS handshakes, or DNS shenanigans.
+
+Tradeoff: **this only works because every client device is on the tailnet.** If someone needed to test from a non-tailnet device, they'd either join the tailnet or we'd need to front the stack with a proxy. For the current single-developer setup, the tailnet-only assumption holds.
+
+### 11.3 Per-host config values (as actually configured on `docker-01`)
+
+Plugging these into Section 4's template:
+
+```
+DEV_HOST              = docker-01
+DEV_HOST_SCHEME       = http
+FRONTEND_PORT         = 5173
+BACKEND_PORT          = 8000
+POSTGRES_PORT         = 5433         # host-side; container-internal stays 5432
+POSTGRES_DB_NAME      = resolutionflow
+POSTGRES_USER         = postgres
+POSTGRES_PASSWORD     = postgres     # local-dev only
+SECRET_KEY            = <generated per host; do not reuse>
+ANTHROPIC_API_KEY     = <from console.anthropic.com>
+GOOGLE_AI_API_KEY     = <unset; Anthropic is sole provider in dev>
+```
+
+And the repo-root `.env` that `docker-compose.dev.yml` interpolates from:
+
+```bash
+SECRET_KEY=<redacted>
+ANTHROPIC_API_KEY=<redacted>
+POSTGRES_PORT=5433
+REPO_ROOT=/opt/docker/code-server/workspace/resolutionflow
+```
+
+### 11.4 Why `REPO_ROOT` is non-optional on this host
+
+code-server runs inside a container. When you open a terminal in code-server and run `docker compose -f docker-compose.dev.yml up -d`, the Docker CLI talks to the *host* daemon via the mounted socket — but the CWD it reports (`/config/workspace/resolutionflow`) is a path that only exists inside the code-server container. The host daemon has never heard of it.
+
+Relative bind mounts like `./backend:/app` therefore resolve against a path the host can't see, and Docker silently creates empty directories there rather than erroring out. The containers come up, but `/app` is empty.
+
+`docker-compose.dev.yml` sidesteps this by using `${REPO_ROOT}/backend:/app` and `${REPO_ROOT}/frontend:/app`. `REPO_ROOT` must be set to the absolute path **on the host** (`/opt/docker/code-server/workspace/resolutionflow`), not the path inside the code-server container. Same contents, different mount point, different name.
+
+If you ever run `docker compose` directly from a host shell (SSH'd into `docker-01`), set `REPO_ROOT` to `.` or the absolute host path. Being explicit is always safe; leaving it unset is the failure mode.
+
+### 11.5 Vite `server.allowedHosts` — required for `docker-01` to resolve
+
+Vite 5+ rejects any `Host:` header not in `server.allowedHosts` (DNS-rebinding protection). `frontend/vite.config.ts` has:
+
+```ts
+server: {
+  host: '0.0.0.0',
+  allowedHosts: ['docker-01', '.ts.net', 'localhost'],
+  ...
+}
+```
+
+- `docker-01` — the MagicDNS short name the browser uses day-to-day.
+- `.ts.net` — wildcard for the full Tailscale MagicDNS FQDN, in case anyone uses it.
+- `localhost` — for the "am I serving anything at all" smoke-test from inside the container.
+
+If you move this setup to a different host, add that host's hostname to `allowedHosts` or the browser will see "Blocked request. This host is not allowed." See Section 8's troubleshooting entry for the full symptom/fix.
+
+### 11.6 CORS origins on this host
+
+The `backend` service's `CORS_ORIGINS` environment variable is pinned in the compose file to:
+
+```
+["http://localhost:5173","http://127.0.0.1:5173","http://docker-01:5173","http://100.64.78.44:5173"]
+```
+
+The last two are what make browser calls from tailnet clients work — they cover both MagicDNS (`docker-01`) and the raw Tailscale IP. If you add a new hostname to reach the frontend from, also add the matching origin here and restart the backend.
+
+### 11.7 Compose file shape (as of this writing)
+
+`docker-compose.dev.yml` has been through a round of cleanup for this topology. Specifics worth knowing if you're comparing against older revisions of the file:
+
+- **No Traefik labels.** They were removed — nothing in this topology uses Traefik.
+- **No Hostinger-VPS-era origins** in `CORS_ORIGINS`.
+- `Dockerfile.dev` for both `backend` and `frontend` is still the build source — this didn't change.
+- Explicit `command:` directives on both `backend` (`uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload`) and `frontend` (`npm run dev -- --host 0.0.0.0 --port 5173`) — this guarantees `--host 0.0.0.0` regardless of what's baked into the image, so the services listen on all interfaces and are reachable from outside the container.
+- `REPO_ROOT` is interpolated into both service volume mounts (see 11.4).
+
+If you're adapting the file for a different host, the things most likely to need editing are `REPO_ROOT` (see 11.4), `CORS_ORIGINS` (see 11.6), `FRONTEND_URL`, `VITE_API_URL`, and `POSTGRES_PORT` if you want something other than `5433`.
+
+### 11.8 End-to-end sanity check for this topology
+
+From any device on the tailnet:
+
+```bash
+# Backend reachable
+curl -sSf http://docker-01:8000/api/docs >/dev/null && echo OK
+
+# Frontend reachable
+curl -sSf http://docker-01:5173 >/dev/null && echo OK
+
+# Alembic head matches the branch expectation
+docker exec resolutionflow_backend alembic current
+# expect f07010f17b01 on feat/flowpilot-migration, 074 on main
+
+# Postgres is alive inside the compose network
+docker exec resolutionflow_postgres psql -U postgres -d resolutionflow -c "SELECT now();"
+```
+
+All four passing = the dev environment is live end-to-end.

docker-compose.dev.yml

@@ -1,4 +1,5 @@
 name: resolutionflow
+
 services:
   db:
     image: pgvector/pgvector:pg16
@@ -8,7 +9,7 @@ services:
       POSTGRES_PASSWORD: postgres
       POSTGRES_DB: resolutionflow
     ports:
-      - "${POSTGRES_PORT:-5432}:5432"
+      - "${POSTGRES_PORT:-5433}:5432"
     volumes:
       - rf_postgres_data:/var/lib/postgresql/data
     healthcheck:
@@ -22,8 +23,11 @@ services:
       context: ./backend
       dockerfile: Dockerfile.dev
     container_name: resolutionflow_backend
+    command: uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+    ports:
+      - "8000:8000"
     volumes:
-      - ./backend:/app
+      - ${REPO_ROOT}/backend:/app
     environment:
       - APP_NAME=ResolutionFlow
       - DEBUG=true
@@ -33,42 +37,34 @@ services:
       - ALGORITHM=HS256
       - ACCESS_TOKEN_EXPIRE_MINUTES=15
       - REFRESH_TOKEN_EXPIRE_DAYS=7
+      - REQUIRE_INVITE_CODE=true
       - FEEDBACK_EMAIL=feedback@resolutionflow.com
       - AI_PROVIDER=anthropic
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
-      - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY}
+      - GOOGLE_AI_API_KEY=${GOOGLE_AI_API_KEY:-}
-      - CORS_ORIGINS=["http://localhost:3000","http://localhost:5173","http://127.0.0.1:3000","http://127.0.0.1:5173","http://46.202.92.250:5173","http://46.202.92.250:3000","https://resolutionflow.com","https://www.resolutionflow.com"]
+      - ENABLE_MCP_MICROSOFT_LEARN=true
+      - FRONTEND_URL=http://docker-01:5173
+      - CORS_ORIGINS=["http://localhost:5173","http://127.0.0.1:5173","http://docker-01:5173","http://100.64.78.44:5173"]
     depends_on:
       db:
         condition: service_healthy
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.rf-api.rule=Host(`dev.resolutionflow.com`) && PathPrefix(`/api`)"
-      - "traefik.http.routers.rf-api.entrypoints=websecure"
-      - "traefik.http.routers.rf-api.tls.certresolver=letsencrypt"
-      - "traefik.http.services.rf-api.loadbalancer.server.port=8000"
 
   frontend:
     build:
       context: ./frontend
       dockerfile: Dockerfile.dev
     container_name: resolutionflow_frontend
+    command: npm run dev -- --host 0.0.0.0 --port 5173
+    ports:
+      - "5173:5173"
     volumes:
-      - ./frontend:/app
+      - ${REPO_ROOT}/frontend:/app
       - /app/node_modules
     environment:
-      - VITE_API_URL=https://dev.resolutionflow.com/
+      - VITE_API_URL=http://docker-01:8000
+      - CHOKIDAR_USEPOLLING=true
     depends_on:
       - backend
-    labels:
-      - "traefik.enable=true"
-      - "traefik.http.routers.rf-frontend.rule=Host(`dev.resolutionflow.com`)"
-      - "traefik.http.routers.rf-frontend.middlewares=dev-auth"
-      - "traefik.http.middlewares.dev-auth.basicauth.users=chihlasm:$$apr1$$dJXUAZ3Y$$SsJm.K8fOjCeNMe4B70Bi0"
-      - "traefik.http.routers.rf-frontend.entrypoints=websecure"
-      - "traefik.http.routers.rf-frontend.tls.certresolver=letsencrypt"
-      - "traefik.http.services.rf-frontend.loadbalancer.server.port=5173"
 
 volumes:
-  rf_postgres_data:
+  rf_postgres_data:
- 

frontend/vite.config.ts

@@ -19,7 +19,7 @@ export default defineConfig({
   ],
   server: {
     host: '0.0.0.0',
-    allowedHosts: ['dev.resolutionflow.com'],
+    allowedHosts: ['docker-01', '.ts.net', 'localhost'],
     watch: {
       usePolling: true,
     },