build(deploy): add docker image and compose for hf spaces

- Dockerfile: multi-stage build. Node 20 builds the Vue SPA, then a
mambaorg/micromamba runtime mirrors the local website_c env from
environment.yml + src/backend/requirements.txt (Python 3.9, rdkit
2023.03.2, boost 1.78, GPU torch+cu118 wheels). Exposes :7860 with
RESEARCH_ROOT=/app/research and CHECKPOINTS_ROOT=/app/checkpoints.
- entrypoint.sh: pre-warms huggingface_hub.snapshot_download from
bani57/checkpoints into /app/checkpoints before exec'ing gunicorn,
so worker startup never blocks on the network.
- docker-compose.yml: local-dev parity on http://localhost:7860 with a
named volume so checkpoints persist across runs. DJANGO_SECRET_KEY
is a required interpolation (${VAR:?...}) — compose fails fast if a
.env file isn't supplied.
- .env.example: template with the secrets.token_urlsafe recipe.
- .dockerignore: keeps node_modules, screenshots, datasets, local
checkpoints, .claude and plans/ out of the build context.
- .gitignore: ignore .env / build artefacts (staticfiles, dist), keep
.env.example and the Vite envs allow-listed.
- README.md: HF Space landing card with the required YAML front-matter
(sdk: docker, app_port: 7860).

.dockerignore

@@ -0,0 +1,34 @@
+# Keep the build context lean so Docker doesn't pipe gigabytes of unrelated
+# files (model weights, datasets, screenshots) to the daemon.
+.git
+.gitignore
+.idea
+.vscode
+.claude
+*.pyc
+__pycache__
+node_modules
+src/frontend/node_modules
+src/frontend/dist
+
+# Local checkpoints — pulled at runtime from HF Hub instead.
+src/research/**/checkpoints/*
+src/research/**/results/**/*.tar
+src/research/**/results/**/*.ckpt
+src/research/**/results/**/*.npz
+src/research/**/results/**/*.gz
+
+# Cached precomputations (regenerated on first boot if needed).
+src/research/**/*.npz
+src/research/**/*.gz
+
+# Local dev artefacts that don't belong in the image.
+docs
+plans
+.env
+.env.*
+!src/frontend/.env.production
+
+# OS
+.DS_Store
+Thumbs.db

.env.example

@@ -0,0 +1,16 @@
+# Local environment for `docker compose up`.  Copy to `.env` (which is
+# gitignored) and fill in the values.  In production these are configured as
+# Space secrets at https://huggingface.co/spaces/bani57/website/settings.
+
+# REQUIRED.  Generate with:
+#   python -c "import secrets; print(secrets.token_urlsafe(50))"
+DJANGO_SECRET_KEY=replace-me
+
+# Optional overrides (defaults shown).
+DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
+CORS_ALLOWED_ORIGINS=http://localhost:7860
+HF_CHECKPOINTS_REPO=bani57/checkpoints
+TORCH_DEVICE=cpu
+
+# Only needed if the checkpoint repo is private.
+# HF_TOKEN=hf_...

.gitignore

@@ -5,3 +5,14 @@ src/research/COINs-KGGeneration/graph_completion/checkpoints/
 src/research/COINs-KGGeneration/graph_generation/checkpoints/
 src/research/MultiProxAn/checkpoints/
 src/backend/.checkpoint_staging/
+
+# Local secrets — keep out of git.  Compose / docker auto-loads .env.
+.env
+.env.local
+!.env.example
+!src/frontend/.env.development
+!src/frontend/.env.production
+
+# Docker build artefacts that don't belong in source control.
+src/backend/staticfiles/
+src/backend/dist/

Dockerfile

@@ -0,0 +1,53 @@
+# syntax=docker/dockerfile:1.6
+
+# ---- Stage 1: build the Vue SPA ----
+FROM node:20-alpine AS frontend
+WORKDIR /app
+COPY src/frontend/package*.json ./
+RUN npm ci
+COPY src/frontend ./
+RUN npm run build
+
+# ---- Stage 2: backend runtime, mirrors the local website_c mamba env ----
+FROM mambaorg/micromamba:1.5.10
+
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      build-essential libgl1 libglib2.0-0 git curl ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+USER $MAMBA_USER
+
+# Conda half: Python 3.9, rdkit, boost, cairo, …
+COPY --chown=$MAMBA_USER:$MAMBA_USER environment.yml /tmp/environment.yml
+RUN micromamba install -y -n base -f /tmp/environment.yml \
+    && micromamba clean --all --yes
+ARG MAMBA_DOCKERFILE_ACTIVATE=1
+
+# Pip half: GPU torch (cu118), torch-geometric, Django, DRF, …
+COPY --chown=$MAMBA_USER:$MAMBA_USER src/backend/requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir \
+      --extra-index-url https://download.pytorch.org/whl/cu118 \
+      -r /tmp/requirements.txt
+
+# Application code + research repo + built SPA
+WORKDIR /app
+COPY --chown=$MAMBA_USER:$MAMBA_USER src/backend /app/backend
+COPY --chown=$MAMBA_USER:$MAMBA_USER src/research /app/research
+COPY --chown=$MAMBA_USER:$MAMBA_USER --from=frontend /app/dist /app/backend/dist
+COPY --chown=$MAMBA_USER:$MAMBA_USER entrypoint.sh /entrypoint.sh
+
+# Settings need RESEARCH_ROOT and CHECKPOINTS_ROOT to point at the in-image
+# research tree.  CHECKPOINTS_ROOT lives on a writable path so snapshot_download
+# can populate it at boot.
+ENV RESEARCH_ROOT=/app/research \
+    CHECKPOINTS_ROOT=/app/checkpoints \
+    SPA_DIST_DIR=/app/backend/dist \
+    DJANGO_SETTINGS_MODULE=research_api.settings \
+    PYTHONUNBUFFERED=1 \
+    PORT=7860
+
+WORKDIR /app/backend
+RUN python manage.py collectstatic --noinput
+
+EXPOSE 7860
+ENTRYPOINT ["/usr/local/bin/_entrypoint.sh", "/entrypoint.sh"]

README.md

@@ -0,0 +1,21 @@
+---
+title: Andrej Janchevski - PhD Research
+emoji: 📚
+colorFrom: green
+colorTo: gray
+sdk: docker
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# Andrej Janchevski — PhD Research
+
+Live demos for the PhD thesis _Scalable Knowledge Graph Reasoning and Scalable Graph Generation_ (EPFL, 2025):
+
+- **COINs** — knowledge-graph reasoning (link prediction, multi-hop query answering).
+- **MultiProxAn** — molecular and KG graph generation by diffusion.
+- **KG anomaly correction** — diffusion-based denoising of corrupted knowledge subgraphs.
+
+The Space runs a single Django + Vue Docker container. The backend pulls model checkpoints
+from <https://huggingface.co/bani57/checkpoints> on first boot. Source on GitHub.

docker-compose.yml

@@ -0,0 +1,29 @@
+# Local-dev convenience.  HF Spaces ignores this file and consumes only the
+# Dockerfile.  Run `docker compose up --build` to reproduce the production
+# container locally on http://localhost:7860.
+services:
+  website:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: bani57-website:local
+    ports:
+      - "7860:7860"
+    environment:
+      DJANGO_DEBUG: "False"
+      # Required.  Generate locally with:
+      #   python -c "import secrets; print(secrets.token_urlsafe(50))"
+      # then put it in .env at the repo root (see .env.example).
+      DJANGO_SECRET_KEY: ${DJANGO_SECRET_KEY:?DJANGO_SECRET_KEY must be set in .env or your shell}
+      DJANGO_ALLOWED_HOSTS: ${DJANGO_ALLOWED_HOSTS:-localhost,127.0.0.1}
+      CORS_ALLOWED_ORIGINS: ${CORS_ALLOWED_ORIGINS:-http://localhost:7860}
+      HF_CHECKPOINTS_REPO: ${HF_CHECKPOINTS_REPO:-bani57/checkpoints}
+      HF_TOKEN: ${HF_TOKEN:-}
+      CHECKPOINTS_ROOT: /app/checkpoints
+      TORCH_DEVICE: ${TORCH_DEVICE:-cpu}
+    volumes:
+      # Persist the downloaded checkpoints between runs so we don't re-pull
+      # ~5.4 GB on every `docker compose up`.
+      - checkpoints:/app/checkpoints
+volumes:
+  checkpoints:

entrypoint.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Entry point for the Hugging Face Space container.
+#
+# Pre-warms the checkpoint download from HF Hub before starting gunicorn so
+# that worker processes never block on the network on first request.  The
+# download is idempotent — on warm restarts (with persistent storage) every
+# file is already present and snapshot_download is a no-op.
+set -euo pipefail
+
+: "${HF_CHECKPOINTS_REPO:=bani57/checkpoints}"
+: "${CHECKPOINTS_ROOT:=/app/checkpoints}"
+: "${PORT:=7860}"
+
+mkdir -p "${CHECKPOINTS_ROOT}"
+
+echo "[entrypoint] Pre-warming checkpoints from ${HF_CHECKPOINTS_REPO} -> ${CHECKPOINTS_ROOT}"
+python - <<'PY'
+import os
+from huggingface_hub import snapshot_download
+
+snapshot_download(
+    repo_id=os.environ["HF_CHECKPOINTS_REPO"],
+    repo_type="model",
+    local_dir=os.environ["CHECKPOINTS_ROOT"],
+    local_dir_use_symlinks=False,
+    max_workers=4,
+    token=os.environ.get("HF_TOKEN"),
+)
+print("[entrypoint] checkpoints ready")
+PY
+
+echo "[entrypoint] starting gunicorn on 0.0.0.0:${PORT}"
+exec gunicorn research_api.wsgi:application \
+    --bind "0.0.0.0:${PORT}" \
+    --workers 2 \
+    --threads 2 \
+    --timeout 300 \
+    --access-logfile - \
+    --error-logfile -

environment.yml

@@ -0,0 +1,15 @@
+name: base
+channels:
+  - conda-forge
+dependencies:
+  - python=3.9
+  - rdkit=2023.03.2
+  - boost=1.78
+  - cairo
+  - pycairo
+  - freetype-py
+  - rlpycairo
+  - libblas=*=*mkl
+  - matplotlib=3.7.1
+  - fonttools
+  - pip