stack/docker/dependencies/docker.compose.yaml
BilalG1 f7e389809e
Some checks failed
all-good: Did all the other checks pass? / all-good (push) Has been cancelled
Ensure Prisma migrations are in sync with the schema / check_prisma_migrations (22.x) (push) Has been cancelled
DB migration compat / Check if migrations changed (push) Has been cancelled
Docker Server Build and Push / Docker Build and Push Server (push) Has been cancelled
Docker Server Build and Run / docker (push) Has been cancelled
Runs E2E API Tests (Local Emulator) / E2E Tests (Local Emulator, Node ${{ matrix.node-version }}) (22.x) (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (mock, 22.x) (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (prod, 22.x) (push) Has been cancelled
Runs E2E API Tests with custom port prefix / build (22.x) (push) Has been cancelled
Runs E2E Fallback Tests / E2E Fallback Tests (Node ${{ matrix.node-version }}) (22.x) (push) Has been cancelled
Lint & build / lint_and_build (24) (push) Has been cancelled
TOC Generator / TOC Generator (push) Has been cancelled
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
DB migration compat / No migration changes (skipped) (push) Has been cancelled
feat(hexclave): PR 1 — wire compatibility layer (invisible) (#1475)
## Summary

**Stacked on #1468** (`docs/hexclave-rename-plan` — the plan doc). Diff
vs that base = the actual PR 1 code.

This is **PR 1 of the Hexclave rebrand: the invisible compatibility
layer**. Everything is additive. Old SDKs, old wire identifiers, and old
env var names keep working unchanged. The backend dual-accepts and
dual-emits; new SDK code emits `x-hexclave-*` headers and the
`hexclave_` Bearer prefix; cookies dual-write; env vars dual-read across
every category. **No user-visible rebranding lands here** — that's PR 2.

See [`RENAME-TO-HEXCLAVE.md`](./RENAME-TO-HEXCLAVE.md) → *"PR 1
implementation guide"* for the full per-work-area spec, file pointers,
and chosen approach.

## What's implemented (all 14 PR-1 work-areas)

- **SDK export aliases** — `Hexclave*` aliases for the user-facing
`Stack*` exports added in `packages/template`; codegen propagates them
to `@stackframe/{js,stack,react,tanstack-start}`. React-only aliases
correctly excluded from `@stackframe/js`. (`e60550a2`)
- **JWT issuer dual-accept** — `decodeAccessToken` accepts both
`api.stack-auth.com` and `api.hexclave.com` issuers. Signing unchanged.
(`fc781def`)
- **Request-header dual-accept** — backend + dashboard proxies normalize
`x-hexclave-*` → `x-stack-*` at the existing empty proxy hook (so
`smart-request.tsx` and every route schema keep working unchanged); CORS
allowlists extended via a derive-once helper. (`2a056eac`)
- **MCP `ask_hexclave`** — registered alongside `ask_stack_auth` via a
shared helper; `ask_stack_auth` behavior byte-identical. (`30ffd604`)
- **Dev-tool** — DOM ids + header emit switched.
`window.HexclaveDevTool` exposed alongside `window.StackDevTool`.
(`32131ea7`)
- **The big consolidated commit** (`7fed864a`):
- **Env vars** — central `getEnvVariable` prefix-transform (HEXCLAVE
first, STACK fallback); dashboard + template client env files dual-read;
`turbo.json` globalEnv; `NEXT_PUBLIC_STACK_PORT_PREFIX` renamed outright
across ~82 files including docker.
- **Cookies** — dual-write/dual-read auth (`stack-access`/`-refresh-*`
and custom-domain variants), OAuth-state
(`stack-oauth-{inner,outer}-*`), and low-risk cookies (`stack-is-https`,
`stack-last-seen-changelog-version`). Bypass sites patched (backend
OAuth callback, dashboard remote-dev auth route, impersonation snippets,
snapshot serializer).
- **Bearer prefix** — SDK token parser accepts both `stackauth_` and
`hexclave_`; emits `hexclave_`. Discovery correction: this is purely
SDK-internal — the backend never parses it.
- **Response headers** — backend dual-emits
`x-hexclave-{request-id,actual-status,known-error}`; SDKs dual-read (new
first, stack fallback).
- **SDK request-header emit switch** —
`client/server/admin-interface.ts` + dashboard `api-headers.ts` +
`internal-project-headers.ts` + `feedback-form.tsx` switched to
`x-hexclave-*`. Plus `stack_response_mode` query param.
- **Storage keys** — dev-tool / cli-auth / oauth-button / docs keys
renamed (straight); `stack:session-replay:v1` dual-read so in-progress
recordings survive SDK upgrades; `stack_mfa_attempt_code` dual-read.
- **Query params** — cross-domain params dual-emit/dual-accept via
shared helpers; backend `oauth/authorize` accepts
`hexclave_response_mode` and `stack_response_mode`; `stack-init-id`
renamed.
- **`Symbol.for`** — app-internals symbol gets a parallel
`Symbol.for("Hexclave--app-internals")` getter on each attach site (no
read-site churn — old symbol still attached). 3 file-private symbols
renamed outright.
- **Config discovery** — prefer `hexclave.config.ts`, fall back to
`stack.config.ts` at every discovery site (CLI / dashboard / backend /
local-emulator); `init` writes the new filename; CLI credentials path
migrates.
- **Internal renames** — `StackAssertionError`,
`StackClient/Server/AdminInterface` renamed outright (no alias, per the
"internal-only → rename" rule). ~264 files touched.
- **Review-pass fixes** (`21217fbe`) — three real bugs found by parallel
review agents and fixed:
- `snapshot-serializer.ts` was interpolating the whole
`keyedCookieNamePrefixes` array (`${arr}`) — adding a second prefix
would have corrupted **every** OAuth-cookie snapshot, not just new ones.
- **Docker port-prefix producer/consumer mismatch** —
`entrypoint.sh`/`run-emulator.sh`/cloud-init `user-data` were still
producing `NEXT_PUBLIC_STACK_PORT_PREFIX` while the dashboard sentinel +
consumers had been renamed; silent self-host regression (custom port
prefix would be ignored).
- **Missing `hexclave-oauth-inner-*` dual-write** in the OAuth authorize
route — callback's fallback masked it but the dual-write was specified
by the plan.
- Plus: `mcp.test.ts` tool-list assertions updated to include
`ask_hexclave`; two dashboard header-emit sites switched to
`x-hexclave-*` for consistency.
- **E2E snapshot serializer follow-up** (`4b16cc5d`) —
`x-hexclave-request-id` added to the hidden-headers list (mirroring
`x-stack-request-id` treatment), and 2 sample inline snapshots
regenerated in `projects.test.ts` to include the new dual-emitted
headers.

## Verification

- **`pnpm typecheck`** — clean (the fresh-worktree `@/.source` / Prisma
codegen gap in `stack-docs` is pre-existing and unrelated).
- **`pnpm lint`** — 29/29 packages green.
- **`pnpm exec turbo run build --filter=./packages/*`** — 13/13 packages
build (including `@stackframe/stack-cli` once the dashboard standalone
is present).
- **Live E2E** against a running backend on `cl/hexclave-pr1`:
- `pnpm test run
apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts` — **6/6
pass** (verifies the new `ask_hexclave` tool — the hand-written inline
snapshot matched actual MCP server output).
- `pnpm test run
apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts` —
**11/11 pass** (verifies wire dual-accept + dual-emit end-to-end; the
snapshot serializer fix was found and applied during this check).

A four-agent parallel **review pass** also audited the full diff for
logic/runtime bugs across the work-areas (wire headers + JWT, cookies +
bearer + symbols, env vars, query params + config + MCP + aliases). All
in-slice review verdicts were ✓ except the three bugs listed above,
which are now fixed.

## Known follow-ups (out of scope for this PR)

- **E2E snapshots across the rest of the suite** — backend now
dual-emits `x-hexclave-{known-error,actual-status}` alongside
`x-stack-*`, which legitimately appears in inline snapshots throughout
`apps/e2e`. Two were regenerated here as a sample; the rest should regen
with `vitest -u` in CI.
- **Docker shell env vars beyond `PORT_PREFIX`** — `entrypoint.sh` still
reads `STACK_*` env vars directly (the JS-side `getEnvVariable`
transform doesn't help the shell). JS consumers dual-read so it works in
practice; full shell-level dual-read is a deeper self-host follow-up.
- **`@stackframe/stack-cli` build ordering** — pre-existing; needs
`build:rde-standalone` first. Not affected by this PR.

## Test plan

- [ ] CI runs full e2e suite (with `vitest -u` to absorb dual-emit
snapshot deltas, then committed back)
- [ ] Spot-check: an old SDK build (emitting only `x-stack-*`) still
authenticates against the new backend
- [ ] Spot-check: a new SDK (emitting `x-hexclave-*` / `Bearer
hexclave_*`) still authenticates against an old backend during deploy
ordering
- [ ] Manual: `npx @stackframe/stack-cli@latest init` (new onboarding
entrypoint) generates `hexclave.config.ts`
- [ ] Manual: existing `stack.config.ts`-only project still resolves (no
migration required)

---------

Co-authored-by: bilal <bilal@stack-auth.com>
2026-05-23 17:24:55 -07:00

348 lines
9.9 KiB
YAML

services:
# ================= PostgreSQL =================
db:
build: ../dev-postgres-with-extensions
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
# Note: A readonly user is also created with password PASSWORD-PLACEHOLDER--readonlyuqfEC1hmmv
# for read replica emulation. See the Dockerfile for details.
POSTGRES_DB: stackframe
POSTGRES_DELAY_MS: ${POSTGRES_DELAY_MS:-0}
POSTGRES_INITDB_ARGS: --nosync
# Increase max_connections for E2E tests that create many databases
command: postgres -c max_connections=500
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}28:5432"
volumes:
- postgres-data:/var/lib/postgresql/data
cap_add:
- NET_ADMIN # required for the fake latency during dev
# ================= PostgreSQL Replica (with replication lag) =================
db-replica:
build: ../dev-postgres-replica
environment:
PGDATA: /var/lib/postgresql/data
PRIMARY_HOST: db
PRIMARY_PORT: 5432
REPLICATOR_USER: replicator
REPLICATOR_PASSWORD: PASSWORD-PLACEHOLDER--replicatorpass
RECOVERY_MIN_APPLY_DELAY: ${STACK_DATABASE_REPLICA_LAG_MS:-15}ms
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}34:5432"
volumes:
- postgres-replica-data:/var/lib/postgresql/data
depends_on:
- db
# ================= PgHero =================
pghero:
image: ankane/pghero:latest
environment:
DATABASE_URL: postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@db:5432/stackframe
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}16:8080"
# ================= WAL Info =================
wal-info:
build: ./wal-info
environment:
PRIMARY_HOST: db
PRIMARY_PORT: 5432
REPLICA_HOST: db-replica
REPLICA_PORT: 5432
POSTGRES_USER: postgres
POSTGRES_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
POSTGRES_DB: stackframe
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}38:8080"
depends_on:
- db
- db-replica
# ================= PgHero (Replica) =================
pghero-replica:
image: ankane/pghero:latest
environment:
DATABASE_URL: postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@db-replica:5432/stackframe
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}35:8080"
depends_on:
- db-replica
# ================= PgAdmin =================
pgadmin:
image: dpage/pgadmin4
environment:
PGADMIN_DEFAULT_EMAIL: admin@example.com
PGADMIN_DEFAULT_PASSWORD: PASSWORD-PLACEHOLDER--vu9p2iy3f
PGADMIN_CONFIG_SERVER_MODE: "False"
PGADMIN_CONFIG_MASTER_PASSWORD_REQUIRED: "False"
configs:
- source: pgadmin_servers
target: /pgadmin4/servers.json
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}17:80"
# ================= Supabase Studio =================
supabase-studio:
image: supabase/studio:20241202-71e5240
restart: unless-stopped
healthcheck:
test:
[
"CMD",
"node",
"-e",
"fetch('http://studio:3000/api/profile').then((r) => {if (r.status !== 200) throw new Error(r.status)})"
]
timeout: 10s
interval: 5s
retries: 3
environment:
STUDIO_PG_META_URL: http://supabase-meta:8080
POSTGRES_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
OPENAI_API_KEY: ${OPENAI_API_KEY:-}
NEXT_PUBLIC_ENABLE_LOGS: true
NEXT_ANALYTICS_BACKEND_PROVIDER: postgres
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}18:3000"
supabase-meta:
image: supabase/postgres-meta:v0.84.2
restart: unless-stopped
environment:
PG_META_PORT: 8080
PG_META_DB_HOST: db
PG_META_DB_PORT: 5432
PG_META_DB_NAME: stackframe
PG_META_DB_USER: postgres
PG_META_DB_PASSWORD: PASSWORD-PLACEHOLDER--uqfEC1hmmv
# ================= Inbucket =================
inbucket:
image: inbucket/inbucket:3.1.0
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}29:2500"
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}05:9000"
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}30:1100"
volumes:
- inbucket-data:/data
# ================= OpenTelemetry & Jaeger =================
jaeger:
image: jaegertracing/all-in-one:latest
environment:
- COLLECTOR_OTLP_ENABLED=true
- MEMORY_MAX_TRACES=50000
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}07:16686" # Jaeger UI
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}31:4318" # OTLP Endpoint
mem_limit: 1g
restart: always
# ================= svix =================
svix-db:
image: "docker.io/postgres:16.1"
environment:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: PASSWORD-PLACEHOLDER--KsoIMcchtp
POSTGRES_DB: svix
volumes:
- svix-postgres-data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -p 5432 -d svix"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
svix-redis:
image: docker.io/redis:7-alpine
command: --save 60 500 --appendonly yes --appendfsync everysec --requirepass PASSWORD-PLACEHOLDER--oVn8GSD6b9
volumes:
- svix-redis-data:/data
healthcheck:
test: ["CMD-SHELL", "redis-cli ping"]
interval: 10s
timeout: 5s
retries: 5
start_period: 10s
svix-server:
image: svix/svix-server
environment:
WAIT_FOR: 'true'
SVIX_REDIS_DSN: redis://:PASSWORD-PLACEHOLDER--oVn8GSD6b9@svix-redis:6379
SVIX_DB_DSN: postgres://postgres:PASSWORD-PLACEHOLDER--KsoIMcchtp@svix-db:5432/svix
SVIX_CACHE_TYPE: memory
SVIX_JWT_SECRET: secret
SVIX_LOG_LEVEL: trace
SVIX_QUEUE_TYPE: redis
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}13:8071"
depends_on:
svix-redis:
condition: service_healthy
svix-db:
condition: service_healthy
# ================= Adobe S3 Mock =================
s3mock:
image: adobe/s3mock:4.12.2
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}21:9090"
environment:
- initialBuckets=stack-storage,stack-storage-private
- root=s3mockroot
- debug=false
volumes:
- s3mock-data:/tmp/s3mock
healthcheck:
test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:9090/"]
interval: 30s
timeout: 10s
retries: 3
# ================= LocalStack =================
localstack:
image: localstack/localstack:4.7
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}24:4566" # LocalStack Gateway
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}50-${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}99:4510-4559" # external services port range
environment:
# LocalStack configuration: https://docs.localstack.cloud/references/configuration/
- DEBUG=${DEBUG:-0}
volumes:
- localstack-data:/var/lib/localstack
- "/var/run/docker.sock:/var/run/docker.sock"
# ================= Freestyle mock =================
freestyle-mock:
build:
context: ./freestyle-mock
dockerfile: Dockerfile
image: freestyle-mock
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}22:8080" # POST http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}19/execute/v1/script
extra_hosts:
- "host.docker.internal:host-gateway" # noop on Docker Desktop/Orbstack, enables host.docker.internal on Linux
environment:
DENO_DIR: /deno-cache
HOST_ON_HOST: host.docker.internal
volumes:
- deno-cache:/deno-cache
# ================= Stripe =================
stripe-mock:
image: stripe/stripe-mock:v0.195.0
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}23:12111"
environment:
- STRIPE_API_KEY=sk_test_1234567890
# ================= QStash =================
qstash:
image: bgodil/qstash:latest
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}25:8080"
command: qstash dev
extra_hosts:
- "host.docker.internal:host-gateway" # noop on Docker Desktop/Orbstack, enables host.docker.internal on Linux
environment:
HOST_ON_HOST: host.docker.internal
# ================= ClickHouse =================
clickhouse:
image: clickhouse/clickhouse-server:25.10
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}36:8123" # HTTP interface
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}37:9000" # Native interface
environment:
CLICKHOUSE_DB: analytics
CLICKHOUSE_USER: stackframe
CLICKHOUSE_PASSWORD: PASSWORD-PLACEHOLDER--9gKyMxJeMx
CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT: 1
volumes:
- clickhouse-data:/var/lib/clickhouse
ulimits:
nofile:
soft: 262144
hard: 262144
# ================= SpacetimeDB =================
spacetimedb:
image: clockworklabs/spacetime:v2.1.0
pull_policy: always
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}39:3000"
command: start
# ================= Drizzle Gateway =================
drizzle-gateway:
image: ghcr.io/drizzle-team/gateway:latest
restart: always
ports:
- "${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}33:1133"
environment:
PORT: 1133
STORE_PATH: /app
volumes:
- drizzle-gateway:/app
# ================= volumes =================
volumes:
postgres-data:
postgres-replica-data:
inbucket-data:
svix-redis-data:
svix-postgres-data:
s3mock-data:
deno-cache:
localstack-data:
clickhouse-data:
drizzle-gateway:
# ================= configs =================
configs:
pgadmin_servers:
content: |
{
"Servers": {
"1": {
"Name": "Local Postgres DB",
"Group": "Servers",
"Host": "db",
"Port": 5432,
"Username": "postgres",
"PasswordExecCommand": "echo 'PASSWORD-PLACEHOLDER--uqfEC1hmmv'",
"MaintenanceDB": "stackframe"
}
}
}