docs: add ADR 0001 and storage scale-out stub

ADR records the single-host OTLP-native architecture decision and its
alternatives; compose.storage.s3.yml is a deliberately commented stub
documenting the concrete Loki/Tempo → S3 path the README mentions.

Author: simonvanlierde

CHANGELOG.md

@@ -21,6 +21,9 @@ First tagged release: the stack is runnable, demoable, and validated in CI.
   error rate.
 - README: architecture diagram, demo quickstart, screenshot, design
   decisions.
+- ADR 0001 recording the single-host OTLP-native architecture, and a
+  commented `compose.storage.s3.yml` stub documenting the storage
+  scale-out path.
 
 ### Changed
 

README.md

@@ -124,7 +124,9 @@ someone.
 
 Everything persists to local Docker volumes (`loki_data`, `tempo_data`,
 `prometheus_data`, `grafana_data`). Swap Loki / Tempo storage to S3-compatible
-(Backblaze B2, Cloudflare R2, Hetzner, MinIO) when you outgrow local disk.
+(Backblaze B2, Cloudflare R2, Hetzner, MinIO) when you outgrow local disk —
+`compose.storage.s3.yml` documents the concrete shape of that change, and
+`docs/adr/0001-observability-stack.md` records the architecture rationale.
 
 ## Design decisions
 

compose.storage.s3.yml

@@ -0,0 +1,54 @@
+# STUB — the storage scale-out path (not wired up; see ADR 0001).
+#
+# When local volumes stop fitting, Loki and Tempo move their object storage
+# to any S3-compatible backend (Cloudflare R2, Backblaze B2, Hetzner, MinIO)
+# without touching the collector, Prometheus, or any client project.
+#
+# This is deliberately a commented stub: it documents the concrete shape of
+# the change so the README's scale-out claim is real, but it is not meant to
+# be started until credentials and a bucket exist. To activate:
+#
+#   1. Create s3 variants of the configs, e.g. config/loki.s3.yaml replacing
+#      `common.storage.filesystem` with:
+#
+#        common:
+#          storage:
+#            s3:
+#              endpoint: ${S3_ENDPOINT}        # e.g. <account>.r2.cloudflarestorage.com
+#              bucketnames: cml-loki
+#              access_key_id: ${S3_ACCESS_KEY_ID}
+#              secret_access_key: ${S3_SECRET_ACCESS_KEY}
+#              s3forcepathstyle: true
+#
+#      and config/tempo.s3.yaml replacing `storage.trace.backend: local` with:
+#
+#        storage:
+#          trace:
+#            backend: s3
+#            s3:
+#              endpoint: ${S3_ENDPOINT}
+#              bucket: cml-tempo
+#              access_key: ${S3_ACCESS_KEY_ID}
+#              secret_key: ${S3_SECRET_ACCESS_KEY}
+#
+#   2. Uncomment the overlay below and run:
+#        docker compose -f compose.yml -f compose.storage.s3.yml up -d
+#
+# services:
+#   loki:
+#     volumes:
+#       - ./config/loki.s3.yaml:/etc/loki/loki.yaml:ro
+#       - loki_data:/loki
+#     environment:
+#       S3_ENDPOINT: ${S3_ENDPOINT:?set S3_ENDPOINT in .env}
+#       S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:?set S3_ACCESS_KEY_ID in .env}
+#       S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY in .env}
+#
+#   tempo:
+#     volumes:
+#       - ./config/tempo.s3.yaml:/etc/tempo/tempo.yaml:ro
+#       - tempo_data:/var/tempo
+#     environment:
+#       S3_ENDPOINT: ${S3_ENDPOINT:?set S3_ENDPOINT in .env}
+#       S3_ACCESS_KEY_ID: ${S3_ACCESS_KEY_ID:?set S3_ACCESS_KEY_ID in .env}
+#       S3_SECRET_ACCESS_KEY: ${S3_SECRET_ACCESS_KEY:?set S3_SECRET_ACCESS_KEY in .env}

docs/adr/0001-observability-stack.md

@@ -0,0 +1,50 @@
+# ADR 0001: Single-host OTLP-native observability stack
+
+Date: 2026-07-03. Status: accepted (records a decision already in production).
+
+## Context
+
+CML runs several research platforms (RELab and others) that need logs,
+traces, and metrics in one place. Telemetry volume is modest — a handful of
+services, single-digit requests per second — but the projects are
+long-lived, maintained by a very small team, and must stay cheap and
+auditable.
+
+## Decision
+
+Run one Docker Compose stack on a single host: an OpenTelemetry Collector as
+the only ingestion endpoint, fanning out to Loki (logs), Tempo (traces), and
+Prometheus (metrics), with Grafana on top. Expose Grafana and the OTLP
+endpoints via Cloudflare Tunnel; bind everything else to `127.0.0.1`.
+
+- **OTLP-native:** projects configure one endpoint and one protocol.
+  Backends can be swapped (or moved to hosted equivalents) without touching
+  any application.
+- **Single-host:** one compose file is something one person can fully audit
+  and rebuild. Distributed ingest (Kubernetes, Mimir, multi-tenant Loki)
+  buys nothing at this volume and costs ongoing operational attention.
+- **Traces as the primary signal:** Tempo's metrics generator derives RED
+  metrics and a service graph from spans, so a service that only sends
+  traces still gets dashboards and error-rate alerting.
+
+## Alternatives considered
+
+- **Grafana Cloud / hosted SaaS:** less to operate, but recurring cost,
+  data residency questions for research data, and less useful as
+  institutional infrastructure knowledge.
+- **Per-project stacks:** no shared endpoint to maintain, but duplicates
+  storage and Grafana per project and makes cross-project correlation
+  impossible.
+- **ELK / OpenSearch:** heavier to run, log-centric; weaker native OTLP and
+  trace correlation story than the Grafana stack.
+
+## Consequences
+
+- The host is a single point of failure; acceptable because the monitored
+  platforms degrade gracefully without telemetry (OTLP export is
+  fire-and-forget) and the stack rebuilds from this repo in minutes.
+- Local disk bounds retention (30d logs/metrics, 7d traces). The documented
+  escape hatch is S3-compatible storage for Loki/Tempo — see
+  `compose.storage.s3.yml` — before any move to distributed ingest.
+- Everything is pinned and validated by `just check` in CI, so the stack
+  stays reproducible.