Pin monitoring and dependency image versions for reproducible local stacks

.env.example

@@ -0,0 +1,8 @@
+# Optional overrides for monitoring and dependency image versions.
+# Defaults are set in docker-compose.yml if these are unset.
+# Copy to .env and adjust if you need a different reviewed version.
+
+REDIS_VERSION=7.4
+JAEGER_VERSION=2.22.0
+PROMETHEUS_VERSION=v3.13.4
+GRAFANA_VERSION=13.2.4

CONTRIBUTING.md

@@ -157,3 +157,30 @@ PRs should:
 For design changes with significant distributed-systems impact, open an issue before implementing a large change. Explain the trade-offs and proposed approach so the design can be discussed before code is written.
 
 Thank you for helping improve the project.
+
+## Updating container image versions
+
+The `docker-compose.yml` pins Jaeger, Prometheus, Grafana, and Redis to specific reviewed tags via environment variables (with defaults). This keeps local stacks reproducible.
+
+Default versions (as of the pin commit):
+
+- Redis: `7.4-alpine`
+- Jaeger: `2.22.0`
+- Prometheus: `v3.13.4` (LTS line)
+- Grafana: `13.2.4`
+
+To override temporarily:
+
+```bash
+cp .env.example .env
+# edit .env
+docker compose up -d
+```
+
+### Process for updating a pinned version
+
+1. Review the upstream release notes and changelog for breaking changes.
+2. Update the default in `docker-compose.yml` and the value in `.env.example`.
+3. Run `docker compose pull` and `docker compose up -d` to verify the stack starts and healthchecks pass.
+4. Smoke-test tracing (Jaeger UI), metrics (Prometheus targets), and dashboards (Grafana).
+5. Document the new versions and any required config adjustments in the PR.

docker-compose.yml

@@ -1,7 +1,7 @@
 services:
 
   redis:
-    image: redis:7-alpine
+    image: redis:${REDIS_VERSION:-7.4}-alpine
     container_name: traffic-control-redis
     healthcheck:
       test: ["CMD", "redis-cli", "ping"]
@@ -13,7 +13,7 @@ services:
       - "6379:6379"
 
   jaeger:
-    image: jaegertracing/jaeger:latest
+    image: jaegertracing/jaeger:${JAEGER_VERSION:-2.22.0}
     container_name: traffic-control-jaeger
     ports:
       - "16686:16686"
@@ -99,7 +99,7 @@ services:
       - "8083:8081"
 
   prometheus:
-    image: prom/prometheus:latest
+    image: prom/prometheus:${PROMETHEUS_VERSION:-v3.13.4}
     container_name: traffic-control-prometheus
     depends_on:
       - gateway-1
@@ -111,7 +111,7 @@ services:
       - "9090:9090"
 
   grafana:
-    image: grafana/grafana:latest
+    image: grafana/grafana:${GRAFANA_VERSION:-13.2.4}
     container_name: traffic-control-grafana
     depends_on:
       - prometheus
@@ -120,4 +120,4 @@ services:
       - ./monitoring/grafana/provisioning/dashboards:/etc/grafana/provisioning/dashboards:ro
       - ./monitoring/grafana/dashboards:/var/lib/grafana/dashboards:ro
     ports:
-      - "3000:3000"
+      - "3000:3000"