Local Development

Prerequisites

• Docker and Docker Compose v2+
• Python 3.12+ (for IDE support and local linting)
• Node.js 20+ (for frontend development)

Starting the Dev Stack

The development compose file overlays the production config with hot-reload and a separate Vite dev server:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

This starts three services:

Service	Port	Description
db	5432 (internal)	PostgreSQL 15
app	8000	FastAPI backend with APP_RELOAD=1
frontend	5173	Vite dev server proxying API calls to app:8000

Dev-Specific Overrides

The docker-compose.dev.yml file applies these changes:

• app: Uses scholarr-dev:local image built from the dev stage. Mounts the project root as /app for hot reload. Disables SESSION_COOKIE_SECURE and the built frontend.
• frontend: Node 20 container running npm install && npm run dev. Mounts ./frontend with a named volume for node_modules. Uses polling for file watching (CHOKIDAR_USEPOLLING=1).

Environment Setup

cp .env.example .env

Set at minimum:

POSTGRES_PASSWORD=localdev
SESSION_SECRET_KEY=local-dev-secret-at-least-32-characters
SESSION_COOKIE_SECURE=0

Running Tests

All tests run inside containers:

# Run unit tests (default: excludes integration markers)
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
  python -m pytest

# Run integration tests
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
  python -m pytest -m integration

# Run a specific test file
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
  python -m pytest tests/unit/test_fingerprints.py -v

See Testing for markers, fixtures, and conventions.

Linting and Type Checking

# Ruff linting
ruff check .

# Ruff formatting check
ruff format --check .

# Mypy type checking
mypy app/

Ruff config is in pyproject.toml: target Python 3.12, line length 120, rules E F W I UP B SIM RUF.

Database Migrations

Alembic migrations run automatically on startup when MIGRATE_ON_START=1. To run manually:

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
  alembic upgrade head

To create a new migration:

docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
  alembic revision --autogenerate -m "description of change"