spacescans-web

Web app for the SPACESCANS EHR ↔ environmental-exposure linkage pipeline: upload a patient cohort CSV, pick exposure variables, run the pipeline, and explore the results.

The same setup runs on macOS, Windows, and Linux — everything runs inside Docker containers, so there is nothing OS-specific to configure.

---

Quick start

The only thing you install yourself is Docker — Docker Desktop on macOS/Windows, Docker Engine on Linux.

Docker Desktop users (macOS/Windows): give the Docker VM enough memory — Settings → Resources → Memory ≥ 12 GB. The pipeline works on multi-GB geodata inside the VM; at the ~8 GB default a large run can get OOM-killed. Linux needs no setting — containers see all host RAM.

git clone https://github.com/IU-Ultraman/spacescans-web.git
cd spacescans-web
cp .env.docker.example .env      # then set SECRET_KEY — see step 1
docker compose up --build        # first build takes a few minutes

Then open http://localhost:3000 and sign up to create an account.

The app runs without any exposure data. To add a dataset, run one command from this directory — it downloads from the deployer's shared folder, verifies the checksum and extracts it into pipeline-data/:

scripts/fetch_distribution.sh --list                       # what's available
scripts/fetch_distribution.sh tract_boundaries_v1.tar.gz   # one dataset
scripts/fetch_distribution.sh --small                      # everything except Bluespace
                                                           # (7 variables, 8.5 GB on disk)

The script wraps python -m spacescans data fetch (resumable downloads, SHA-256 checks from the package's data manifest), so it needs a Python with the spacescans package installed; set SPACESCANS_PYTHON to point at one (scripts/fetch_distribution.sh --help has the install line). Without one, run the same command in the backend container, which has the package and the data root at /project: docker compose exec backend /opt/conda/bin/python -m spacescans data fetch --data-dir /project --dataset tract_boundaries.

Add only what the variables you plan to run need — the in-app Data Setup page shows the command for each variable, and takes archive uploads if you would rather not use a terminal. Datasets whose licenses forbid redistribution (VNL, TEMIS) are listed there with their original download sites. See pipeline-data/README.md for the full layout.

---

1. Configure

cp .env.docker.example .env

Then set SECRET_KEY in .env to a random value. Generate one with:

openssl rand -hex 32

Open .env and replace the placeholder with the generated value:

SECRET_KEY=<paste the generated value here>

Skipping this is fine for local testing — defaults apply — but set a real secret for anything else.

---

2. Run

docker compose up --build

• Frontend → http://localhost:3000
• Backend → http://localhost:8000

The first build downloads ~1.5 GB of dependencies and takes a few minutes; later runs are cached and fast. Open the frontend and sign up to create an account.

docker compose down              # stop
docker compose down -v           # stop + also delete accounts/tasks/cache
docker compose logs -f backend   # follow backend logs

---

License

spacescans-web is released under the MIT License (LICENSE), like the spacescans package it runs. The license covers the software only: each catalog source keeps its provider's terms (the Data Setup page lists them), and a dataset a user registers keeps the terms of its source, which its owner is responsible for before sharing it with the deployment.