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.
0. RESOLUTION: 2026-08-11
Section titled “0. RESOLUTION: 2026-08-11”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, noee/code read), the package shipsoidc.plug.yaml, andvars.yamlpins chalice to the fork. Nobody pays for anything in this stack:LICENSE_KEY="", and the built artifact carriesENTERPRISE_BUILD=default-fosswith 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 anoidc.plug.yamlin 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.
1. The self-host footprint: VERIFIED
Section titled “1. The self-host footprint: VERIFIED”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/ingithub.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_SERVERSsurvives in the per-service env files as a vestigial, non-resolving leftover (upstream’s own compose points it at akafka.db.svc.cluster.localname 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.
- No Kafka. The compose services depend only on postgres, redis, clickhouse
and minio; the message bus is Valkey/Redis.
- Backing stores: postgres 17, clickhouse (26.2-alpine upstream), Valkey
(Redis 8), and an S3-compatible object store (upstream ships
rustfs1.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 shipLICENSE_KEY="". OpenReplay’s SSO (SAML/OIDC) is an EE feature gated behind that license key.
2. Decision: PACKAGE
Section titled “2. Decision: PACKAGE”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-shotrestart: "no"migration jobs (theapps/hyperswitchpattern). The PG schema self-guards (re-runs are a no-op). - nginx.conf is shipped as
nginx.conf.templateand 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 theungated_pathscarve-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.yamlcarries the current posture, andmigration-files/seed_owner.sqlcarries 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.
6. Verified vs assumed
Section titled “6. Verified vs assumed”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-templatesclean (375/375 apps, incl. openreplay’s 7 templated files);scripts/arch-fitness.shexit 0;shfmt -d -i 4 -ciclean 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
Hostto the estate S3; this works in upstream’s bundled-minio setup, but was not proven against the estate S3 socket. - The
sessions-assetspublic-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 ins3.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).