Update debugging support for Django and Celery (#1048)

* feat: add debugpy debugging support for Django and Celery

Use docker-compose override file pattern for enabling remote debugging
with debugpy in VS Code. Supports debugging the main Django app and
Celery workers independently or simultaneously.

Changes:
- Update docker-compose.yml to use /start-celeryworker script
- Add docker-compose.override.yml.example to enable debuggers
- Update start scripts to look for DEBUGGER environment variable
- Add debugger config for main Django app in addition to Celery workers

* chore: add pipefail option to celery worker start as well

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* fix: ensure celeryworker doesn't reuse django ports

* feat: allow auto reload for celery worker even with debugger

* chore: comments & cleanup

* chore: rename example file so that linting works

* feat: allow debugger to work properly with Django

* chore: remove redundant launch config

* chore: don't auto reload celery worker

* chore: make script volume mount options consistent

Author: mihow

.agents/AGENTS.md

@@ -66,6 +66,35 @@ Stop all services:
 docker compose down
 ```
 
+### Debugging with VS Code
+
+Enable remote debugging with debugpy for Django and Celery services:
+
+```bash
+# One-time setup: copy the override example file
+cp docker-compose.override-example.yml docker-compose.override.yml
+
+# Start services (debugpy will be enabled automatically)
+docker compose up
+
+# In VS Code, attach debugger:
+# - "Attach: Django" for web server debugging (port 5678)
+# - "Attach: Celeryworker" for task debugging (port 5679)
+# - "Attach: Django + Celery" for simultaneous debugging
+```
+
+**How it works:**
+- The `docker-compose.override.yml` file sets `DEBUGGER=1` environment variable
+- Start scripts (`compose/local/django/start` and `compose/local/django/celery/worker/start`) detect this and launch with debugpy
+- VS Code launch configurations in `.vscode/launch.json` connect to the exposed ports
+- The override file is git-ignored for local customization
+
+**Disable debugging:**
+```bash
+rm docker-compose.override.yml
+docker compose restart django celeryworker
+```
+
 ### Backend (Django)
 
 Run tests:

.gitignore

@@ -277,5 +277,8 @@ sandbox/
 # Other
 flower
 
+# Docker Compose override for local debugging (copy from .example file)
+docker-compose.override.yml
+
 # Temporary files in current work session
 .agents/todo

.vscode/launch.json

@@ -1,8 +1,15 @@
 {
     "version": "0.2.0",
+    "compounds": [
+        {
+            "name": "Attach: Django + Celery",
+            "configurations": ["Attach: Django", "Attach: Celeryworker"],
+            "stopAll": true
+        }
+    ],
     "configurations": [
         {
-            "name": "Python Debugger: Remote Attach",
+            "name": "Attach: Django",
             "type": "debugpy",
             "request": "attach",
             "connect": {
@@ -12,9 +19,26 @@
             "pathMappings": [
                 {
                     "localRoot": "${workspaceFolder}",
-                    "remoteRoot": "."
+                    "remoteRoot": "/app"
+                }
+            ],
+            "justMyCode": true
+        },
+        {
+            "name": "Attach: Celeryworker",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5679
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}",
+                    "remoteRoot": "/app"
                 }
-            ]
+            ],
+            "justMyCode": true
         }
     ]
 }

README.md

@@ -258,3 +258,50 @@ The local environment uses a local PostgreSQL database in a Docker container.
 ### Load fixtures with test data
 
     docker compose run --rm django python manage.py migrate
+
+## Debugging with VS Code
+
+Antenna supports remote debugging with debugpy for both Django and Celery services.
+
+### Setup
+
+1. Copy or link the override example file:
+   ```bash
+   cp docker-compose.override-example.yml docker-compose.override.yml
+   # OR
+   ln -s docker-compose.override-example.yml docker-compose.override.yml
+   ```
+
+2. Start services normally:
+   ```bash
+   docker compose up
+   ```
+
+3. In VS Code, open the Debug panel (Ctrl+Shift+D) and select one of:
+   - **Attach: Django** - Debug the Django web server (port 5678)
+   - **Attach: Celeryworker** - Debug the Celery worker (port 5679)
+   - **Attach: Django + Celery** - Debug both simultaneously
+
+4. Click the green play button or press F5 to attach the debugger
+
+### Setting Breakpoints
+
+- Set breakpoints in your Python code by clicking in the left margin of the editor
+- When the code executes, the debugger will pause at your breakpoints
+- Use the Debug Console to inspect variables and execute expressions
+
+### Troubleshooting
+
+- **Connection refused**: Make sure you copied `docker-compose.override-example.yml` to `docker-compose.override.yml`
+- **Debugger not stopping**: Verify breakpoints are set in code that actually executes
+- **Port conflicts**: Check that ports 5678 and 5679 aren't already in use on your host machine
+- **Auto-reload**: Note that auto-reloading is disabled when debugging. You will need to manually restart the services to see code changes.
+
+### Disabling Debug Mode
+
+To disable debugging and return to normal operation:
+
+```bash
+rm docker-compose.override.yml
+docker compose restart django celeryworker
+```

compose/local/django/celery/worker/start

@@ -1,7 +1,14 @@
 #!/bin/bash
 
 set -o errexit
+set -o pipefail
 set -o nounset
 
-
-exec watchfiles --filter python celery.__main__.main --args '-A config.celery_app worker -l INFO'
+# Launch VS Code debug server if DEBUGGER environment variable is set to 1
+# Note that auto reloading is disabled when debugging, manual restart required for code changes.
+if [ "${DEBUGGER:-0}" = "1" ]; then
+    # exec watchfiles --filter python 'python -m debugpy --listen 0.0.0.0:5679 -m celery -A config.celery_app worker -l INFO'
+    exec python -Xfrozen_modules=off -m debugpy --listen 0.0.0.0:5679 -m celery -A config.celery_app worker -l INFO
+else
+    exec watchfiles --filter python celery.__main__.main --args '-A config.celery_app worker -l INFO'
+fi

compose/local/django/start

@@ -4,6 +4,12 @@ set -o errexit
 set -o pipefail
 set -o nounset
 
-
 python manage.py migrate
-exec uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include '*.html'
+
+# Launch VS Code debug server if DEBUGGER environment variable is set to 1
+# Note that the --reload flag is not compatible with debugpy, so manually restart the server when code changes
+if [ "${DEBUGGER:-0}" = "1" ]; then
+    exec python -Xfrozen_modules=off -m debugpy --listen 0.0.0.0:5678 -m uvicorn config.asgi:application --host 0.0.0.0
+else
+    exec uvicorn config.asgi:application --host 0.0.0.0 --reload --reload-include '*.html'
+fi

docker-compose.override-example.yml

@@ -0,0 +1,30 @@
+# Docker Compose Override File for Local Development
+#
+# This file can be used to enable debugging and other local development features (db volume location, etc.)
+# without affecting the committed docker-compose.yml file.
+#
+# Setup Instructions:
+# 1. Copy this file: cp docker-compose.override-example.yml docker-compose.override.yml
+# 2. Start services: docker compose up
+# 3. Attach debugger from VS Code using the launch configurations in .vscode/launch.json
+#
+# The docker-compose.override.yml file is git-ignored for local customization.
+
+services:
+  django:
+    environment:
+      - DEBUGGER=1
+    ports:
+      - "5678:5678"
+    volumes:
+      # allow modifying the start script without rebuilding the image
+      - ./compose/local/django/start:/start
+
+  celeryworker:
+    environment:
+      - DEBUGGER=1
+    ports:
+      - "5679:5679"
+    volumes:
+      # allow modifying the start script without rebuilding the image
+      - ./compose/local/django/celery/worker/start:/start-celeryworker

docker-compose.yml

@@ -90,11 +90,8 @@ services:
     <<: *django
     image: ami_local_celeryworker
     scale: 1
-    # For remote debugging with debugpy, should get overridden for production
-    # Also make sure to install debugpy in your requirements/local.txt
-    ports:
-      - "5678:5678"
-    command: python -m debugpy --listen 0.0.0.0:5678 -m celery -A config.celery_app worker -l INFO
+    ports: []
+    command: /start-celeryworker
 
   celerybeat:
     <<: *django