Skip to content

Local Development Setup

This guide explains how to set up a local development environment using uv and a virtual environment, with containerized database and cache services.

Overview

This setup provides the best of both worlds:

  • Local Python: Fast execution without container overhead
  • Containerized Services: Reliable database and cache services
  • Native VSCode Integration: Full pytest discovery and coverage

Quick Start

  1. Run the setup script:
./setup_local_dev.sh
  1. Activate the virtual environment:
source .venv/bin/activate

  1. Open VSCode and it will automatically detect the local Python interpreter

  2. Run tests with coverage: 

    pytest tests/ --cov=app --cov-report=xml -v

Architecture

Services

  • Database: PostgreSQL with PostGIS (localhost:2345)
  • Cache: Dragonfly Redis-compatible (localhost:6379)
  • API: Runs locally on localhost:8000

Benefits

  • 🚀 Fast: No container overhead for Python execution
  • 🔧 Simple: Just uv + venv + exposed container services
  • 🧪 Native Testing: Full VSCode pytest integration
  • 📊 Coverage: Real-time coverage feedback
  • 🐛 Debugging: Full local debugging capabilities
  • 🔄 Hot Reload: Instant code changes with uvicorn --reload

Manual Setup

If the setup script fails, you can set up the environment manually:

1. Install Dependencies

# Create virtual environment
uv venv

# Activate it
source .venv/bin/activate

# Install dependencies
uv pip install -e .

2. Start Services

# Start database and cache
docker compose up -d db dragonfly

# Wait for services to be ready
sleep 5

3. Configure Environment

# Copy environment configuration
cp .env.local .env

4. Run Migrations

# Apply database migrations
alembic upgrade head

VSCode Integration

Test Explorer

  1. Open Test Explorer: View → Test Explorer
  2. Run Tests: Click individual tests or "Run All Tests"
  3. Coverage: Automatically generated with each test run

Coverage Display

  1. Install Extension: "Coverage Gutters" by ryanluker
  2. Display Coverage: Command Palette → "Coverage Gutters: Display Coverage"
  3. View Results: Green/red gutters show line coverage

VSCode Tasks

Use Ctrl+Shift+P → "Tasks: Run Task":

  • Setup Local Development Environment: Run the setup script
  • Run Tests with Coverage (Local): Run all tests
  • Run Specific Test File (Local): Run tests for a specific file
  • Run Cache Invalidation Tests (Local): Run cache-specific tests
  • Start Local API Server: Start the API server locally
  • Start Database and Cache Services: Start only the containerized services
  • Stop All Services: Stop all Docker services

Development Workflow

Daily Development

# 1. Activate environment
source .venv/bin/activate

# 2. Start services (if not running)
docker compose up -d db dragonfly

# 3. Run tests
pytest tests/ --cov=app --cov-report=xml -v

# 4. Start API server (optional)
uvicorn app.main:app --reload

Testing Workflow

# Run all tests
pytest tests/ --cov=app --cov-report=xml -v

# Run specific test file
pytest tests/api/routes/test_cache_invalidation.py -v

# Run with coverage and open HTML report
pytest tests/ --cov=app --cov-report=html -v
open htmlcov/index.html

Cache Invalidation Testing

The local setup is specifically configured to work with the cache invalidation fixes:

# Run cache invalidation tests
pytest tests/api/routes/test_cache_invalidation.py -v

# All 14 cache tests should pass:
# ✅ test_brands_cache_invalidation_on_create
# ✅ test_brands_cache_invalidation_on_update
# ✅ test_brands_cache_invalidation_on_delete
# ✅ test_cache_key_generation_consistency
# ✅ test_cache_invalidation_patterns
# ✅ ... and 9 more

Troubleshooting

Services Won't Start

# Check Docker is running
docker info

# Stop any conflicting services
docker compose down

# Restart services
docker compose up -d db dragonfly

Tests Not Discovered in VSCode

# Refresh Python interpreter
# Command Palette → "Python: Select Interpreter"
# Choose: .venv/bin/python

# Refresh tests
# Command Palette → "Python: Refresh Tests"

Coverage Not Showing

# Install Coverage Gutters extension
# Run tests first to generate coverage.xml
pytest tests/ --cov=app --cov-report=xml -v

# Display coverage
# Command Palette → "Coverage Gutters: Display Coverage"

Database Connection Issues

# Check database is running
docker compose ps

# Check connection
docker compose exec db pg_isready -U postgres

# Restart database
docker compose restart db

Stopping Services

# Stop all services
docker compose down

# Or stop specific services
docker compose stop db dragonfly