Skip to content
SHC Docs

The session-replay league: OpenReplay packaged, footprint verified

Status: RULED AND EXECUTED 2026-08-11: flagship: replay is applied. The body below is the 2026-08-06 packaging record, preserved as written; §5’s “OWNER DECISION REQUIRED” is answered in §0. Date: 2026-08-06.


The owner ruled OpenReplay into the session-replay league. §5 is the reason the label was withheld on 2026-08-06, and half of it was falsified the same day:

  • §5’s first bullet reads the flagship contract’s “the claimed SSO tier must be reachable WITHOUT a paid license” against an OpenReplay whose only SSO was EE-paywalled SAML2. That stopped being true in bd61d2ee3, committed hours after this doc: SHC runs an additive AGPL soft-fork of chalice that adds a native OIDC login router (community helpers only, no ee/ code read), the package ships oidc.plug.yaml, and vars.yaml pins chalice to the fork. Nobody pays for anything in this stack: LICENSE_KEY="", and the built artifact carries ENTERPRISE_BUILD=default-foss with the SAML router absent. The tension is resolved on the merits, not waived.
  • §5’s second bullet stands and is the reason no # flagship-userless: marker was written: OpenReplay HAS a user model, so that rung was never available and the label does not claim it. The SSO surface bar is satisfied the ordinary way, by an oidc.plug.yaml in the package.
  • §5’s third bullet (the label is owner-assigned) is satisfied by the ruling.

Access posture is unchanged: access: gated + ungated_paths: [/ingest/, /script/]. The app is now both gated and natively OIDC-capable, which is not a contradiction here the way it would be for huly or glitchtip: the reason a gate breaks a native-OIDC app is that it 401s a machine audience that cannot perform an SSO handshake, and OpenReplay’s machine audience, the tracker, is already carved out by those two prefixes. Everything left behind the gate is a human with a browser. OIDC_ENFORCE defaults false, so the password form remains the break-glass path and a misconfigured IdP cannot lock an estate out of its own instance.

One defect fixed in passing. apps/monitoring/openreplay/app.yaml’s ACCESS POSTURE block still read “OpenReplay does NOT ship an oidc.plug; it rides the gate”, which had been false since bd61d2ee3 while tests/tests.bats asserted the opposite. The package’s own documentation was arguing against its own shipped files. Rewritten to describe what is there.

The task allowed a refusal if OpenReplay’s self-host reality were k8s-only or otherwise untractable for a compose/swarm estate. It is not. This documents the footprint that was verified, why the decision is PACKAGE, the engineering choices, and what is verified vs assumed.


OpenReplay was historically Kubernetes-only (a k3s/helm installer). That is no longer the whole story:

  • A maintained docker-compose self-host exists. scripts/docker-compose/ in github.com/openreplay/openreplay (docs: docs.openreplay.com/en/deployment/deploy-docker). It is per-service version-pinned (common.env, v1.27.0) and actively maintained, but upstream labels it experimental and sized for low-traffic evaluation, not production (min 2 vCPU / 8 GB / 50 GB, x86).
  • The compose path is materially SIMPLER than the k8s path. Two heavy k8s dependencies are ABSENT from the compose stack:
    • No Kafka. The compose services depend only on postgres, redis, clickhouse and minio; the message bus is Valkey/Redis. KAFKA_SERVERS survives in the per-service env files as a vestigial, non-resolving leftover (upstream’s own compose points it at a kafka.db.svc.cluster.local name that exists in NEITHER their compose nor ours, and the documented install works, proof the images ignore it when Redis is the bus). We set it empty.
    • No Quickwit / no dedicated search tier in the compose path.
  • Backing stores: postgres 17, clickhouse (26.2-alpine upstream), Valkey (Redis 8), and an S3-compatible object store (upstream ships rustfs 1.0.0-beta.1; S3 is pluggable: “any S3-compatible storage”).
  • The application mesh is 17 microservices behind ONE internal nginx path router, itself behind a Caddy TLS terminator: alerts, api (Go v2), assets, assist, canvases, chalice (Python API), db, ender, frontend, heuristics, http (ingest), images, integrations, sink, sourcemapreader, spot, storage.
  • License: the monorepo is multi-license: core defaults to AGPLv3, the ee/ dir is a separate proprietary license, some dirs MIT. The CE images this package pins (public.ecr.aws/p1t3u8a3/*) are the AGPL build and ship LICENSE_KEY="". OpenReplay’s SSO (SAML/OIDC) is an EE feature gated behind that license key.

The refusal condition (k8s-only / untractable) does not hold. A maintained, version-pinned compose exists; the compose path drops the two hardest k8s dependencies (Kafka, Quickwit); the estate already has a proven analog (apps/highlight, a clickhouse+redis+s3 observability app) and the shared apps/clickhouse, apps/minio/apps/s3 and ce-builtin postgres stacks the package can consume. Packaging is tractable and honest.

3. What the package does: the estate substitutions

Section titled “3. What the package does: the estate substitutions”
  • Consumes the estate postgres, clickhouse and S3 sockets via conditional plugs (required: "{{ not vars.<x>.hostname/endpoint }}", mirroring highlight). No bundled copies of them.
  • Bundles only Valkey (the ingest bus + cache), the one component that genuinely cannot be externalized.
  • Drops Caddy: Traefik owns TLS and the forward-auth gate. The internal nginx router (service openreplay) is the single ingress.
  • Ships the two schema bootstraps (init_pg_schema.sql, init_ch_schema.sql, ~65 KB / ~51 KB) as bind-mounted app files applied by one-shot restart: "no" migration jobs (the apps/hyperswitch pattern). The PG schema self-guards (re-runs are a no-op).
  • nginx.conf is shipped as nginx.conf.template and rendered at container start by the official nginx image’s built-in envsubst-on-templates, injecting ${S3_UPSTREAM} (the S3 socket endpoint), the only way to get a dynamic value into a config file, since SHC ships bind-mounted files verbatim (un-templated).
  • All 21 images digest-pinned (17 OpenReplay ECR-public services hashed from their manifests on 2026-08-06 + valkey/nginx/pgclient/clickhouse-client reused from known-good catalog pins).
  • backup.yaml is stack-scoped: OpenReplay’s own stack holds no durable data (only the ephemeral scratch + bus volumes, both excluded); postgres/clickhouse/ S3 back themselves up and ride shc backup create --all-connected.

4. Access posture: gated, not native-OIDC (owner memo)

Section titled “4. Access posture: gated, not native-OIDC (owner memo)”

SUPERSEDED 2026-08-23: this app is now access: open. The owner ruled that partial gating is not a posture the platform offers: “there is no such thing as partial gating. its either public or not. if part of it needs to be public then you make it all public and let the app handle security.” The gate and the ungated_paths carve-out described below are both gone. OpenReplay’s own login, JWTs and per-project keys are the security now. Two things this section got right still hold and are worth reading for: why the tracker audience could never pass a gate, and that the AGPL soft-fork rather than the gate settled the package’s SSO question. apps/flagship/openreplay/app.yaml carries the current posture, and migration-files/seed_owner.sql carries the seed that closes OpenReplay’s own open first-run signup now that the host is public.

OpenReplay’s SSO is EE-paywalled, so access: gated: the Keycloak forward-auth gate fronts the dashboard, and the package ships no oidc.plug. The load-bearing subtlety is ungated_paths: [/ingest/, /script/]; the tracker runs in end-user browsers NOT authenticated to Keycloak and POSTs to /ingest/ (its own project-key + JWT auth); gating the whole host would 401 every session and capture nothing.

5. The flagship-label tension: OWNER DECISION REQUIRED

Section titled “5. The flagship-label tension: OWNER DECISION REQUIRED”

The task frames OpenReplay as “the owner-ruled session-replay flagship,” but the flagship contract shipped the SAME day (docs/decisions/2026-08-06-flagship-tier.md) would, read literally, REJECT the label, for the identical reason it ruled highlight out of the errors league (§7 of that doc):

  • §1.1: the claimed SSO tier “must be reachable WITHOUT a paid license.” An app whose SSO is paywalled “cannot claim any rung by paying.” OpenReplay’s SSO is EE-gated. → the free-SSO rung is unavailable.
  • The userless-but-gated rung is also unavailable. It requires “no user model upstream.” OpenReplay HAS its own email/password login, so a # flagship-userless: marker would be factually FALSE; writing one to pass the grep is exactly the “routing accident vs documented decision” failure the contract warns against.
  • §2 / §6: the label is owner-assigned; “an app PR must not add or move a flagship: key without an owner ruling,” and the shipped state is “zero apps labeled.”

This package therefore does NOT add flagship: replay. It is built to the flagship mechanical floor (backup.yaml ✓, tests.bats ✓, digest-pinned ✓, estate-citizen plugs ✓) so the owner can add the key in a one-line commit IF they choose to override the highlight precedent for replay tools (the memo’s “replay tools sit behind the gate” posture accepts the double-credentialing that highlight was dinged for). Recommendation: owner reconciles the precedent and assigns (or withholds) the label; the package is ready either way.

Verified (in this session):

  • The compose footprint above (fetched from upstream main: the compose file, all 17 per-service env files, common.env, both migration SQL files, nginx.conf, install.sh/run.sh, LICENSE).
  • No Kafka / no Quickwit in the compose path; Redis is the bus.
  • License posture (AGPL core, EE-gated SSO, LICENSE_KEY="").
  • All 21 image digests resolved.
  • validate-templates clean (375/375 apps, incl. openreplay’s 7 templated files); scripts/arch-fitness.sh exit 0; shfmt -d -i 4 -ci clean on the bats.

Assumed / owed a live proof (NO from-empty deploy was run; the estate is where this gets proven, consistent with the flagship doc’s finding that NO candidate has a zero-touch proof today):

  • That the CE images tolerate KAFKA_SERVERS="" and use Redis as the bus (strong circumstantial evidence from upstream’s working compose; not executed here).
  • S3 presigning-behind-proxy: chalice presigns browser URLs against the app domain and nginx forwards Host to the estate S3; this works in upstream’s bundled-minio setup, but was not proven against the estate S3 socket.
  • The sessions-assets public-read policy: upstream’s installer sets an anonymous-download policy on that bucket; the generic s3 socket creates buckets but sets no per-bucket policy, so asset serving may need a one-time public-read grant on the estate S3 (noted in s3.plug.yaml).
  • Per-service healthchecks for the 17 Go/Python microservices are deliberately OMITTED (matching upstream, which healthchecks only the datastores): their images’ shell/port tooling is unverified, and a false-unhealthy check would abort docker compose up --wait. Only valkey and nginx are healthchecked. This is an honest-health gap for the flagship “real healthchecks on every service” bar, documented, not faked.
  • Memory limits are from OpenReplay’s own sizing doc + per-service judgment (~8 GB total, matching upstream’s stated minimum), NOT individually measured.
  • The /script/ route proxies the tracker bundle from OpenReplay’s public CDN, a client-side external dependency preserved as upstream ships it (the server never fetches it).