Skip to content

Development Environment with VSCode Debugging

This guide explains how to use the Docker development environment with VSCode debugging capabilities.

Alternative Setup Available

For a simpler, faster local development setup using uv and venv, see the Local Development Setup guide.

Features

  • Full development environment with all dependencies installed
  • Live code reloading with uvicorn --reload
  • Remote debugging with VSCode
  • Mounts the entire project directory for easy development
  • Runs on a different port (8100) to avoid conflicts with the main API service

Getting Started

1. Start the Development Container

# Using environment variable
export COMPOSE_PROFILES=dev
docker compose up

# Or using --profile flag
docker compose --profile dev up

# Or inline
COMPOSE_PROFILES=dev docker compose up

This will start the development containers and wait for a debugger to attach.

2. Attach the VSCode Debugger

  1. Open the project in VSCode
  2. Go to the "Run and Debug" view (Ctrl+Shift+D or Cmd+Shift+D on macOS)
  3. Select "Python: Remote Attach" from the dropdown menu
  4. Click the green play button or press F5

VSCode will attach to the running container, and the application will start.

3. Set Breakpoints and Debug

You can now set breakpoints in your code and debug as usual. When you make changes to the code, the application will automatically reload thanks to the --reload flag.

Configuration

The development environment is configured in the following files:

  • build/dev/Dockerfile: The Dockerfile for the development environment
  • build/dev/entrypoint.sh: The entrypoint script that starts the application with debugging enabled
  • .vscode/launch.json: The VSCode launch configuration for attaching to the debugger
  • compose.yml: The Docker Compose configuration with development profile

Python Frozen Modules

The development environment uses the -Xfrozen_modules=off flag when starting Python. This is necessary to ensure that the debugger can properly set breakpoints in frozen modules. Without this flag, you might find that some breakpoints are not hit during debugging.

Ports

  • 8100: The application port (mapped to 8000 inside the container)
  • 5678: The debug port

Volumes

The entire project directory is mounted at /app in the container, so any changes you make to the code will be immediately available inside the container.