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.
