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 - } -}