Local development

Prerequisites#

• Python 3.10 or newer.
• Node.js 22 or another version compatible with Next.js 16.
• npm.
• Git.
• Docker Desktop when using the Compose path.

Provider, Clerk, Stripe, OpenAI, and notification accounts are optional unless you test the corresponding integration.

Install the API and engine#

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements-dashboard.txt

Use placeholder-only local environment values. Do not copy production credentials into a tracked file.

Start the API#

For an insecure local-only auth bypass:

export ENV=development
export ALLOW_INSECURE_DEV_AUTH=true
export ALLOW_INSECURE_DEV_CRYPTO=true
export DATABASE_URL=sqlite:///tmp/dashboard.db
uvicorn dashboard.api.main:app --reload --port 8000

The insecure flags are development conveniences. Production guards must set both to false and provide Clerk plus encryption configuration.

Check the API:

curl --fail http://localhost:8000/api/health
curl --fail http://localhost:8000/api/readiness

Start the dashboard#

In a second terminal:

cd dashboard/web
npm ci
NEXT_PUBLIC_API_URL=http://localhost:8000 npm run dev

Open http://localhost:3000. A full authenticated flow requires Clerk keys. The repository’s test-only auth bypass is restricted so a deployed production app cannot enable it through E2E_AUTH_BYPASS alone.

Docker Compose#

The development Compose file starts the API and web services and persists API runtime data in a named volume:

docker compose up --build

Review all environment defaults before allowing the containers to reach a real board.