feat: enable LMS to run in debug mode for improved troubleshooting

.devcontainer/devcontainer.json

@@ -7,6 +7,13 @@
     },
     "customizations": {
         "vscode": {
+            //Optional list of VS Code extensions to install in the container.
+            //  See https://aka.ms/vscode-dev-containers/extensions.
+            // 
+            "extensions": [                
+                "ms-python.python",
+                "ms-python.debugpy" 
+            ],
             "settings": {
                 "terminal.integrated.profiles.linux": { "zsh": { "path": "/bin/zsh" } },
                 "terminal.integrated.profiles.osx": { "zsh": { "path": "/bin/zsh" } },
@@ -47,7 +54,7 @@
         2010, 3406, 5335, 7474, 8000, 8081, 8734, 8735, 9021, 9201, 9202,
         9301, 9600, 18000, 18010, 18040, 18110, 18120, 18130, 18150, 18160,
         18170, 18270, 18280, 18381, 18400, 18450, 18734, 18760, 18787, 19001,
-        27017, 44567
+        27017, 44567, 44568
     ],
     "portsAttributes": {
         "3406":  { "label": "mysql80" },
@@ -96,6 +103,7 @@
         "18270": { "label": "enterprise-access" },
         "18280": { "label": "enterprise-subsidy" },
         "8000":  { "label": "paragon-pattern-library" },
-        "18760": { "label": "ai-translations" }
+        "18760": { "label": "ai-translations" },
+        "44568": { "label": "LMS debugging" }
     }
 }

LMS_DEBUG_MODE.md

@@ -0,0 +1,77 @@
+# LMS Debug Mode Setup
+
+This document describes how to run the LMS service in normal or debug mode using the Devstack Makefile.
+
+## Quick Start
+
+### Normal Mode (Default)
+To run the LMS service in normal mode without debugpy:
+```bash
+make dev.up.lms
+```
+
+### Debug Mode with debugpy
+To run the LMS service in debug mode with debugpy enabled:
+```bash
+make dev.debug.lms
+```
+
+## How It Works
+
+### Implementation Details
+
+1. **LMS Runner Script** (`lms-run.sh`)
+   - A bash script that determines whether to run in normal or debug mode
+   - Checks the `DEVSTACK_DEBUG` environment variable
+   - If set to `debug`: Installs and runs with debugpy on port 44568
+   - If set to `normal` (default): Runs without debugpy
+
+2. **Docker Compose Configuration**
+   - The LMS service command now calls `lms-run.sh` instead of hardcoding debugpy
+   - The `DEVSTACK_DEBUG` environment variable is passed to the container
+   - Port 44568 remains exposed in docker-compose.yml for debugpy
+
+3. **Makefile Targets**
+   - `dev.up.%`: Standard targets for normal mode (unchanged)
+   - `dev.debug.%`: New targets that set `DEVSTACK_DEBUG=debug` before starting services
+   - Examples:
+     - `make dev.up.lms` - Start LMS normally
+     - `make dev.debug.lms` - Start LMS with debugpy
+     - `make dev.debug.lms+discovery` - Start LMS with debugpy and discovery in normal mode
+
+## VS Code Debugging
+
+With the LMS running in debug mode, you can attach VS Code debugger:
+
+1. Ensure `make dev.debug.lms` is running
+2. In VS Code, go to the Debug view (Ctrl+Shift+D)
+3. Select "LMS Debugpy" configuration
+4. Click the play button to attach the debugger
+
+The debugger will wait for client attachment when configured with `--wait-for-client` flag.
+
+## Switching Between Modes
+
+To switch from one mode to another:
+
+```bash
+# Kill existing LMS container
+docker-compose kill lms
+
+# Start in the desired mode
+make dev.up.lms        # Normal
+# or
+make dev.debug.lms     # Debug with debugpy
+```
+
+## Troubleshooting
+
+- **Debugpy port already in use**: Ensure no other process is using port 44568
+- **Script permission issues**: The `lms-run.sh` script will be executed inside the container, so host permissions don't matter
+- **Environment variable not passed**: Verify using `docker-compose exec lms env | grep DEVSTACK_DEBUG`
+
+## Technical Notes
+
+- The `DEVSTACK_DEBUG` environment variable only affects LMS service
+- Other services (cms, lms-worker, etc.) are not affected by this flag
+- For services other than LMS, standard `dev.up` and `dev.debug` targets still apply the environment variable, but it won't affect their behavior unless they also implement similar logic

Makefile

@@ -54,7 +54,8 @@
         dev.shell.registrar dev.shell.cms \
         dev.shell.cms_watcher dev.shell.xqueue dev.shell.xqueue_consumer \
         dev.static dev.static.lms dev.static.cms dev.stats dev.status \
-        dev.stop dev.up dev.up.attach dev.up.shell \
+        dev.stop dev.debug dev.debug.without-deps \
+        dev.up dev.up.attach dev.up.shell \
         dev.up.without-deps dev.up.without-deps.shell dev.up.with-programs \
         dev.up.with-watchers dev.validate docs \
         help requirements impl-dev.clone.https impl-dev.clone.ssh impl-dev.provision \
@@ -279,6 +280,24 @@ ifeq ($(ALWAYS_CACHE_PROGRAMS),true)
 endif
 
 
+########################################################################################
+# Developer interface: Debug mode (with debugpy).
+########################################################################################
+
+dev.debug: _expects-service-list.dev.debug ## Bring up services in debug mode (with debugpy).
+
+dev.debug.%: dev.check-memory ## Bring up services in debug mode and their dependencies.
+	DEVSTACK_DEBUG=debug docker compose up -d $$(echo $* | tr + " ")
+ifeq ($(ALWAYS_CACHE_PROGRAMS),true)
+	make dev.cache-programs
+endif
+
+dev.debug.without-deps: _expects-service-list.dev.debug.without-deps ## Bring up services in debug mode by themselves.
+
+dev.debug.without-deps.%: dev.check-memory ## Bring up services in debug mode by themselves.
+	DEVSTACK_DEBUG=debug docker compose up -d --no-deps $$(echo $* | tr + " ")
+
+
 dev.ps: ## View list of created services and their statuses.
 	docker compose ps
 

docker-compose.yml

@@ -421,7 +421,8 @@ services:
 
   lms:
     # Switch to `--settings devstack_with_worker` if you want to use lms-worker
-    command: bash -c 'source /edx/app/edxapp/edxapp_env && (pip install -r /edx/private_requirements.txt; while true; do python /edx/app/edxapp/edx-platform/manage.py lms runserver 0.0.0.0:18000 --settings devstack; sleep 2; done)'
+    # Use DEVSTACK_DEBUG env var to enable debugpy. See `make dev.debug.lms` and `make dev.up.lms`.
+    command: bash -c '/edx/devstack/lms-run.sh ${DEVSTACK_DEBUG:-normal}'
     container_name: "edx.${COMPOSE_PROJECT_NAME:-devstack}.lms"
     hostname: lms.devstack.edx
     depends_on:
@@ -446,6 +447,7 @@ services:
       CMS_CFG: "/edx/etc/studio.yml"
       PATH: "/edx/app/edxapp/venvs/edxapp/bin:/edx/app/edxapp/nodeenv/bin:/edx/app/edxapp/edx-platform/node_modules/.bin:/edx/app/edxapp/edx-platform/bin:${PATH}"
       SERVICE_VARIANT: lms
+      DEVSTACK_DEBUG: ${DEVSTACK_DEBUG:-normal}
     image: edxops/lms-dev:latest
     networks:
       default:
@@ -455,10 +457,12 @@ services:
     ports:
       - "18000:18000"
       - "19876:19876" # JS test debugging
+      - "44568:44568" # debugpy
       # - "18003:18003"
       # - "18031:18031"
     volumes:
       - edxapp_lms_assets:/edx/var/edxapp/staticfiles/
+      - ${PWD}/lms-run.sh:/edx/devstack/lms-run.sh
 
   lms-worker:
     command: bash -c 'source /edx/app/edxapp/edxapp_env && cd /edx/app/edxapp/edx-platform && celery --app=lms.celery:APP worker -l debug -c 2'

lms-run.sh

@@ -0,0 +1,33 @@
+#!/bin/bash
+# LMS runner script to support both normal and debug modes
+# Usage: lms-run.sh [debug|normal]
+# Expected to be run inside the LMS container
+
+set -e
+
+source /edx/app/edxapp/edxapp_env
+
+DEBUG_MODE="${1:-${DEVSTACK_DEBUG:-normal}}"
+
+# Install pip requirements
+pip install -r /edx/private_requirements.txt
+
+if [ "$DEBUG_MODE" = "debug" ]; then
+    # Install debugpy for debug mode
+    pip install debugpy
+
+    # Run with debugpy
+    while true; do
+        python -m debugpy --listen 0.0.0.0:44568 --wait-for-client \
+            /edx/app/edxapp/edx-platform/manage.py lms runserver 0.0.0.0:18000 \
+            --settings devstack --noreload
+        sleep 2
+    done
+else
+    # Run in normal mode
+    while true; do
+        python /edx/app/edxapp/edx-platform/manage.py lms runserver 0.0.0.0:18000 \
+            --settings devstack --noreload
+        sleep 2
+    done
+fi