diff --git a/api/compose.yml b/api/compose.yml index 28e0736abff..f88eee7295d 100644 --- a/api/compose.yml +++ b/api/compose.yml @@ -19,10 +19,13 @@ services: - PDM_INSTALL_ARGS=--dev image: openverse-api:${API_PDM_HASH:-latest} pull_policy: never + # During debugging, use the following command to override. + # command: python -Xfrozen_modules=off -m debugpy --listen 0.0.0.0:5678 run.py volumes: - .:/api:z - ../packages/python:/packages/python:z ports: + # - "50256:5678" # Uncomment this to map port for debugging. - "50280:50280" depends_on: - db diff --git a/api/pdm.lock b/api/pdm.lock index 51c3997cef9..fc33b507d96 100644 --- a/api/pdm.lock +++ b/api/pdm.lock @@ -5,7 +5,7 @@ groups = ["default", "dev", "overrides", "test"] strategy = ["inherit_metadata"] lock_version = "4.5.0" -content_hash = "sha256:0ccb45f2f3acade4e0e80b7fd1bfb3f157fea437c5a98584084a070d783359e7" +content_hash = "sha256:c2d4630f70250e30f99650c6ee7a39694b2a1155ef2836d7abb299fdc3491151" [[metadata.targets]] requires_python = "==3.12.*" @@ -358,6 +358,21 @@ files = [ {file = "cryptography-42.0.5.tar.gz", hash = "sha256:6fe07eec95dfd477eb9530aef5bead34fec819b3aaf6c5bd6d20565da607bfe1"}, ] +[[package]] +name = "debugpy" +version = "1.8.9" +requires_python = ">=3.8" +summary = "An implementation of the Debug Adapter Protocol for Python" +groups = ["dev"] +files = [ + {file = "debugpy-1.8.9-cp312-cp312-macosx_14_0_universal2.whl", hash = "sha256:957363d9a7a6612a37458d9a15e72d03a635047f946e5fceee74b50d52a9c8e2"}, + {file = "debugpy-1.8.9-cp312-cp312-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:5e565fc54b680292b418bb809f1386f17081d1346dca9a871bf69a8ac4071afe"}, + {file = "debugpy-1.8.9-cp312-cp312-win32.whl", hash = "sha256:3e59842d6c4569c65ceb3751075ff8d7e6a6ada209ceca6308c9bde932bcef11"}, + {file = "debugpy-1.8.9-cp312-cp312-win_amd64.whl", hash = "sha256:66eeae42f3137eb428ea3a86d4a55f28da9bd5a4a3d369ba95ecc3a92c1bba53"}, + {file = "debugpy-1.8.9-py2.py3-none-any.whl", hash = "sha256:cc37a6c9987ad743d9c3a14fa1b1a14b7e4e6041f9dd0c8abf8895fe7a97b899"}, + {file = "debugpy-1.8.9.zip", hash = "sha256:1339e14c7d980407248f09824d1b25ff5c5616651689f1e0f0e51bdead3ea13e"}, +] + [[package]] name = "decorator" version = "5.1.1" diff --git a/api/pyproject.toml b/api/pyproject.toml index a958534c863..b89b3a22a6a 100644 --- a/api/pyproject.toml +++ b/api/pyproject.toml @@ -53,6 +53,7 @@ dev = [ "pgcli >=4.1, <5", "remote-pdb >=2.1.0, <3", "setuptools >=75.2,<76", + "debugpy >= 1.8.9,<2", # FIXME: Should be removed when Python build issues are resolved, # FIXME: since we don't explicitly use this library. # FIXME: https://github.com/WordPress/openverse/issues/5146 diff --git a/documentation/_static/vs_code_debug_panel.png b/documentation/_static/vs_code_debug_panel.png new file mode 100644 index 00000000000..0a3cc341d7f Binary files /dev/null and b/documentation/_static/vs_code_debug_panel.png differ diff --git a/documentation/_static/vs_code_workspace.png b/documentation/_static/vs_code_workspace.png new file mode 100644 index 00000000000..d5cfc9e41ab Binary files /dev/null and b/documentation/_static/vs_code_workspace.png differ diff --git a/documentation/api/guides/debugging.md b/documentation/api/guides/debugging.md new file mode 100644 index 00000000000..3d413514c60 --- /dev/null +++ b/documentation/api/guides/debugging.md @@ -0,0 +1,71 @@ +# API debugging guidelines + +```{note} +This is an opinionated guide that only applies to VS Code users. If you use a +different editor or IDE, these instructions will not apply to you. +``` + +This is the guide to debugging the API using VS Code. This uses Microsoft's +`debugpy` package. + +## Prerequisites + +1. Install the + [Python Debugger extension](https://marketplace.visualstudio.com/items?itemName=ms-python.debugpy). +1. [Set up a VS Code workspace](/general/workspace.md) for the Openverse + monorepo. + +## Steps + +1. Add a launch configuration to the Openverse workspace configuration. This + configuration does the following things. + + - Specifies that the debugger used should be `debugpy`. + - Configures the debugger to "attach" to a running process instead of + launching a new one. + - Specifies the port on which the `debugpy` server is running so that VS Code + can connect to it. + - Maps source code in the local repo clone to paths inside the Docker + container so you can set breakpoints in the editor. + + ```json + { + // existing configuration + "launch": { + "version": "0.2.0", + "configurations": [ + { + "name": "API", + "type": "debugpy", + "request": "attach", + "connect": { + "host": "localhost", + "port": 50256 + }, + "pathMappings": [ + { + "localRoot": "${workspaceFolder:api}", + "remoteRoot": "/api" + } + ], + "justMyCode": true + } + ] + } + } + ``` + +1. Edit the `compose.yml` file inside the `api/` directory to uncomment the + `command` field and port mapping for port 5678. + +1. Run the API server inside Docker using the instructions in the + [quickstart](/api/guides/quickstart.md) guide. + +1. Connect the debugger to the running instance from the Run and Debug panel. + + ![VS Code Run and Debug panel](/_static/vs_code_debug_panel.png) + +1. Read the + [Visual Code debugger's official instructions](https://code.visualstudio.com/docs/editor/debugging) + to better understand how to use the debugger interface to accomplish tasks + like setting breakpoints, watching variables etc. diff --git a/documentation/api/guides/index.md b/documentation/api/guides/index.md index 06156d83592..fd90860002d 100644 --- a/documentation/api/guides/index.md +++ b/documentation/api/guides/index.md @@ -6,4 +6,5 @@ quickstart test documentation +debugging ``` diff --git a/documentation/general/index.md b/documentation/general/index.md index ac9fa8e97bc..5039be2ec9d 100644 --- a/documentation/general/index.md +++ b/documentation/general/index.md @@ -10,5 +10,5 @@ test zero_downtime_database_management logging stack - +workspace ``` diff --git a/documentation/general/workspace.md b/documentation/general/workspace.md new file mode 100644 index 00000000000..133e0f4feaa --- /dev/null +++ b/documentation/general/workspace.md @@ -0,0 +1,67 @@ +# Using workspaces + +```{note} +This is an opinionated guide that only applies to VS Code users. If you use a +different editor or IDE, these instructions will not apply to you. +``` + +This is a guide to uses VS Code's multi-root workspace feature to work on +multiple sub-stacks of Openverse. + +## Steps + +1. Clone the GitHub repository. + + ```shell + git clone --filter=blob:none https://github.com/WordPress/openverse.git # or your fork + ``` + +1. In the same directory as the repository, create a workspace file + `openverse.code-workspace` with the following configuration. + + ```json + { + "folders": [ + { + "name": "monorepo", + "path": "openverse" + }, + { + "name": "catalog", + "path": "openverse/catalog" + }, + { + "name": "indexer_worker", + "path": "openverse/indexer_worker" + }, + { + "name": "ingestion_server", + "path": "openverse/ingestion_server" + }, + { + "name": "api", + "path": "openverse/api" + }, + { + "name": "frontend", + "path": "openverse/frontend" + }, + { + "name": "documentation", + "path": "openverse/documentation" + }, + { + "name": "python/openverse-attribution", + "path": "openverse/packages/python/openverse-attribution" + } + ], + "settings": { + "terminal.integrated.cwd": "${workspaceFolder:monorepo}" + } + } + ``` + +1. From VS Code, open this workspace file. You should see the entire repository + open in VS Code with all sub-stacks depicted as top-level folders. + + ![VS Code workspace](/_static/vs_code_workspace.png)