Hugging Face's logo

Spaces:
Bani57
/
website
Sleeping

App Files Community
website / docs /guides /local-development.md
Andrej Janchevski
docs(deploy): refresh for the post-launch deployment iteration
5ed6f37
preview code
|
raw
history blame contribute delete
4.75 kB

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 (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:
    [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:

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:

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/:

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:

curl http://localhost:8000/api/v1/health

4. Run the Vue frontend

In a second shell, from src/frontend/:

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:

pip install "whitenoise[brotli]" huggingface_hub gunicorn

See also