fix(workshop): harden staged learner setup

.github/workflows/workshop.yml

@@ -36,6 +36,9 @@ jobs:
           find . -type f -name '*.sh' -print0 \
             | xargs -0 -n1 bash -n
 
+      - name: Test staged preflight behavior
+        run: ./scripts/test-preflight.sh
+
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"

workshops/build_workshop/app/OBSERVABILITY.md

@@ -124,7 +124,7 @@ docker compose --env-file .env.workshop \
 | `CLICKHOUSE_ENDPOINT` | `https://${CLICKHOUSE_HOST}:${CLICKHOUSE_PORT}` | Full HTTPS endpoint (protocol + `:8443`) of the Cloud service. Assembled from the workshop's `CLICKHOUSE_HOST`/`CLICKHOUSE_PORT`. |
 | `CLICKHOUSE_USER` | `default` | Cloud SQL user. |
 | `CLICKHOUSE_PASSWORD` | (empty) | Cloud SQL password. |
-| `OTLP_AUTH_TOKEN` | (empty) | Shared secret securing the collector's OTLP ingest. Clients send it back. Empty disables auth. |
+| `OTLP_AUTH_TOKEN` | (empty) | Random shared secret securing the collector's OTLP ingest. Clients send it back; Module 05 preflight rejects an empty or placeholder value. |
 | `HYPERDX_OTEL_EXPORTER_CLICKHOUSE_DATABASE` | `otel` (via `CLICKSTACK_DATABASE`) | Database for ClickStack's `otel_*` tables. Separate from the app data DB (`nyc_tlc_data`). |
 | `CUSTOM_OTELCOL_CONFIG_FILE` | `/etc/otelcol-contrib/main.config.yaml` (main) · `.../custom.config.yaml` (container-logs) | Merges an extra config onto the image's baked-in pipelines. The **main** collector uses `main.config.yaml` to redirect the unused `metrics/promql` (Prometheus remote-write) pipeline to a `nop` exporter — see below. The **container-logs** collector uses `custom.config.yaml` for the filelog receiver. |
 
@@ -139,10 +139,11 @@ stops the error without affecting what lands in ClickHouse.
 Collector OTLP ports: `4317` (gRPC), `4318` (HTTP). If either host port is
 already taken, `docker compose ... up` fails to bind the collector; set
 `OTEL_GRPC_HOST_PORT` / `OTEL_HTTP_HOST_PORT` to free ports in `.env.workshop`
-**before** starting the overlay (`preflight.sh` flags the clash and suggests
-values). Those host mappings only matter for host-side OTLP senders — the backend
-reaches the collector in-network at `http://otel-collector:4318`, so overriding
-the host ports does NOT change the backend wiring.
+**before** starting the overlay (`./preflight.sh --otel` flags the clash and suggests
+values). Both mappings bind to `127.0.0.1`, so they are available to host-side senders
+without exposing the authenticated ingest receiver to the LAN. The backend reaches the
+collector in-network at `http://otel-collector:4318`, so overriding the host ports does
+NOT change the backend wiring.
 
 ### Backend
 

workshops/build_workshop/app/README.md

@@ -23,7 +23,7 @@ module 00 — it walks through every step below in order.
   plus `curl` and `git`.
 
 Host ports (override any of these in `.env.workshop` if it is already taken —
-`preflight.sh` tells you which one and suggests a free port):
+`preflight.sh` checks the app ports, and `preflight.sh --otel` adds the collector ports):
 
 | Service | Default host port | Override var |
 |---|---|---|
@@ -47,6 +47,7 @@ cp .env.workshop.example .env.workshop     # fill in your ClickHouse Cloud value
 docker compose --env-file .env.workshop -f docker-compose.workshop.yml up -d
 
 # with the ClickStack observability overlay (module 05 onward):
+./preflight.sh --otel                     # must print "Overall: READY" (exit 0)
 docker compose --env-file .env.workshop \
   -f docker-compose.workshop.yml -f docker-compose.otel.yml up -d --build
 ```

workshops/build_workshop/app/WORKSHOP_CHANGES.md

@@ -28,7 +28,7 @@ learner machine.
 1. Module 00 creates ClickHouse Cloud and starts only the local frontend/backend.
 2. Module 01 creates and seeds the Cloud schema.
 3. Module 03 creates managed Postgres, validates it with
-   `./preflight.sh --require-postgres`, then explicitly enables the `cdc` trip writer.
+   `./preflight.sh --cdc`, then explicitly enables the `cdc` trip writer.
 4. Module 05 starts the stateless collector overlay, then enables Managed ClickStack.
 5. Module 08 sends chat traces to Langfuse Cloud.
 

workshops/build_workshop/app/docker-compose.otel.yml

@@ -1,7 +1,7 @@
 # ClickStack observability OVERLAY.
 #
 # This file is NOT standalone. It layers on top of docker-compose.workshop.yml
-# (which defines the `backend`, `frontend`, `pg-trip-writer` services) and:
+# (which defines the base app and the profile-gated `pg-trip-writer`) and:
 #   - adds a ClickStack OpenTelemetry collector that forwards traces + logs to
 #     the participant's ClickHouse Cloud service,
 #   - turns on OpenTelemetry in the backend and points it at that collector,
@@ -34,8 +34,9 @@ services:
       - CLICKHOUSE_ENDPOINT=https://${CLICKHOUSE_HOST:-}:${CLICKHOUSE_PORT:-8443}
       - CLICKHOUSE_USER=${CLICKHOUSE_USER:-default}
       - CLICKHOUSE_PASSWORD=${CLICKHOUSE_PASSWORD:-}
-      # Arbitrary shared secret. Clients must send it back (see backend
-      # OTEL_EXPORTER_OTLP_HEADERS below). Leave empty to disable OTLP auth.
+      # Random shared secret. Clients must send it back (see backend
+      # OTEL_EXPORTER_OTLP_HEADERS below). Module 05 preflight rejects an empty
+      # or placeholder value.
       - OTLP_AUTH_TOKEN=${OTLP_AUTH_TOKEN:-}
       # Target database for ClickStack's own otel_* tables (distinct from the
       # app's data database, CLICKHOUSE_DATABASE=nyc_tlc_data).
@@ -51,8 +52,8 @@ services:
     ports:
       # Host mappings are only needed if you send OTLP from the host; the backend
       # reaches the collector in-network at http://otel-collector:4318.
-      - "${OTEL_GRPC_HOST_PORT:-4317}:4317"
-      - "${OTEL_HTTP_HOST_PORT:-4318}:4318"
+      - "127.0.0.1:${OTEL_GRPC_HOST_PORT:-4317}:4317"
+      - "127.0.0.1:${OTEL_HTTP_HOST_PORT:-4318}:4318"
 
   # Additive overlay onto the workshop `backend`: enable OpenTelemetry and point
   # it at the collector. Only env keys are added here; the service body comes