Local Dev Stack

How to bring up the substrate, Prism, and dependencies on a workstation.

Source: docs/dev/dev-stack.md

Dev Stack: One-Command Local Boot

make dev-stack is the single command a fresh operator runs after git clone to get a working SciDEX (substrate + Prism) talking to a seeded local Postgres. It collapses what used to be 12+ manual steps into one target that exits when both services have reported ready.

Usage

make dev-stack          # bring the whole stack up
make dev-stack-status   # report which processes are alive
make dev-stack-down     # tear it down

What it does

  1. Creates the Postgres database scidex_v2_dev if it doesn’t exist (no-op via createdb swallowing errors so re-runs are safe).

  2. Applies all migrations via python -m scidex_substrate.cli schema apply (the in-package migration runner — same code path CI uses).

  3. Seeds demo content via tools.seed.first_visitor_demo_seed --apply (idempotent — re-runs report “already present”).

  4. Clones SciDEX-AI/scidex-prism into /tmp/scidex-prism-dev if absent, then runs npm install --legacy-peer-deps if node_modules/ is missing.

  5. Boots substrate on 127.0.0.1:18200 in the background, writes PID to /tmp/scidex-substrate-dev.pid and stdout/stderr to /tmp/scidex-substrate-dev.log.

  6. Polls GET /v1/readiness for up to 30 seconds.

  7. Boots Prism (SvelteKit dev server) on 127.0.0.1:13200 with SCIDEX_SUBSTRATE_URL wired to the substrate port, PID to /tmp/scidex-prism-dev.pid and stdout/stderr to /tmp/scidex-prism-dev.log.

  8. Polls GET / for up to 60 seconds.

  9. Prints the URLs and an open http://localhost:13200/start hint.

Customization

Override defaults via env vars on the make invocation:

Var Default Purpose
DEV_DSN postgresql://localhost/scidex_v2_dev DB used for migrations + seed + substrate process
SUBSTRATE_PORT 18200 Port substrate listens on
PRISM_PORT 13200 Port Prism dev server listens on
PRISM_DIR /tmp/scidex-prism-dev Filesystem location of the Prism checkout

Example: boot against an existing dev DB on a non-default port pair:

make dev-stack \
  DEV_DSN=postgresql:///my_scidex_dev \
  SUBSTRATE_PORT=18300 \
  PRISM_PORT=13300

Pre-requisites

The target assumes the operator has installed:

  • Postgres running locally (default socket; trust auth or ~/.pgpass configured).

  • Node ≥ 18 for the Prism dev server.

  • Python ≥ 3.10 with the substrate package installed in editable mode (pip install -e ".[dev]").

  • gh CLI authenticated, so Prism can be cloned on first run.

Anything missing surfaces as a clear error at the corresponding step; no silent failure.

Tear-down

make dev-stack-down

Kills both processes via the PID files and removes the PID files. Database state (the scidex_v2_dev DB and its seeded rows) is left intact so the next make dev-stack is a fast re-boot rather than a re-seed. Drop the DB manually if you want a fully clean re-run:

make dev-stack-down
dropdb scidex_v2_dev
make dev-stack

Status

make dev-stack-status

Reports running (PID …) / stale pid file / not started for each service. A stale PID file is left behind if a process was killed externally (e.g. kill -9, OOM, reboot) — re-running make dev-stack overwrites it.

Manual test procedure

Because the target depends on actual Postgres + Node + a network for the Prism clone, automated CI cannot run the full target. The substitutes:

  1. tests/integration/dev_stack/test_dev_stack.py checks that make -n dev-stack parses cleanly — catches Makefile-syntax regressions.

  2. Operator manual smoke (one-time after merge):

    make dev-stack-down 2>/dev/null  # clean slate
dropdb scidex_v2_dev 2>/dev/null
rm -rf /tmp/scidex-prism-dev

time make dev-stack
# Expect: substrate ready in ~10s, Prism ready in ~30s

curl -sf http://localhost:18200/v1/readiness | head -3
curl -sf http://localhost:13200/ | head -3

make dev-stack-status   # both running
make dev-stack-down
make dev-stack-status   # both not started

Why these defaults

  • Port 18200 / 13200 match tools/test/cross_repo_smoke.sh defaults so an operator already familiar with cross-repo smoke sees the same numbers.

  • DB name scidex_v2_dev stays distinct from scidex_v2 (CI/local-test DB) and scidex_v2_smoke (cross-repo smoke DB) so the dev stack can coexist with both.

  • /tmp/scidex-prism-dev sits outside the substrate checkout so a git clean -fdx on substrate doesn’t blow away Prism’s node_modules/.

  • Background + PID file rather than tmux / systemd so the target works in any shell environment, including headless CI sandboxes that already happen to have Postgres + Node.