From 87886213beb1aa67ff43493d2d2d8a162b6b96ea Mon Sep 17 00:00:00 2001 From: MCR-3 Date: Tue, 22 Sep 2026 12:46:04 +0200 Subject: [PATCH] feat: add Docker Compose dev environment Running the app locally meant managing a Python venv and installing frontend dependencies by hand, then starting uvicorn and Vite as two separate manual processes. `docker compose up` now boots both with hot reload, so neither is required for day-to-day development. - backend/Dockerfile.dev and frontend/Dockerfile.dev install dependencies at build time; source is bind-mounted in for reload/HMR. - compose.yaml wires them up on the same ports (8000/5173) the manual workflow already used. Verification (build/lint/analyzer) runs via `docker compose exec`. - Vite's watcher needs polling to see bind-mounted changes under Docker Desktop on Windows; gated behind VITE_USE_POLLING so local (non-Docker) dev is unaffected. - .oxlintrc.json now ignores node_modules/dist explicitly rather than relying on the ambient .gitignore, since the frontend container's bind mount has no .git to discover it from. - The dev Dockerfiles/compose.yaml are entirely separate from the root Dockerfile and render.yaml, which still drive the Render and GitHub Pages deploys unchanged. Closes #26 --- CLAUDE.md | 20 +++++++++++++++++--- backend/.dockerignore | 2 ++ backend/Dockerfile.dev | 6 ++++++ compose.yaml | 24 ++++++++++++++++++++++++ frontend/.dockerignore | 2 ++ frontend/.oxlintrc.json | 1 + frontend/Dockerfile.dev | 6 ++++++ frontend/vite.config.ts | 5 +++++ 8 files changed, 63 insertions(+), 3 deletions(-) create mode 100644 backend/.dockerignore create mode 100644 backend/Dockerfile.dev create mode 100644 compose.yaml create mode 100644 frontend/.dockerignore create mode 100644 frontend/Dockerfile.dev diff --git a/CLAUDE.md b/CLAUDE.md index 96ad0ac..4ae5a9e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,18 @@ Visualizes a codebase's function call graph as draggable Blueprint-style cards. Run from the repo root unless noted. Dev machine is Windows; both PowerShell and Git Bash work. +```sh +# Preferred: Docker Compose (no local venv or node_modules to manage) +docker compose up # backend on :8000 (--reload), frontend on :5173 (HMR) +docker compose up --build # after changing backend/requirements.txt or frontend/package.json +``` + +`compose.yaml` and `backend/Dockerfile.dev` / `frontend/Dockerfile.dev` are dev-only — they're +unrelated to the root `Dockerfile` used for the Render deploy (see CI/CD below). + +
+Fallback: running without Docker + ```sh # Backend (Python 3.10+; CI and Docker use 3.11) pip install -r backend/requirements.txt @@ -22,13 +34,15 @@ npm run lint # oxlint python -m backend.analyzer sample_project ``` +
+ ## Verifying a change There is **no test suite**. Verify by hand: -- Frontend: `npm run build` and `npm run lint` in `frontend/`. -- Backend: start uvicorn and `GET /api/health`. -- Analyzer or language-plugin changes: run `python -m backend.analyzer` on `sample_project`, `sample_rust_project` and `sample_typescript_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression. +- Frontend: `docker compose exec frontend npm run build` and `docker compose exec frontend npm run lint` (or run them in `frontend/` without Docker). +- Backend: with `docker compose up` running, `GET localhost:8000/api/health`. +- Analyzer or language-plugin changes: `docker compose exec backend python -m backend.analyzer ` on `sample_project`, `sample_rust_project` and `sample_typescript_project` before and after, and compare function and edge counts. An unexplained drop in edges is a regression. CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the backend health check. It does not lint and does not exercise the analyzer, so green CI says little about analysis correctness. diff --git a/backend/.dockerignore b/backend/.dockerignore new file mode 100644 index 0000000..7a60b85 --- /dev/null +++ b/backend/.dockerignore @@ -0,0 +1,2 @@ +__pycache__/ +*.pyc diff --git a/backend/Dockerfile.dev b/backend/Dockerfile.dev new file mode 100644 index 0000000..46229e8 --- /dev/null +++ b/backend/Dockerfile.dev @@ -0,0 +1,6 @@ +FROM python:3.11-slim +WORKDIR /app +COPY requirements.txt ./ +RUN pip install --no-cache-dir -r requirements.txt +EXPOSE 8000 +CMD ["uvicorn", "backend.main:app", "--reload", "--reload-dir", "backend", "--host", "0.0.0.0", "--port", "8000"] diff --git a/compose.yaml b/compose.yaml new file mode 100644 index 0000000..9c8325a --- /dev/null +++ b/compose.yaml @@ -0,0 +1,24 @@ +services: + backend: + build: + context: ./backend + dockerfile: Dockerfile.dev + volumes: + - .:/app + ports: + - "8000:8000" + + frontend: + build: + context: ./frontend + dockerfile: Dockerfile.dev + volumes: + - ./frontend:/app + - frontend_node_modules:/app/node_modules + ports: + - "5173:5173" + environment: + - VITE_USE_POLLING=true + +volumes: + frontend_node_modules: diff --git a/frontend/.dockerignore b/frontend/.dockerignore new file mode 100644 index 0000000..b947077 --- /dev/null +++ b/frontend/.dockerignore @@ -0,0 +1,2 @@ +node_modules/ +dist/ diff --git a/frontend/.oxlintrc.json b/frontend/.oxlintrc.json index 6fa991d..980fe9a 100644 --- a/frontend/.oxlintrc.json +++ b/frontend/.oxlintrc.json @@ -1,6 +1,7 @@ { "$schema": "./node_modules/oxlint/configuration_schema.json", "plugins": ["react", "typescript", "oxc"], + "ignorePatterns": ["node_modules", "dist"], "rules": { "react/rules-of-hooks": "error", "react/only-export-components": ["warn", { "allowConstantExport": true }] diff --git a/frontend/Dockerfile.dev b/frontend/Dockerfile.dev new file mode 100644 index 0000000..5719c83 --- /dev/null +++ b/frontend/Dockerfile.dev @@ -0,0 +1,6 @@ +FROM node:20-alpine +WORKDIR /app +COPY package.json package-lock.json ./ +RUN npm ci +EXPOSE 5173 +CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"] diff --git a/frontend/vite.config.ts b/frontend/vite.config.ts index 26d1dc3..6b47319 100644 --- a/frontend/vite.config.ts +++ b/frontend/vite.config.ts @@ -6,4 +6,9 @@ export default defineConfig({ // Render serves dist/ at "/"; GitHub Pages serves it under "/function-viewer/" (set via VITE_BASE_PATH). base: process.env.VITE_BASE_PATH ?? '/', plugins: [react()], + server: { + // Docker Desktop bind mounts don't reliably forward native FS change events; polling + // is what makes HMR work for the frontend dev container (see compose.yaml). + watch: process.env.VITE_USE_POLLING ? { usePolling: true } : undefined, + }, })