Local development setup

Quick start

./setup.sh          # installs backend + frontend deps
cp .env.example .env
./start.sh          # backend :5001, frontend :3000

Raptor database (backend_v2)

Raptor (the backend_v2 Flask app) is migrating from SQLite to Postgres as part of the v1 launch milestone. Postgres is optional for local development. The database layer falls back to SQLite automatically when DATABASE_URL is not set.

Default (no DATABASE_URL set)

DATABASE_URL=sqlite+pysqlite:///./dev.db

This is the implicit default. You do not need to export the variable — if it is absent, Raptor creates dev.db in the project root and applies all SQLite migrations. No Postgres server required.

Run against a local Postgres

If you want to test against Postgres locally, install Postgres, create a database, and export:

DATABASE_URL=postgresql://localhost/raptor_dev

Then apply the Alembic baseline migration:

cd backend_v2
alembic upgrade head

Explicit SQLite URL (for test fixtures)

DATABASE_URL=sqlite+pysqlite:///./test.db

This form is used by some test fixtures to isolate test state from dev.db.

ARM / Apple Silicon note

psycopg2-binary ships ARM wheels for >=2.9 (the pinned floor). If you encounter a build failure on ARM, install the non-binary package with system libpq instead:

brew install libpq
pip install psycopg2

Alembic commands

Run these from backend_v2/ where alembic.ini lives.

Staging / prod cutover: DATABASE_URL on Heroku is set via heroku config:set (append >/dev/null 2>&1 to avoid echoing the URL to logs). The release dyno runs alembic upgrade head automatically. No Postgres URL ever appears in committed source files.