From 93784d3dce089d78c0961ff9a1dd31f09be1820c Mon Sep 17 00:00:00 2001 From: Amal Sharma Date: Wed, 11 Feb 2026 08:28:56 +0000 Subject: [PATCH 1/3] feat: enable LMS to run in debug mode for improved troubleshooting --- .devcontainer/devcontainer.json | 12 ++++- LMS_DEBUG_MODE.md | 77 +++++++++++++++++++++++++++++++++ Makefile | 21 ++++++++- docker-compose.yml | 6 ++- lms-run.sh | 33 ++++++++++++++ 5 files changed, 145 insertions(+), 4 deletions(-) create mode 100644 LMS_DEBUG_MODE.md create mode 100755 lms-run.sh diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index a0bced6..af9e9d5 100644 --- a/.devcontainer/devcontainer.json +++ b/.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" } } } diff --git a/LMS_DEBUG_MODE.md b/LMS_DEBUG_MODE.md new file mode 100644 index 0000000..da327f5 --- /dev/null +++ b/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 diff --git a/Makefile b/Makefile index 387d38a..dd01f84 100644 --- a/Makefile +++ b/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 diff --git a/docker-compose.yml b/docker-compose.yml index 93e7758..80eefd0 100644 --- a/docker-compose.yml +++ b/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' diff --git a/lms-run.sh b/lms-run.sh new file mode 100755 index 0000000..9822bb0 --- /dev/null +++ b/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 From 29b465182449b22d1dde992ce4aa6dd26cdba7ca Mon Sep 17 00:00:00 2001 From: Amal Sharma Date: Mon, 16 Feb 2026 01:07:24 -0700 Subject: [PATCH 2/3] fix: Fix macOS image name in CLI tests workflow --- .github/workflows/cli-tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/cli-tests.yml b/.github/workflows/cli-tests.yml index 9bc048e..30da178 100644 --- a/.github/workflows/cli-tests.yml +++ b/.github/workflows/cli-tests.yml @@ -25,7 +25,7 @@ jobs: - name: linux image: ubuntu-latest - name: mac - image: macos-13 + image: macos-lates python-version: - '3.11' fail-fast: false From 418e46dea078601e2e1a061688a5ce5b802fd418 Mon Sep 17 00:00:00 2001 From: Amal Sharma Date: Mon, 16 Feb 2026 01:26:22 -0700 Subject: [PATCH 3/3] fix: Fix typo in macOS image name in workflow --- .github/workflows/cli-tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/cli-tests.yml b/.github/workflows/cli-tests.yml index 30da178..fd0e8e1 100644 --- a/.github/workflows/cli-tests.yml +++ b/.github/workflows/cli-tests.yml @@ -25,7 +25,7 @@ jobs: - name: linux image: ubuntu-latest - name: mac - image: macos-lates + image: macos-latest python-version: - '3.11' fail-fast: false