Skip to main content

DevContainer Setup

Complete guide to using VS Code DevContainers for isolated, consistent development environments.

What is DevContainer?​

DevContainer provides a fully configured development environment inside a Docker container:

✅ Python 3.11 pre-installed
✅ All dependencies auto-installed via uv sync
✅ PostgreSQL and Redis services
✅ VS Code extensions pre-configured
✅ Consistent environment across team

Prerequisites​

Required​

  • Docker Desktop - Must be running
  • VS Code - Latest version
  • Dev Containers Extension - Install from VS Code marketplace

Install Dev Containers Extension​

  1. Open VS Code
  2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)
  3. Search for "Dev Containers"
  4. Install extension by Microsoft

Setup Instructions​

1. Clone Repository​

git clone https://github.com/equalcollective/santra-be.git
cd santra-be

2. Configure Environment​

# Copy environment template
cp .env.example .env

Edit .env with required values:

SECRET_KEY=your-secret-key-here
AZURE_STORAGE_CONNECTION_STRING=your-connection-string
AZURE_STORAGE_CONTAINER_NAME=report-uploads

3. Open in Container​

Option 1: Command Palette

  1. Open project in VS Code
  2. Press F1 or Ctrl+Shift+P
  3. Type: "Dev Containers: Reopen in Container"
  4. Select and wait for build (2-3 minutes first time)

Option 2: Notification

  1. VS Code will show notification: "Folder contains a Dev Container configuration file"
  2. Click "Reopen in Container"

Option 3: Status Bar

  1. Click the remote indicator in bottom-left corner (><)
  2. Select "Reopen in Container"

4. Wait for Build​

First time setup:

  • Pulls base images (~500MB)
  • Installs system dependencies
  • Runs uv sync for Python packages
  • Takes 2-3 minutes

Subsequent opens: < 30 seconds

5. Run Database Migrations​

Once inside the container:

# Apply migrations
uv run alembic upgrade head

6. Start the API​

# Start FastAPI with auto-reload
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

API available at: http://localhost:8000

What's Included​

Services​

All running automatically inside container network:

ServiceHostPortPurpose
applocalhost8000FastAPI application
dbdb5432PostgreSQL 15
redisredis6379Cache & Celery

VS Code Extensions​

Pre-installed extensions:

  • Python - Full Python language support
  • Ruff - Fast Python linter and formatter
  • Even Better TOML - TOML file support

Python Environment​

  • Python 3.11
  • uv package manager
  • Virtual environment at /workspace/.venv
  • All dependencies from pyproject.toml

Database Configuration​

Environment variables automatically set:

DATABASE_URL=postgresql://orange_user:orange_password@db:5432/orange_db
REDIS_URL=redis://redis:6379/0

Working Inside Container​

Terminal Access​

Open integrated terminal (Ctrl+~`):

  • Already inside the container
  • Virtual environment activated
  • All tools available (uv, alembic, pytest)

Running Commands​

# Start API
uv run uvicorn app.main:app --reload

# Start Celery worker
uv run celery -A app.celery_app worker --loglevel=info

# Run migrations
uv run alembic upgrade head

# Create migration
uv run alembic revision --autogenerate -m "description"

Accessing Services​

PostgreSQL:

# Via psql
psql postgresql://orange_user:orange_password@db:5432/orange_db

# Via Docker Compose
docker compose exec db psql -U orange_user -d orange_db

Redis:

# Test connection
redis-cli -h redis ping

File Editing​

Edit files normally in VS Code:

  • Files are mounted from host → container
  • Changes sync instantly
  • Git operations work on host files

Next Steps​