VSCode API Debugger (#222)

## Changes

- Add API debugging ability from VSCode

app/Makefile

@@ -92,6 +92,9 @@ build:
 start:
 	docker compose up --detach
 
+start-debug:
+	docker compose -f ../docker-compose.yml -f ../docker-compose.debug.yml up --detach
+
 run-logs: start
 	docker compose logs --follow --no-color $(APP_NAME)
 

app/pyproject.toml

@@ -40,6 +40,7 @@ pytest-watch = "^4.2.0"
 pytest-lazy-fixture = "^0.6.3"
 types-pyyaml = "^6.0.12.11"
 setuptools = "^68.2.2"
+debugpy = "^1.8.1"
 
 [build-system]
 requires = ["poetry-core>=1.0.0"]

docker-compose.debug.yml

@@ -0,0 +1,26 @@
+version: "3.8"
+
+# run with `docker compose -f`
+# combines ports and env vars with the main docker-compose.yml main-app service
+
+services:
+  main-app:
+    build:
+      context: ./app
+      target: dev
+      args:
+        - RUN_UID=${RUN_UID:-4000}
+        - RUN_USER=${RUN_USER:-app}
+    container_name: main-app
+    env_file: ./app/local.env
+    command: [
+      "poetry", "run", "python", "-m", "debugpy",
+      "--listen", "0.0.0.0:5678",
+      "--wait-for-client",  "--log-to-stderr",
+      "-m", "flask", "--app", "src.app", "run",
+      "--host", "0.0.0.0", "--port", "8080", "--no-reload"
+    ]
+    ports:
+      - 5678:5678
+    volumes:
+      - ./app:/app

docs/app/README.md

@@ -15,7 +15,7 @@ root
 │   └── src
 │       └── auth                Authentication code for API
 │       └── db
-│           └── models          DB model definitions            
+│           └── models          DB model definitions
 │           └── migrations      DB migration configs
 │               └── versions    The DB migrations
 │       └── logging
@@ -105,3 +105,52 @@ Any environment variables specified directly in the [docker-compose](/docker-com
 ## Authentication
 
 This API uses a very simple [ApiKey authentication approach](https://apiflask.com/authentication/#use-external-authentication-library) which requires the caller to provide a static key. This is specified with the `API_AUTH_TOKEN` environment variable.
+
+## VSCode Remote Attach Container Debugging
+
+The API can be run in debug mode that allows for remote attach debugging (currently only supported from VSCode) to the container.
+
+- Requirements:
+
+  - VSCode Python extension
+  - Updated Poetry with the `debugpy` dev package in `pyproject.toml`
+
+- First create a file `./vscode/launch.json` - as shown below. (Default name of `Python: Remote Attach`)
+
+- Start the server in debug mode via `make start-debug` or `make start-debug run-logs`.
+    - This will start the `main-app` service with port 5678 exposed.
+
+- The server will start in waiting mode, waiting for you to attach the debugger (see `/src/app.py`) before continuing to run.
+
+- Go to your VSCode debugger window and run the `Python: Remote Attach` option
+
+- You should now be able to hit set breakpoints throughout the API
+
+`./vscode/launch.json`:
+
+```
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Remote Attach",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost",
+                "port": 5678
+            },
+            "pathMappings": [
+                {
+                    "localRoot": "${workspaceFolder}/app",
+                    "remoteRoot": "."
+                }
+            ],
+            "justMyCode": false,
+        }
+    ]
+}
+```