chore: configure django debug toolbar

backend/.env.sample

@@ -1,4 +1,6 @@
 DEBUG=true
+ENABLE_DJANGO_DEBUG_TOOLBAR=true
+DJANGO_INTERNAL_IPS=127.0.0.1,localhost,host.docker.internal
 DJANGO_SECRET_KEY=change-me
 DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1,0.0.0.0
 DJANGO_CORS_ALLOWED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

backend/README.md

@@ -634,6 +634,8 @@ Example:
 | Variable | Default | Purpose |
 | --- | --- | --- |
 | `DEBUG` | `true` | Enables debug mode and permissive CORS in local development. |
+| `ENABLE_DJANGO_DEBUG_TOOLBAR` | `true` when `DEBUG=true` | Enables Django Debug Toolbar for local backend requests. |
+| `DJANGO_INTERNAL_IPS` | `127.0.0.1,localhost,host.docker.internal` | Internal IP allowlist used by Django Debug Toolbar. |
 | `DJANGO_SECRET_KEY` | local dev key | Django secret key. Override outside local development. |
 | `DJANGO_ALLOWED_HOSTS` | `localhost,127.0.0.1,0.0.0.0` | Allowed hosts. |
 | `DJANGO_CORS_ALLOWED_ORIGINS` | `http://localhost:5173,http://127.0.0.1:5173` | Frontend origins. |

backend/config/settings.py

@@ -10,6 +10,9 @@ BASE_DIR = Path(__file__).resolve().parent.parent
 SECRET_KEY = os.getenv("DJANGO_SECRET_KEY", "django-insecure-job-queue-local-dev-key")
 DEBUG = os.getenv("DEBUG", "true").lower() in {"1", "true", "yes"}
 ALLOWED_HOSTS = [host.strip() for host in os.getenv("DJANGO_ALLOWED_HOSTS", "localhost,127.0.0.1,0.0.0.0").split(",")]
+ENABLE_DJANGO_DEBUG_TOOLBAR = (
+    DEBUG and os.getenv("ENABLE_DJANGO_DEBUG_TOOLBAR", "true").lower() in {"1", "true", "yes"}
+)
 
 INSTALLED_APPS = [
     "unfold",
@@ -25,6 +28,9 @@ INSTALLED_APPS = [
     "jobs",
 ]
 
+if ENABLE_DJANGO_DEBUG_TOOLBAR:
+    INSTALLED_APPS.append("debug_toolbar")
+
 MIDDLEWARE = [
     "django.middleware.security.SecurityMiddleware",
     "corsheaders.middleware.CorsMiddleware",
@@ -36,6 +42,9 @@ MIDDLEWARE = [
     "django.middleware.clickjacking.XFrameOptionsMiddleware",
 ]
 
+if ENABLE_DJANGO_DEBUG_TOOLBAR:
+    MIDDLEWARE.insert(2, "debug_toolbar.middleware.DebugToolbarMiddleware")
+
 ROOT_URLCONF = "config.urls"
 
 TEMPLATES = [
@@ -120,6 +129,21 @@ UNFOLD = {
     "SITE_SUBHEADER": "Jobs, attempts, leases, and events",
 }
 
+INTERNAL_IPS = [
+    ip.strip()
+    for ip in os.getenv("DJANGO_INTERNAL_IPS", "127.0.0.1,localhost,host.docker.internal").split(",")
+    if ip.strip()
+]
+
+
+def show_debug_toolbar(_request):
+    return ENABLE_DJANGO_DEBUG_TOOLBAR
+
+
+DEBUG_TOOLBAR_CONFIG = {
+    "SHOW_TOOLBAR_CALLBACK": show_debug_toolbar,
+}
+
 JOB_WORKER_THREADS = int(os.getenv("JOB_WORKER_THREADS", "4"))
 JOB_WORKER_POLL_INTERVAL_MS = int(os.getenv("JOB_WORKER_POLL_INTERVAL_MS", "500"))
 JOB_WORKER_LEASE_SECONDS = int(os.getenv("JOB_WORKER_LEASE_SECONDS", "30"))

backend/config/urls.py

@@ -1,3 +1,4 @@
+from django.conf import settings
 from django.contrib import admin
 from django.urls import include, path
 from drf_spectacular.views import SpectacularAPIView, SpectacularSwaggerView
@@ -31,3 +32,6 @@ urlpatterns = [
     path("api/config/", ConfigAPIView.as_view(), name="config"),
     path("api/", include("jobs.urls")),
 ]
+
+if settings.ENABLE_DJANGO_DEBUG_TOOLBAR:
+    urlpatterns.append(path("__debug__/", include("debug_toolbar.urls")))

backend/requirements.txt

@@ -5,6 +5,7 @@ drf-spectacular>=0.28,<0.29
 python-dotenv>=1.1,<2.0
 psycopg[binary]>=3.2,<4.0
 django-unfold>=0.76,<1.0
+django-debug-toolbar>=5.0,<6.0
 pytest>=8.0,<9.0
 pytest-django>=4.9,<5.0
 pytest-cov>=6.0,<7.0

docker-compose.yml

@@ -22,6 +22,7 @@ services:
     command: sh -c "python manage.py migrate && python manage.py runserver 0.0.0.0:8000"
     environment:
       DEBUG: "true"
+      ENABLE_DJANGO_DEBUG_TOOLBAR: "true"
       DJANGO_ALLOWED_HOSTS: localhost,127.0.0.1,0.0.0.0
       DJANGO_CORS_ALLOWED_ORIGINS: http://localhost:5173,http://127.0.0.1:5173
       POSTGRES_DB: ${POSTGRES_DB:-job_queue}