Dev Environment Setup¶

This page describes how to set up a full local development environment for contributing to SWEN.

Prerequisites¶

1 · Clone and Install¶

git clone https://github.com/maltewinckler/swen.git
cd swen
make install

This runs uv sync (Python workspace: backend + ML + contracts) and npm install (frontend) in one step.

2 · Configure Environment¶

cp config/.env.example config/.env.dev

The example file ships with safe defaults for local development. Only these keys typically need changing:

# If your local Postgres uses a different password
POSTGRES_PASSWORD=postgres
POSTGRES_HOST=localhost

Relaxed security settings are pre-enabled in the example (API_COOKIE_SECURE=false, REGISTRATION_MODE=open).

3 · Start Postgres¶

docker run -d \
  --name swen-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -p 5432:5432 \
  postgres:18-alpine

4 · Initialise the Database¶

make db-init

5 · Install Pre-commit Hooks (recommended)¶

make pre-commit-install

This installs Ruff, detect-secrets, and end-of-file fixers as pre-commit hooks that run before every commit.

6 · Run the Services¶

# Terminal 1 — backend (port 8000, hot-reload)
make backend

# Terminal 2 — frontend (port 5173, Vite HMR)
make frontend

# Terminal 3 — ML service (port 8001, optional)
make ml

Open http://localhost:5173, register (first user = admin), and start exploring.

7 · Load Demo Data (optional)¶

make seed-demo

Creates demo@example.com / demo with ~200 sample transactions.

Running Tests¶

# All tests
make test

# Backend only (unit + integration)
make test-backend

# ML service
make test-ml

# With coverage report
make test-cov

Podman Instead of Docker¶

If you use Podman, export these variables before running integration tests:

export DOCKER_HOST=unix:///run/user/$(id -u)/podman/podman.sock
export TESTCONTAINERS_RYUK_DISABLED=true

Common Issues¶