Development Setup¶

Run LightningROD locally outside of Docker for development, with hot-reload and direct database access.

Prerequisites¶

Python 3.11+
uv -- fast Python package manager
Docker -- for PostgreSQL

Steps¶

1. Install dependencies¶

git clone https://github.com/yourusername/LightningROD.git
cd LightningROD
uv sync

2. Configure environment¶

cp .env.example .env

The defaults work for local development. No changes needed unless you want different database credentials.

3. Start PostgreSQL¶

The dev compose override exposes PostgreSQL on port 5432 so you can connect with local tools, and keeps the web service from starting (you'll run it locally instead):

docker-compose.dev.yml

# Usage: docker compose -f docker-compose.yml -f docker-compose.dev.yml up db
services:
  web:
    profiles: ["prod"]
  db:
    ports:
      - "5432:5432"

docker compose -f docker-compose.yml -f docker-compose.dev.yml up db -d

4. Run migrations¶

uv run alembic upgrade head

5. Seed data (optional)¶

uv run python scripts/seed.py --vin YOUR_VIN_HERE

6. Start the dev server¶

uv run uvicorn web.main:app --reload --port 8000

Open http://localhost:8000. The server auto-reloads when you change Python files.

Creating Migrations¶

When you modify a model in db/models/, create a migration:

# Auto-generate from model changes
uv run alembic revision --autogenerate -m "description of change"

# Apply it
uv run alembic upgrade head

Warning

Autogenerate requires a running database to diff against. If the database isn't running, you can write migrations manually -- see the existing migrations in db/migrations/versions/ for examples.

Running Tests¶

uv run pytest

Linting¶

uv run ruff check .
uv run ruff format .

Connecting to the Database¶

With the dev compose stack running, PostgreSQL is available at localhost:5432:

# psql
psql -h localhost -U lightningrod -d lightningrod

# Or use any GUI tool (pgAdmin, DBeaver, etc.)