Skip to content

Development Environment with VSCode Debugging

This guide explains how to attach VSCode to the Docker-based development environment.

The normal workflow is to run the development services from compose.yml, then attach the debugger to the API container when you need breakpoints.

Features

  • Docker Compose-backed dev environment
  • Live code reloading with uvicorn --reload
  • Remote debugging with VSCode and debugpy
  • Bind mounts for fast code iteration
  • API exposed on port 8100 for local development

For the full setup flow, see the Installation Guide.

Getting Started

1. Start the Development Stack

docker compose up -d

This starts the API, admin panel, frontend, database, cache, and worker services.

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 API container. If DEBUG_WAIT_FOR_CLIENT=true is set, the app waits for the debugger before starting Uvicorn.

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 automatically reloads thanks to the --reload flag.

Configuration

The development environment is configured in the following files:

  • compose.yml: The Docker Compose services and volumes for development
  • build/dev/Dockerfile: The API development image
  • build/dev/entrypoint.sh: The startup script that launches Uvicorn through debugpy
  • .vscode/launch.json: The VSCode launch configuration for remote attach

Python Frozen Modules

The development environment uses the -Xfrozen_modules=off flag when starting Python. This helps VSCode set breakpoints reliably inside the container.

Ports

  • 8100: The API port exposed by the development stack
  • 5678: The debug port

Volumes

The project directory is mounted into the container, so any changes you make to the code are immediately available inside the running services.