From 69244c33529aab54dc7d3248713b9b7751f2b9cb Mon Sep 17 00:00:00 2001
From: davidwyld <24752124+davidwilby@users.noreply.github.com>
Date: Wed, 21 Jan 2026 15:39:04 +0000
Subject: [PATCH 1/2] add utilities and docs for debugging with docker

---
 Dockerfile          |  3 ++-
 compose.debug.yml   |  7 +++++++
 docs/development.md | 32 ++++++++++++++++++++++++++++++++
 3 files changed, 41 insertions(+), 1 deletion(-)
 create mode 100644 compose.debug.yml

diff --git a/Dockerfile b/Dockerfile
index 714be02..a0af0f0 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -22,5 +22,6 @@ COPY pyproject.toml manage.py /usr/src/app/
 COPY polarrouteserver /usr/src/app/polarrouteserver
 
 ENV SETUPTOOLS_SCM_PRETEND_VERSION=99.99.99
+
 RUN uv pip install --system -e .
-RUN uv pip install --system django-debug-toolbar
+RUN uv pip install --system django-debug-toolbar debugpy
diff --git a/compose.debug.yml b/compose.debug.yml
new file mode 100644
index 0000000..41b0b99
--- /dev/null
+++ b/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
\ No newline at end of file
diff --git a/docs/development.md b/docs/development.md
index 9b7c324..1e04b7c 100644
--- a/docs/development.md
+++ b/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.

From 83d511c3ff482396d04ccb7d82eca2a3620a6895 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?David=20Wyld=20=28n=C3=A9=20Wilby=29?=
 <24752124+davidwyld@users.noreply.github.com>
Date: Wed, 21 Jan 2026 16:10:53 +0000
Subject: [PATCH 2/2] correct Capitalisation

Co-authored-by: Thomas Zwagerman <36264706+thomaszwagerman@users.noreply.github.com>
---
 docs/development.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/development.md b/docs/development.md
index 1e04b7c..048433a 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -24,7 +24,7 @@ A number of helpful development tools are made available through the `Makefile`,
 
 ## 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.
+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`