Installation¶

This guide walks you through installing litestar-pydotorg for local development.

Install uv¶

uv is a fast Python package manager that we use for dependency management.

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew

brew install uv

Verify the installation:

uv --version

Clone the Repository¶

git clone https://github.com/JacobCoffee/litestar-pydotorg.git
cd litestar-pydotorg

Set Up Python Environment¶

Create and activate a virtual environment:

# Create virtual environment with uv
uv venv

# Activate virtual environment
# macOS/Linux
source .venv/bin/activate

# Windows
.venv\Scripts\activate

Install dependencies:

# Install all dependencies (production + development)
uv pip install -e ".[dev]"

Or use the Makefile:

make install

Configure Environment¶

Copy the example environment file and configure your settings:

cp .env.example .env

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

# Database connection
DATABASE_URL=postgresql+asyncpg://postgres:postgres@localhost:5432/pydotorg

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

# Secret key (generate a secure one)
SECRET_KEY=your-secure-secret-key-here

# Debug mode (enable for development)
DEBUG=true

Generate a secure secret key:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Start Infrastructure Services¶

Option 1: Docker Compose (Recommended)¶

Start PostgreSQL and Redis using Docker Compose:

# Start all infrastructure services
make infra-up

# Or manually:
docker-compose up -d postgres redis

Verify services are running:

docker-compose ps

Option 2: Local Installation¶

If you prefer to install services locally:

PostgreSQL¶

macOS (Homebrew)

brew install postgresql@15
brew services start postgresql@15
createdb pydotorg

Ubuntu/Debian

sudo apt install postgresql-15
sudo systemctl start postgresql
sudo -u postgres createdb pydotorg

Redis¶

macOS (Homebrew)

brew install redis
brew services start redis

Ubuntu/Debian

sudo apt install redis-server
sudo systemctl start redis

Database Setup¶

Run database migrations:

# Using Makefile
make litestar-db-upgrade

# Or directly with Litestar CLI
LITESTAR_APP=pydotorg.main:app uv run litestar database upgrade

Optionally seed development data:

make db-seed

Verify Installation¶

Start the development server:

make serve

# Or directly:
LITESTAR_APP=pydotorg.main:app uv run litestar run --reload

Visit http://localhost:8000 in your browser.

Check the API documentation at:

Scalar UI: http://localhost:8000/api/
Swagger UI: http://localhost:8000/api/swagger
ReDoc: http://localhost:8000/api/redoc

Frontend Assets¶

Install frontend dependencies and start the asset watcher:

# Install frontend dependencies
make assets-install

# Start Vite dev server with hot module replacement
make assets-serve

Or in a separate terminal while the backend is running:

make frontend

Common Issues¶

Database Connection Failed¶

Ensure PostgreSQL is running and the connection string is correct:

# Check PostgreSQL is running
docker-compose ps postgres

# Test connection
psql $DATABASE_URL -c "SELECT 1"

Redis Connection Failed¶

Verify Redis is running:

# Check Redis is running
docker-compose ps redis

# Test connection
redis-cli -u $REDIS_URL ping

Import Errors¶

Reinstall dependencies:

uv pip install -e ".[dev]" --force-reinstall

# Clear Python cache
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -type f -name "*.pyc" -delete

Port Already in Use¶

If port 8000 is in use:

# Find the process using the port
lsof -i :8000

# Use a different port
LITESTAR_APP=pydotorg.main:app uv run litestar run --port 8001

Next Steps¶

Continue to the Quickstart to start developing
Read the Architecture Overview to understand the codebase structure
Check the Development Guide for coding standards and workflows