add utilities and docs for debugging with docker

Author: davidwyld

Dockerfile

@@ -24,4 +24,4 @@ COPY assets /usr/src/app/assets
 
 ENV SETUPTOOLS_SCM_PRETEND_VERSION=99.99.99
 RUN uv pip install --system -e .[frontend]
-RUN uv pip install --system django-debug-toolbar
+RUN uv pip install --system django-debug-toolbar debugpy

compose.debug.yml

@@ -0,0 +1,7 @@
+services:
+  app:
+    ports:
+      - 5678:5678
+    command: >
+      python -m debugpy --listen 0.0.0.0:5678 --wait-for-client
+      manage.py runserver 0.0.0.0:8000 --noreload

docs/development.md

@@ -22,6 +22,38 @@ A number of helpful development tools are made available through the `Makefile`,
 
 **Important**: Please ensure all changes are included in `CHANGELOG.md` in a human-friendly format.
 
+## Debugging with docker compose
+
+To run using a debugger in e.g. vs code, run with the additional compose file `compose.debug.yml` which adds some additional settings to enable this.
+
+Do so with: `docker compose -f compose.yml -f compose.debug.yml up`
+
+This will launch the containers, but the `app` service will stop until a debugger is attached.
+
+For VS Code, the launch config should look like:
+
+```json
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug Dockerised Django",
+            "type": "debugpy",
+            "request": "attach",
+            "pathMappings": [
+                {
+                "localRoot": "${workspaceFolder}",
+                "remoteRoot": "/usr/src/app"
+                }
+            ],
+            "connect": {"host": "127.0.0.1", "port": 5678},
+        }
+    ]
+}
+```
+
+Run the debugger using this config to run the debugger listening to the debugging port configured.
+
 ## Release/Versioning
 
 Version numbers should be used in tagging commits on the `main` branch and reflected in the `pyproject.toml` file and should be of the form `v0.1.7` using the semantic versioning convention.