Enable debugging of the API server from inside a Docker container

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" # Comment this to map port for debugging.
       - "50280:50280"
     depends_on:
       - db

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

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
+   [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.

documentation/api/guides/index.md

@@ -6,4 +6,5 @@
 quickstart
 test
 documentation
+debugging
 ```

documentation/general/index.md

@@ -10,5 +10,5 @@ test
 zero_downtime_database_management
 logging
 stack
-
+workspace
 ```

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)