Add VS Code debug configuration (#48)

* Add vscode debug config for flask app

Adds a docker-compose.debug.yml file based on the existing docker-compose.yml file used in dev, which overrides the default command in order to install debugpy and wait for a debugger to attach via port 6789 prior to running the flask dev server process.

* Add vscode debug config for save_routes.py

Adds configuration for debugging the `save_routes.py` script using the flask-dev Docker image. This configuration can be used as prior art for adding other script debug configuration in the future, or adjusted to accept a user-specified command to run rather than creating vscode tasks for each script. Note: a prompt was added to allow M1/M2 Mac users to select a working platform; this will ideally be removed in the future as support for ARM64 wheels is added to installed packages, but is necessary for now to successfully build the Docker image.

* Add docs for new debug configuration

* Update compose debug config to be used as extension to base compose config

Updates the `docker-compose.debug.yml` config to define only settings that should override or extend the base `docker-compose.yml` config.

.gitignore

@@ -14,7 +14,10 @@ backend/data/*/
 docker-compose.override.yml
 
 .aws/
-.vscode/
+.vscode/*
+
+!.vscode/launch.json
+!.vscode/tasks.json
 
 # Created by https://www.gitignore.io/api/node,macos,flask,python,eclipse,intellij
 # Edit at https://www.gitignore.io/?templates=node,macos,flask,python,eclipse,intellij

.vscode/launch.json

@@ -0,0 +1,39 @@
+{
+  // 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: Attach",
+      "type": "python",
+      "request": "attach",
+      "connect": {
+        "host": "localhost",
+        "port": 6789
+      },
+      "pathMappings": [
+        {
+          "localRoot": "${workspaceFolder}/backend",
+          "remoteRoot": "/app/backend"
+        }
+      ],
+
+    },
+    {
+      "name": "Docker: flask-dev - save_routes.py",
+      "type": "docker",
+      "request": "launch",
+      "preLaunchTask": "docker-run: save_routes.py",
+      "python": {
+        "pathMappings": [
+          {
+            "localRoot": "${workspaceFolder}/backend",
+            "remoteRoot": "/app/backend"
+          }
+        ],
+        "projectType": "general"
+      }
+    }
+  ]
+}

.vscode/tasks.json

@@ -0,0 +1,41 @@
+{
+	"version": "2.0.0",
+	"tasks": [
+    {
+      "type": "docker-build",
+      "label": "docker-build",
+      "platform": "python",
+      "dockerBuild": {
+        "tag": "opentransitmetrics:flask-dev",
+        "dockerfile": "${workspaceFolder}/Dockerfile",
+        "context": "${workspaceFolder}",
+        "pull": true,
+        "target": "flask-dev",
+        "customOptions": "${input:dockerBuildm1}",
+      }
+    },
+    {
+      "type": "docker-run",
+      "label": "docker-run: save_routes.py",
+      "dependsOn": [
+        "docker-build"
+      ],
+      "python": {
+        "args": ["--s3", "--timetables", "--scheduled-stats", "--agency=trimet"],
+        "file": "save_routes.py"
+      }
+    }
+  ],
+  "inputs": [
+    {
+      "id": "dockerBuildm1",
+      "type": "pickString",
+      "description": "Select '--platform linux/amd64' to build for Macs with an ARM CPU",
+      "default": "",
+      "options": [
+        "--platform linux/amd64",
+        ""
+      ]
+    }
+  ]
+}

README.md

@@ -227,6 +227,22 @@ services:
 
 After changing docker-compose.override.yml, you will need to re-run `docker-compose up` for the changes to take effect.
 
+### Debugging in VS Code
+
+#### Debugging the Flask app
+
+For developers using the VS Code editor, there is configuration that supports debugging Python code. To debug the Flask app, the `docker-compose.debug.yml` compose file is configured to listen on port `6789` before starting the app, while the debugger is attached via the "Python: Attach" configuration defined in [`.vscode/launch.json`](.vscode/launch.json).
+
+To debug using this configuration, the debug compose file should be used along with the base compose config to start up the services. This can be done by listing the debug compose file explicitly along with the base config, for example, `docker compose -f docker-compose.yml -f docker-compose.debug.yml up` (add the `--build` option if the containers need to be built). Open the "Run and Debug" panel in the VS Code sidebar, then select and run the "Python: Attach" launch configuration.
+
+> **NOTE**: If running on a Mac with an ARM CPU (for example, an M1 or M2 processor), the `docker-compose.override.yml` file will need to be included as an additional file option: `docker compose -f docker-compose.yml -f docker-compose.debug.yml -f docker-compose.override.yml up`. See [this article](https://pythonspeed.com/articles/docker-build-problems-mac/) for more details.
+
+#### Debugging Python command line scripts
+
+To debug code that is not run as part of the Flask app, for example one of the command line scripts, the `flask-dev` Docker image can be built and run using configuration in [`.vscode/tasks.json`](.vscode/tasks.json). Configuration exists for running the `save_routes.py` script, and this can be expanded over time to allow for debugging additional scripts.
+
+To run the debug configuration for this script, open the "Run and Debug" panel in the VS Code sidebar, then select and run the "Docker: flask-dev - save_routes.py" launch configuration. When prompted, select the `--platform linux/amd64` option if running on a Mac with an ARM CPU (see note in previous section), or the default value for any other platform.
+
 ### Advanced Concepts
 
 Please see [ADVANCED_DEV.md](docs/ADVANCED_DEV.md) for even more advanced information like computing arrival times and deploying to AWS.

docker-compose.debug.yml

@@ -0,0 +1,15 @@
+#
+# docker-compose file configured for starting the flask-dev service
+# with debug config for use with VS Code.
+# Should be started up as follows:
+# - Run `docker compose up` with the `docker-compose.yml` file as the base config.
+#   For example: `docker compose -f "docker-compose.yml" -f "docker-compose.debug.yml" up --build`
+# - Once the flask-dev service has started, attach the VS Code debugger by switching
+#   to the debug sidebar and running the `Python: Attach` config.
+# - Add breakpoints as desired to flask app code.
+version: "3.7"
+services:
+  flask-dev:
+    command: ["sh", "-c", "pip install debugpy -t /tmp && python /tmp/debugpy --wait-for-client --listen 0.0.0.0:6789 -m flask run --no-debugger --no-reload --host 0.0.0.0 --port 5000"]
+    ports:
+      - "6789:6789"