feat: add debugger and prioritise local values yaml

Author: osintalex

docs/develop/backend-hot-reload-and-debugger.md

@@ -0,0 +1,62 @@
+# Deploy the Backend with Hot Reloading and Interactive Debugging
+
+This guide explains how to deploy Browsertrix with [skaffold](https://skaffold.dev/) 
+so the backend hot reloads and allows interactive debugging.
+
+This may save time since you don't need to rebuild the backend container every time you change code
+and can use a debugger to step through code.
+
+## Requirements
+
+Follow the documentation to [install skaffold](https://skaffold.dev/docs/install/), i.e. if you are on
+Mac OS run:
+
+```sh
+brew install skaffold
+```
+
+To install helm and set up a local Kubernetes cluster, see the section on [local dev set up](local-dev-setup.md).
+
+## Quickstart
+
+From the command line, run:
+
+```sh
+skaffold dev
+```
+
+This will deploy Browsertrix into the cluster and port forward the API with hot reloading. 
+Navigate to `localhost:8000/api/redoc` or `localhost:8000/api/docs` to see the documentation.
+Changing any code in `backend/btrixcloud` will trigger a reload.
+
+### Debugger
+
+Interactive debugging uses [debugpy](https://github.com/microsoft/debugpy), which 
+works on VSCode but not PyCharm.
+
+Use this debug configuration in VSCode:
+
+```JSON
+{
+    "name": "Attach to Browsertrix Backend",
+    "type": "debugpy",
+    "request": "attach",
+    "connect": {
+        "host": "127.0.0.1",
+        "port": 5678
+    },
+    "pathMappings": [
+        {
+        "localRoot": "${workspaceFolder}/backend/btrixcloud/",
+        "remoteRoot": "/app/btrixcloud/"
+        }
+    ],
+    "justMyCode": false
+}
+```
+
+This will attach to the Kubernetes pod running Browsertrix and persist between
+hot reloads. Change your code, wait for the application to reload, 
+and still hit breakpoints in the same debugging session.
+
+

docs/develop/backend-hot-reload.md

@@ -136,4 +136,4 @@ If you are just making changes to the frontend, you can also [deploy the fronten
 
 ## Deploying Backend with Hot Reloading
 
-If you want to iterate faster on the backend, read [deploy the backend with hot reloading](backend-hot-reload.md).
+If you want to iterate faster on the backend, read [deploy the backend with hot reloading and interactive debugging](backend-hot-reload-and-debugger.md).

docs/develop/local-dev-setup.md

@@ -61,7 +61,7 @@ nav:
       - develop/local-dev-setup.md
       - develop/frontend-dev.md
       - develop/docs.md
-      - develop/backend-hot-reload.md
+      - develop/backend-hot-reload-and-debugger.md
   - User Guide:
       - user-guide/index.md
       - user-guide/signup.md

mkdocs.yml

@@ -15,32 +15,39 @@ build:
         - src: 'btrixcloud/**/*'
           dest: .
 portForward:
+# so you can hit the API on `localhost:8000`
 - resourceType: service
   resourceName: browsertrix-cloud-backend
-  # assumes you are doing local dev in `default` namespace
-  # if you aren't you need to change this manually
   namespace: default
   port: 8000
   localPort: 8000
+# for the debugger
+- resourceType: deployment
+  resourceName: browsertrix-cloud-backend
+  namespace: default
+  port: 5678
+  localPort: 5678
 deploy:
   helm:
     releases:
       - name: btrix
         chartPath: chart
         valuesFiles:
           - chart/values.yaml
+          # local must come after values since it is expected to override
+          - chart/local.yaml
         # See https://skaffold.dev/docs/deployers/helm/
         # must do this to make skaffold use local images with helm
         setValues:
-          backend_image: docker.io/webrecorder/browsertrix-backend
-          backend_pull_policy: "Never"
           # hot reloading doesn't work with default gunicorn command
           # so need to override to use uvicorn
-          backend_api_command_override: 
-            - uvicorn
-            - btrixcloud.main:app_root
-            - --reload
-            - --host
-            - "0.0.0.0"
-            - --port
-            - "8000"
+          # plus need to start the process with debugpy to debug
+          backend_api_command_override:
+            - sh
+            - -c
+            -  >
+                pip install --no-input debugpy
+                &&
+                python -m debugpy --listen 0.0.0.0:5678
+                -m uvicorn btrixcloud.main:app_root
+                --reload --host 0.0.0.0 --port 8000