Local development setup

For the hosted platform, open brainmaps.xyz. For data-processing tools, follow CLI installation. This page is for developing the platform locally.

Start from a BrainMaps superproject checkout with its component repositories available. Repository access may require authorization from a maintainer. Commands below run from the superproject root unless stated otherwise.

API

Use Python 3.11 and uv with the API’s existing requirements file:

cd brainmaps-api
uv venv --python 3.11
uv pip install -r requirements.txt

Set these environment variables in the terminal running the API. The current settings module does not automatically load a .env file:

export DEBUG=True
export DJANGO_SECRET_KEY=replace-with-a-local-development-secret
export DATABASE_URL=sqlite:///db.sqlite3
export ALLOWED_HOSTS=localhost,127.0.0.1
export FRONTEND_URL=http://localhost:3200

uv run python manage.py migrate
uv run python manage.py createsuperuser
uv run python manage.py runserver

The API is at http://localhost:8000/api/; the health endpoint is http://localhost:8000/health/. Django administration is at /admin/. Source code lives in core/, not src/.

Object-storage uploads also require the server’s storage configuration. Coordinate this with the maintainer; a local SQLite setup alone does not provision a bucket or signed upload credentials.

Website

In another terminal, from the superproject root:

cd brainmaps-front
pnpm install
VITE_API_URL=http://localhost:8000 pnpm dev

The current package script starts Vite on port 3200. Check the printed URL if that port is occupied. Set the API URL explicitly when developing locally so requests do not fall back to production.

Documentation

cd brainmaps-docs
bun install --frozen-lockfile
bun run dev

Docs use Next.js and Nextra, normally on port 3000. Edit content in pages/; navigation is defined by each directory’s _meta.ts.

Validate changes

Run the checks for the component you changed:

The API also has a Docker Compose setup. Use docker compose and the service name api, not web. Review the checked-out Compose file and its sibling-project paths before starting it; it can include the database, proxy, monitoring and other services.