100 lines
2.5 KiB
Markdown
100 lines
2.5 KiB
Markdown
---
|
|
title: Local Development
|
|
sidebar_position: 3
|
|
---
|
|
|
|
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Set at minimum:
|
|
|
|
```bash
|
|
POSTGRES_PASSWORD=localdev
|
|
SESSION_SECRET_KEY=local-dev-secret-at-least-32-characters
|
|
SESSION_COOKIE_SECURE=0
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
All tests run inside containers:
|
|
|
|
```bash
|
|
# 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](testing.md) for markers, fixtures, and conventions.
|
|
|
|
## Linting and Type Checking
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
|
|
alembic upgrade head
|
|
```
|
|
|
|
To create a new migration:
|
|
|
|
```bash
|
|
docker compose -f docker-compose.yml -f docker-compose.dev.yml run --rm app \
|
|
alembic revision --autogenerate -m "description of change"
|
|
```
|