Development Environment¶

Complete setup for local development.

Package Manager (uv)¶

This project uses uv for dependency management. Install it:

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

# Or with pip
pip install uv

Common Commands¶

# Install all dependencies
uv sync --locked --all-extras --dev

# Add a new dependency
uv add package-name

# Add a dev dependency
uv add --dev package-name

# Update lockfile
uv lock

Infrastructure Services¶

The application requires PostgreSQL, Redis, and MinIO. Use Docker Compose for local development.

COMPOSE_FILE

The .env.example includes COMPOSE_FILE=docker-compose.yaml:docker-compose.local.yaml which automatically configures Docker Compose for local development. Copy it to .env before running commands.

# Start PostgreSQL, Redis, and MinIO
docker compose up -d postgres redis minio

# Create MinIO buckets, run migrations, and collect static files
docker compose up minio-create-buckets migrations collectstatic

# View logs
docker compose logs -f postgres redis minio

# Stop services
docker compose down

# Stop and remove volumes (reset data)
docker compose down -v

Service Ports¶

Service	Port	Description
PostgreSQL	5432	Database
Redis	6379	Cache/Broker
MinIO API	9000	S3-compatible storage
MinIO Console	9001	Web UI

Running the Application¶

HTTP API¶

make dev

The server runs at http://localhost:8000 with hot reload enabled.

Celery Worker¶

make celery-dev

Runs with debug logging and auto-restart on file changes.

Celery Beat (Scheduler)¶

make celery-beat-dev

Telegram Bot¶

make bot-dev

Requires TELEGRAM_BOT_TOKEN in .env.

Code Quality¶

Formatting¶

make format

Uses Ruff for formatting and import sorting.

Linting¶

make lint

Runs multiple linters:

ruff — Fast Python linter
ty — Type checker
pyrefly — Type checker
mypy — Type checker

Why three type checkers? Each tool has different strengths:

ty — Extremely fast, catches common type errors quickly during development
pyrefly — Meta's type checker with unique inference capabilities for complex patterns
mypy — The ecosystem standard with the most mature plugin support (e.g., Django stubs)

Running all three ensures comprehensive coverage. Since ty and pyrefly are very fast, the performance overhead is minimal.

Testing¶

make test

Runs pytest with 80% coverage requirement.

IDE Configuration¶

VS Code¶

Recommended extensions:

Python (Microsoft)
Ruff
Pylance

Settings (.vscode/settings.json):

{
    "python.defaultInterpreterPath": ".venv/bin/python",
    "python.analysis.typeCheckingMode": "basic",
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.organizeImports": "explicit"
        }
    }
}

PyCharm¶

Set interpreter to .venv/bin/python
Enable Ruff plugin
Configure Ruff as the formatter:
Settings → Tools → Ruff → Enable "Format on save"

Database Operations¶

Create Migrations¶

make makemigrations

Apply Migrations¶

make migrate

Django Shell¶

uv run manage.py shell

Create Superuser¶

uv run manage.py createsuperuser

Environment Variables¶

The application uses .env for local development. See Environment Variables Reference for all options.

Test Environment¶

Tests use .env.test which is automatically loaded by pytest:

# .env.test
DATABASE_URL="postgres://postgres:test@localhost:5432/test_db"

Troubleshooting¶

Database Connection Failed¶

django.db.utils.OperationalError: could not connect to server

Ensure PostgreSQL is running:

docker compose ps postgres
docker compose logs postgres

Redis Connection Failed¶

redis.exceptions.ConnectionError: Error connecting to localhost:6379

Ensure Redis is running:

docker compose ps redis
docker compose logs redis

Import Errors After Adding Dependencies¶

Restart your IDE's Python language server or run:

uv sync --locked --all-extras --dev