File size: 4,748 Bytes
175b650 5ed6f37 175b650 5ed6f37 175b650 5ed6f37 175b650 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 | # How to run the site locally
End-to-end development setup: backend Python env, frontend dev server, checkpoints on disk. Pick the path that matches what you're working on — backend-only and frontend-only flows are both supported. For a deployment-equivalent run see [guides/deploy.md](deploy.md) (`docker compose up`).
## Prerequisites
- Mamba (or conda). The repo root has an `environment.yml` capturing the conda half of the env.
- Node 20+ and npm.
- ~6 GB of free disk for the checkpoints if you intend to run inference locally.
- Optional: a Hugging Face account if you want to publish or update checkpoints.
- For Docker (`docker compose up`): WSL2 with at least **12 GB** of memory. Bumping `/dev/shm` is handled by `docker-compose.yml` (`shm_size: "2gb"`). Edit `%UserProfile%\.wslconfig`:
```ini
[wsl2]
memory=12GB
processors=4
swap=4GB
```
then `wsl --shutdown` and restart Docker Desktop. The peak boot RAM is ~5–6 GB while the three COINs Loaders compute graph metrics.
## 1. Create the Python environment
From the repo root:
```bash
mamba env create -n website_c -f environment.yml
mamba activate website_c
pip install --extra-index-url https://download.pytorch.org/whl/cu118 -r src/backend/requirements.txt
```
This mirrors what the deployment image installs. The CUDA 11.8 wheels work on CPU-only machines too — they just bundle the CUDA runtime.
## 2. Pull checkpoints
If you have a Hugging Face account and the `Bani57/checkpoints` repo is accessible to you:
```bash
huggingface-cli login # paste a read token
python -c "from huggingface_hub import snapshot_download; \
snapshot_download(repo_id='Bani57/checkpoints', \
local_dir='src/research', local_dir_use_symlinks=False)"
```
If you only need the discovery endpoints (no inference), you can skip this — the backend logs warnings about missing checkpoints but starts up fine.
## 3. Run the Django backend
From `src/backend/`:
```bash
DJANGO_DEBUG=True python manage.py runserver 8000
```
The server listens on `http://localhost:8000`. The first start will:
- Skip the HF Hub download because the local `src/research/.../checkpoints/` dirs are populated.
- Scan checkpoints, load Loaders, generate sample subgraphs (~30 s).
- Then accept traffic.
`DJANGO_DEBUG=True` enables verbose error pages and exposes `POST /api/v1/debug/force-unlock`. Without it (`False`), `ALLOWED_HOSTS` and `CORS_ALLOWED_ORIGINS` are enforced strictly — set them via env vars.
Confirm with:
```bash
curl http://localhost:8000/api/v1/health
```
## 4. Run the Vue frontend
In a second shell, from `src/frontend/`:
```bash
npm install # one-time
npm run dev
```
Vite serves on `http://localhost:5173`. The dev env (`src/frontend/.env.development`) points the SPA at `http://localhost:8000` for API calls — you'll need both servers running.
Open `http://localhost:5173` and exercise the three demos.
## 5. Hand-test the API
The Postman collection at `docs/postman/collection.json` covers every discovery endpoint and the prediction endpoint with sensible request bodies. Import the collection plus `docs/postman/environment.json`, point the base URL variable at `http://localhost:8000/api/v1`, and run.
For the streaming endpoints, browser dev tools (Network tab → an active SSE connection shows individual frames) are usually more informative than Postman.
## Troubleshooting
### "ModelRegistry not initialized"
You hit a view before `AppConfig.ready()` finished. Wait for the boot logs to print "ModelRegistry initialized" and retry.
### "Stale machines.npz for {dataset}: rebuilding"
Harmless. The cached `machines_*.npz` file on disk has an old `num_communities`; the registry rebuilds it in memory.
### `INFERENCE_BUSY` (429)
Another inference is already running. Wait, or `POST http://localhost:8000/api/v1/debug/force-unlock` if `DEBUG=True`.
### Frontend hits the wrong URL
Check `src/frontend/.env.development`. In dev it should be `VITE_API_BASE_URL=http://localhost:8000`. The composables append `/api/v1` themselves.
### `whitenoise` / `huggingface_hub` / `gunicorn` missing
The deployment image installs them; locally you may not need them, but if you've enabled `whitenoise` middleware in dev (it is in `MIDDLEWARE`) you do:
```bash
pip install "whitenoise[brotli]" huggingface_hub gunicorn
```
## See also
- [reference/api.md](../reference/api.md) — endpoint contracts.
- [reference/frontend-modules.md](../reference/frontend-modules.md) — frontend project layout.
- [explanation/inference-lifecycle.md](../explanation/inference-lifecycle.md) — what happens at boot and on each request.
- [guides/deploy.md](deploy.md) — running the full container locally and pushing to the HF Space.
|