From 4f9b5c65b61896df23e92f013491eca9f71341d8 Mon Sep 17 00:00:00 2001 From: JSONbored <49853598+JSONbored@users.noreply.github.com> Date: Mon, 6 Jul 2026 20:14:47 -0700 Subject: [PATCH] docs(rees): lead with self-host docker-compose, retire our Railway deployment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Self-host REES via docker-compose (added just before this change) is now production-validated end-to-end on edge-us-01, so re-frame the docs around it as the recommended default rather than an afterthought under an external/managed-instance-first structure: - docs.self-hosting-rees.tsx: merge the separate "Engine configuration" and "Self-hosting REES" sections into one "Run REES" flow that leads with the in-network docker-compose path, with "point at an external or managed instance instead" demoted to an explicit alternative. - review-enrichment/README.md: drop the "standalone Railway microservice" framing, generalize the /health and stale-build notes (neither is Railway-specific), and note self-hosting as the simplest path ahead of the Railway deploy section. - Remove review-enrichment/railway.json: the actual Railway project this repo's own instance depended on has been decommissioned (its self-hosted engine now points at the in-network rees service instead), so the config file describing that deployment is stale. The Railway deploy path itself remains documented and supported for anyone who wants it — only our own no-longer-used config is removed. Unrelated top-level railway.json (the separate, still-valid Railway deploy option for the main self-host image) and the generic "railway.json" infra-file pattern in src/signals/path-matchers.ts are untouched. --- .../src/routes/docs.self-hosting-rees.tsx | 71 +++++++++++-------- review-enrichment/README.md | 26 ++++--- review-enrichment/railway.json | 18 ----- 3 files changed, 57 insertions(+), 58 deletions(-) delete mode 100644 review-enrichment/railway.json diff --git a/apps/gittensory-ui/src/routes/docs.self-hosting-rees.tsx b/apps/gittensory-ui/src/routes/docs.self-hosting-rees.tsx index 008de72034..ea2a61a6eb 100644 --- a/apps/gittensory-ui/src/routes/docs.self-hosting-rees.tsx +++ b/apps/gittensory-ui/src/routes/docs.self-hosting-rees.tsx @@ -71,14 +71,51 @@ function SelfHostingRees() { ]} /> -

Engine configuration

+

Run REES

+

+ REES runs as its own small HTTP service, separate from the engine. The simplest way to run + it is in-network alongside the engine, using the docker-compose stack in the repo root — no + separate hosting to manage, and nothing published to the host (the engine reaches it only + over the compose network): +

+ +

Point the engine at it and generate a fresh shared secret:

+ `} + /> +

+ No SENTRY_* variables are required for a working local REES. Set them only if + you want REES error reporting — see "Service configuration" below for the variables REES + reads, and add them for the rees service through a{" "} + docker-compose.override.yml rather than the root .env: REES reads + the same SENTRY_DSN name the main engine uses, so forwarding the whole{" "} + .env file would point REES's error reporting at the engine's Sentry project + instead of a dedicated one. +

+ +

Pointing at an external or managed instance instead

+

+ If you'd rather run REES elsewhere — a separate host, a managed provider, or one shared + instance across multiple self-hosted installs — point REES_URL at it directly + and skip the rees compose profile entirely. Generate a dedicated shared secret + for that instance; never reuse a secret across two different REES instances you run: +

-REES_TIMEOUT_MS=8000 +REES_SHARED_SECRET=`} + /> + +

Common options (either path)

+ -

Self-hosting REES

-

- The docker-compose stack in the repo root can run REES for you instead of pointing{" "} - REES_URL at a managed or external instance. Start it alongside the engine with - the rees profile: -

- -

- REES is not published to the host — the engine reaches it only over the compose network. - Point the engine at it and generate a fresh shared secret; do not reuse a secret from any - other REES instance (for example a managed Railway deployment) you also run: -

- `} - /> -

- No SENTRY_* variables are required for a working local REES. Set them only if - you want REES error reporting — see "Service configuration" below for the variables REES - reads, and add them for the rees service through a{" "} - docker-compose.override.yml rather than the root .env: REES reads - the same SENTRY_DSN name the main engine uses, so forwarding the whole{" "} - .env file would point REES's error reporting at the engine's Sentry project - instead of a dedicated one. -

-

Disable cleanly

Set GITTENSORY_REVIEW_ENRICHMENT=false to turn off REES for the whole instance. diff --git a/review-enrichment/README.md b/review-enrichment/README.md index 415fb409dc..606a43849c 100644 --- a/review-enrichment/README.md +++ b/review-enrichment/README.md @@ -1,6 +1,10 @@ # Review-enrichment service (REES) -A standalone Railway microservice that produces a structured **review brief** for the gittensory review engine. +A standalone microservice that produces a structured **review brief** for the gittensory review engine. Run it +in-network alongside a self-hosted engine via the repo-root `docker-compose --profile rees` service (the simplest +path, no separate hosting to manage — see the [self-hosting REES docs](https://gittensory.aethereal.dev/docs/self-hosting-rees)), +or deploy it as its own service on any platform that can run a Dockerfile-based Node service — see +[Deploy (Railway)](#deploy-railway) below for one example. The engine reviews PRs by running a headless `claude --print` subprocess with `Bash`/`WebFetch` disallowed and **no repo checkout**, so it cannot run a linter, hit a CVE database, resolve a dependency tree, or query git history. REES @@ -12,7 +16,7 @@ treats any timeout/error as "no brief" and proceeds. | Route | Purpose | | ----------------- | ------------------------------------------------------------------------------- | -| `GET /health` | Liveness (Railway healthcheck). | +| `GET /health` | Liveness health check. | | `GET /ready` | Readiness. | | `POST /v1/ping` | Auth check only — the engine calls this at startup to verify the shared secret matches. Returns `{ok:true}` or 401. | | `POST /v1/enrich` | `Authorization: Bearer ` → `EnrichRequest` → `ReviewBrief`. | @@ -160,9 +164,9 @@ category, skipped/capped work counts by category, and elapsed time. Never put re comments, tokens, private configs, or raw external payloads into cache categories, metric keys, Sentry tags, or logs. The engine also sends `budget.timeoutMs` with one second of headroom below `REES_TIMEOUT_MS`, so REES can return a -partial/degraded brief before the caller aborts the HTTP request. If Railway is still running an older REES build, -temporarily raise the engine-side `REES_TIMEOUT_MS` above the REES analyzer budget, or set `REES_ANALYZERS` to a -bounded list that excludes `history` until the budget-aware build is deployed. +partial/degraded brief before the caller aborts the HTTP request. If your REES deployment is still running an older +build, temporarily raise the engine-side `REES_TIMEOUT_MS` above the REES analyzer budget, or set `REES_ANALYZERS` to +a bounded list that excludes `history` until the budget-aware build is deployed. ## Run locally @@ -176,10 +180,14 @@ curl -XPOST localhost:8080/v1/enrich -H 'authorization: Bearer dev' \ ## Deploy (Railway) -Separate service from the engine. Set **Root Directory = `review-enrichment`** so Railway reads this folder's -`railway.json` + `Dockerfile`. Set `REES_SHARED_SECRET` (same value the engine holds) as a service variable — never -commit it. The engine reaches the service over Railway **private networking** (`.railway.internal`); no public -domain is required. +For a self-hosted engine, `docker compose --profile rees up -d` from the repo root (see the +[self-hosting REES docs](https://gittensory.aethereal.dev/docs/self-hosting-rees)) is the simplest path — no +separate service to host. If you'd rather run REES on its own outside that compose network, it's a plain +Dockerfile-based Node service and can go anywhere that builds one; Railway is one option this repo has release +tooling for (the Sentry/source-map wiring below). Point **Root Directory = `review-enrichment`** at a `railway.json` +you add there (see Railway's Dockerfile-builder docs) and set `REES_SHARED_SECRET` (same value the engine holds) as a +service variable — never commit it. The engine reaches the service over Railway **private networking** +(`.railway.internal`); no public domain is required. ## Sentry releases and source maps diff --git a/review-enrichment/railway.json b/review-enrichment/railway.json deleted file mode 100644 index 5f5414c644..0000000000 --- a/review-enrichment/railway.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "$schema": "https://railway.com/railway.schema.json", - "build": { - "builder": "DOCKERFILE", - "dockerfilePath": "Dockerfile", - "watchPatterns": ["review-enrichment/**"] - }, - "deploy": { - "numReplicas": 1, - "healthcheckPath": "/health", - "healthcheckTimeout": 60, - "sleepApplication": false, - "restartPolicyType": "ON_FAILURE", - "restartPolicyMaxRetries": 5, - "overlapSeconds": 0, - "drainingSeconds": 15 - } -}