chore: improve s2-lite local-dev onboarding

Three small papercuts hitting new contributors:

1. .env.example was silent on realtime-streams S2 config, so fresh clones
   defaulted to v1 (Redis-only) streams and Sessions / chat.agent failed
   with "S2 configuration is missing". The `s2` service in compose
   pre-seeds a `trigger-local` basin (see docker/config/s2-spec.json) —
   wire the env vars to it by default.

2. The s2 healthcheck shelled `wget` on a distroless image, so docker
   always reported it unhealthy even when the API was live. Drop it; no
   service depends on s2.

3. Two clones could not run docker side by side: ports, project name,
   and container names were all hardcoded. Parameterize host ports with
   `${VAR:-default}`, drive the project name via `COMPOSE_PROJECT_NAME`
   (with a `name:` field for backward compat), prefix container names
   with `${CONTAINER_PREFIX:-}`, and pass `--env-file .env` so compose
   reads the same root `.env` the webapp does.

Also split the optional services (electric-shard-1, ch-ui, toxiproxy,
nginx-h2, otel-collector, prometheus, grafana) into
docker-compose.extras.yml + a `docker:full` pnpm script. The core stack
keeps everything the webapp actually needs (postgres, redis, electric,
minio, clickhouse + migrator, s2-lite).

Author: ericallam

.env.example

@@ -29,6 +29,52 @@ REDIS_TLS_DISABLED="true"
 DEV_OTEL_EXPORTER_OTLP_ENDPOINT="http://localhost:3030/otel"
 DEV_OTEL_BATCH_PROCESSING_ENABLED="0"
 
+# Realtime streams v2 (Sessions, chat.agent, large stream backfills) backed
+# by S2 (https://s2.dev). The `s2` service in docker/docker-compose.yml runs
+# the open-source s2-lite binary and pre-creates a basin named `trigger-local`
+# (see docker/config/s2-spec.json). Comment these out to fall back to v1
+# (Redis-only) streams; Sessions and chat.agent then become unavailable.
+REALTIME_STREAMS_S2_BASIN=trigger-local
+REALTIME_STREAMS_S2_ACCESS_TOKEN=ignored
+REALTIME_STREAMS_S2_ENDPOINT=http://localhost:4566/v1
+REALTIME_STREAMS_S2_SKIP_ACCESS_TOKENS=true
+REALTIME_STREAMS_DEFAULT_VERSION=v2
+
+# Running multiple instances side by side (worktrees, branch experiments)
+#
+# Every host port in docker/docker-compose.yml is `${VAR:-default}` and the
+# project name comes from `COMPOSE_PROJECT_NAME`. To stand up a second stack
+# alongside the default one, uncomment the block below in this clone's `.env`
+# (pick any offset that doesn't clash with anything else running), then update
+# the URL/PORT vars further up to match. Default values are commented for
+# reference.
+#
+# --- core (pnpm run docker) ---
+# COMPOSE_PROJECT_NAME=triggerdotdev-docker-alt
+# CONTAINER_PREFIX=alt-
+# POSTGRES_HOST_PORT=15432           # default 5432
+# REDIS_HOST_PORT=16379              # default 6379
+# ELECTRIC_HOST_PORT=13060           # default 3060
+# MINIO_API_HOST_PORT=19005          # default 9005
+# MINIO_CONSOLE_HOST_PORT=19006      # default 9006
+# CLICKHOUSE_HTTP_HOST_PORT=18123    # default 8123
+# CLICKHOUSE_TCP_HOST_PORT=19000     # default 9000
+# S2_HOST_PORT=14566                 # default 4566
+# REMIX_APP_PORT=13030               # default 3030
+# --- extras (only needed if you also run `pnpm run docker:full`) ---
+# ELECTRIC_SHARD_1_HOST_PORT=13061   # default 3061
+# CH_UI_HOST_PORT=15521              # default 5521
+# TOXIPROXY_PROXY_HOST_PORT=40303    # default 30303
+# TOXIPROXY_API_HOST_PORT=18474      # default 8474
+# NGINX_H2_HOST_PORT=18443           # default 8443
+# OTEL_GRPC_HOST_PORT=14317          # default 4317
+# OTEL_HTTP_HOST_PORT=14318          # default 4318
+# OTEL_PROMETHEUS_HOST_PORT=18889    # default 8889
+# PROMETHEUS_HOST_PORT=19090         # default 9090
+# GRAFANA_HOST_PORT=13001            # default 3001
+# (and update DATABASE_URL / CLICKHOUSE_URL / REDIS_PORT / APP_ORIGIN /
+#  LOGIN_ORIGIN / ELECTRIC_ORIGIN / REALTIME_STREAMS_S2_ENDPOINT to match)
+
 # When the domain is set to `localhost` the CLI deploy command will only --load the image by default and not --push it
 DEPLOY_REGISTRY_HOST=localhost:5000
 
@@ -106,7 +152,7 @@ POSTHOG_PROJECT_KEY=
 # INTERNAL_OTEL_TRACE_LOGGING_ENABLED=1
 # INTERNAL_OTEL_TRACE_INSTRUMENT_PRISMA_ENABLED=0
 
-# Enable local observability stack (requires `pnpm run docker` to start otel-collector)
+# Enable local observability stack (requires `pnpm run docker:full` to bring up otel-collector + prometheus + grafana)
 # Uncomment these to send metrics to the local Prometheus via OTEL Collector:
 # INTERNAL_OTEL_METRIC_EXPORTER_ENABLED=1
 # INTERNAL_OTEL_METRIC_EXPORTER_URL=http://localhost:4318/v1/metrics

AGENTS.md

@@ -19,6 +19,7 @@ See `ai/references/repo.md` for a more complete explanation of the workspaces.
    ```bash
    pnpm run docker
    ```
+   Add `:full` (`pnpm run docker:full`) for the optional observability + chaos tooling. See `docker/docker-compose.extras.yml`.
 4. Run database migrations:
    ```bash
    pnpm run db:migrate

CLAUDE.md

@@ -9,7 +9,8 @@ This is a pnpm 10.33.2 monorepo using Turborepo. Run commands from root with `pn
 **Adding dependencies:** Edit `package.json` directly instead of using `pnpm add`, then run `pnpm i` from the repo root. See `.claude/rules/package-installation.md` for the full process.
 
 ```bash
-pnpm run docker              # Start Docker services (PostgreSQL, Redis, Electric)
+pnpm run docker              # Core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite)
+# pnpm run docker:full       # Same + observability stack (Prometheus, Grafana, OTEL) and chaos tooling
 pnpm run db:migrate           # Run database migrations
 pnpm run db:seed              # Seed the database (required for reference projects)
 

CONTRIBUTING.md

@@ -71,12 +71,14 @@ branch are tagged into a release periodically.
 
    Feel free to update `SESSION_SECRET` and `MAGIC_LINK_SECRET` as well using the same method.
 
-8. Start Docker. This starts the required services: Postgres, Redis, Electric, and ClickHouse (the ClickHouse migrator runs once on first start). If this is your first time using Docker, consider going through this [guide](DOCKER_INSTALLATION.md).
+8. Start Docker. This starts the core dev services (Postgres, Redis, Electric, MinIO, ClickHouse, s2-lite) and runs the ClickHouse migrator once on first start. If this is your first time using Docker, consider going through this [guide](DOCKER_INSTALLATION.md).
 
    ```
    pnpm run docker
    ```
 
+   For the observability stack (Prometheus, Grafana, OTEL collector) and other optional tooling (Toxiproxy, nginx-h2, ch-ui, extra electric shard), use `pnpm run docker:full` instead. See `docker/docker-compose.extras.yml` for the full list.
+
 9. Migrate the database
    ```
    pnpm run db:migrate
@@ -300,3 +302,7 @@ The process running on port `3030` should be destroyed.
    ```sh
    sudo kill -9 <PID>
    ```
+
+### Running two clones side by side (worktree, branch experiment)
+
+The default `pnpm run docker` uses the project name `triggerdotdev-docker` and the standard host ports (5432, 6379, 3060, 4566, 8123, 9000, 9005, 9006). To stand up a second instance in another clone without clashing, set a different `COMPOSE_PROJECT_NAME` and the offset host ports in that clone's `.env`. The "Running multiple instances side by side" block in `.env.example` lists every overridable env var with its default for reference; uncomment the lines you need and update `DATABASE_URL` / `CLICKHOUSE_URL` / `REDIS_PORT` / `APP_ORIGIN` / `LOGIN_ORIGIN` / `ELECTRIC_ORIGIN` / `REALTIME_STREAMS_S2_ENDPOINT` to match.

docker/docker-compose.extras.yml

@@ -0,0 +1,122 @@
+# Optional services for advanced local-dev workflows. Pair with
+# `docker-compose.yml` via `pnpm run docker:full`.
+#
+# Same `name:` so `docker compose` treats both files as one project — bring
+# them up together and they share the `app_network` and `triggerdotdev-docker`
+# volume namespace. Tear down with `pnpm run docker:full:stop`.
+#
+# Includes:
+#   - electric-shard-1:   second Electric instance for multi-shard testing
+#   - ch-ui:              ClickHouse browser UI
+#   - toxiproxy:          chaos / flake testing
+#   - nginx-h2:           HTTP/2 reverse proxy
+#   - otel-collector + prometheus + grafana: observability stack
+name: triggerdotdev-docker
+
+volumes:
+  prometheus-data:
+  grafana-data:
+
+networks:
+  app_network:
+    external: false
+
+services:
+  electric-shard-1:
+    container_name: ${CONTAINER_PREFIX:-}electric-shard-1
+    image: electricsql/electric:1.2.4@sha256:20da3d0b0e74926c5623392db67fd56698b9e374c4aeb6cb5cadeb8fea171c36
+    restart: always
+    environment:
+      DATABASE_URL: postgresql://postgres:postgres@database:5432/postgres?sslmode=disable
+      ELECTRIC_INSECURE: true
+      ELECTRIC_REPLICATION_STREAM_ID: "triggershard1"
+    networks:
+      - app_network
+    ports:
+      - "${ELECTRIC_SHARD_1_HOST_PORT:-3061}:3000"
+    depends_on:
+      - database
+
+  ch-ui:
+    image: ghcr.io/caioricciuti/ch-ui:latest
+    restart: always
+    ports:
+      - "${CH_UI_HOST_PORT:-5521}:5521"
+    environment:
+      VITE_CLICKHOUSE_URL: "http://localhost:${CLICKHOUSE_HTTP_HOST_PORT:-8123}"
+      VITE_CLICKHOUSE_USER: "default"
+      VITE_CLICKHOUSE_PASS: "password"
+    networks:
+      - app_network
+
+  toxiproxy:
+    container_name: ${CONTAINER_PREFIX:-}toxiproxy
+    image: ghcr.io/shopify/toxiproxy:latest
+    restart: always
+    volumes:
+      - ./config/toxiproxy.json:/config/toxiproxy.json
+    ports:
+      - "${TOXIPROXY_PROXY_HOST_PORT:-30303}:30303" # Proxied webapp port
+      - "${TOXIPROXY_API_HOST_PORT:-8474}:8474" # Toxiproxy API port
+    networks:
+      - app_network
+    command: ["-host", "0.0.0.0", "-config", "/config/toxiproxy.json"]
+
+  nginx-h2:
+    image: nginx:1.27
+    container_name: ${CONTAINER_PREFIX:-}nginx-h2
+    restart: unless-stopped
+    ports:
+      - "${NGINX_H2_HOST_PORT:-8443}:8443"
+    volumes:
+      - ./config/nginx.conf:/etc/nginx/nginx.conf:ro
+      - ./config/certs:/etc/nginx/certs:ro
+
+  # Observability stack for local development
+  otel-collector:
+    container_name: ${CONTAINER_PREFIX:-}otel-collector
+    image: otel/opentelemetry-collector-contrib:0.96.0
+    restart: always
+    command: ["--config", "/etc/otel-collector-config.yaml"]
+    volumes:
+      - ./config/otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
+    ports:
+      - "${OTEL_GRPC_HOST_PORT:-4317}:4317" # OTLP gRPC receiver
+      - "${OTEL_HTTP_HOST_PORT:-4318}:4318" # OTLP HTTP receiver
+      - "${OTEL_PROMETHEUS_HOST_PORT:-8889}:8889" # Prometheus exporter
+    networks:
+      - app_network
+
+  prometheus:
+    container_name: ${CONTAINER_PREFIX:-}prometheus
+    image: prom/prometheus:v2.54.1
+    restart: always
+    volumes:
+      - ./config/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+      - prometheus-data:/prometheus
+    ports:
+      - "${PROMETHEUS_HOST_PORT:-9090}:9090"
+    networks:
+      - app_network
+    command:
+      - "--config.file=/etc/prometheus/prometheus.yml"
+      - "--storage.tsdb.path=/prometheus"
+      - "--web.enable-lifecycle"
+
+  grafana:
+    container_name: ${CONTAINER_PREFIX:-}grafana
+    image: grafana/grafana:11.3.0
+    restart: always
+    volumes:
+      - grafana-data:/var/lib/grafana
+      - ./config/grafana/provisioning:/etc/grafana/provisioning:ro
+    ports:
+      - "${GRAFANA_HOST_PORT:-3001}:3000"
+    environment:
+      GF_SECURITY_ADMIN_USER: admin
+      GF_SECURITY_ADMIN_PASSWORD: admin
+      GF_USERS_ALLOW_SIGN_UP: false
+    networks:
+      - app_network
+    depends_on:
+      - prometheus