Installation¶

This guide covers setting up the LMS development environment from scratch.

Prerequisites¶

Dependency	Version	Purpose
Python	3.13+	Backend runtime
PostgreSQL	16+	Database (schema-per-tenant)
Redis	7+	Celery broker and result backend
Node.js	20+	Frontend build tooling
npm	10+	Frontend package manager
uv	Latest	Python package manager

Clone the Repository¶

git clone https://github.com/lendsimple/lms.git
cd lms

Backend Setup¶

Install Dependencies¶

cd backend
uv sync --extra dev

This installs all Python dependencies including dev tools (pytest, ruff, mypy).

Note

uv sync alone won't install dev tools. The --extra dev flag (or --group dev) is required for pytest, ruff, mypy, and other development dependencies.

Configure Environment¶

cp .env.example .env

Edit .env with your local settings. At minimum, configure:

# Database
DATABASE_URL=postgres://user:password@localhost:5432/lms

# Redis
REDIS_URL=redis://localhost:6379/0

# Django
SECRET_KEY=your-secret-key-here
DEBUG=True
ALLOWED_HOSTS=localhost,127.0.0.1

# Provider encryption (generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())")
PROVIDER_ENCRYPTION_KEY=your-fernet-key-here

See Configuration for all available settings.

Create Database¶

createdb lms

Run Migrations¶

uv run python manage.py migrateschema -as

This runs migrations across all schemas (public, main, and any existing tenant schemas). See Multi-Tenancy for details on the three-schema model.

Start the Dev Server¶

uv run python manage.py runserver

The backend API is available at http://localhost:8000/api/v1/docs (OpenAPI documentation).

Frontend Setup¶

Admin Dashboard¶

cd frontend/admin
npm install
npm run dev

The admin dashboard is available at http://localhost:5173.

Borrower Portal¶

cd frontend/borrower
npm install
npm run dev

The borrower portal is available at http://localhost:5174.

Docker Compose (Alternative)¶

For a complete environment with all services:

docker compose up

This starts:

Service	Port	Purpose
`db`	5432	PostgreSQL 16
`redis`	6379	Redis 7
`backend`	8000	Django ASGI (uvicorn)
`celery-worker`	---	Celery worker
`celery-beat`	---	Celery beat scheduler
`frontend`	5173	Admin dashboard (Vite)
`portal`	5174	Borrower portal (Vite)

Verification¶

Run Backend Tests¶

cd backend
uv run pytest

All 1200+ tests should pass.

Run Frontend Tests¶

cd frontend/admin
npm run test

cd frontend/borrower
npm run test

Lint and Type Check¶

cd backend
uv run ruff check .          # Lint
uv run ruff format --check . # Format check
uv run mypy .                # Type check

Documentation¶

cd docs
uv sync
uv run mkdocs serve

The documentation site is available at http://127.0.0.1:8000/.