Skip to content

feat(deploy): make the stack deployable on Railway - #22

Merged
Odiethebest merged 3 commits into
mainfrom
feat/railway-deploy
Aug 3, 2026
Merged

Odiethebest merged 3 commits into
mainfrom
feat/railway-deploy

Conversation

@Odiethebest

Copy link
Copy Markdown
Owner

Stacked on #18, #19, #20, #21. Closes F-09, F-16, F-17, adds F-21. The only PR in this series that is genuinely platform-specific.

R-1 — a Railway volume attaches to exactly one service

The worker writes the repository tree that the agent's read_file / grep / list_directory tools read back at query time. They cannot be two services, so they become one container — through a Railway-only Dockerfile and entrypoint.

docker-compose.yml is untouched: local Docker shares volumes fine, and that is a platform difference, not a reason to degrade the local path (Deploy.md §5.1).

The entrypoint uses wait -n, so either child exiting takes the container down. Waiting on both in sequence would leave a container that looks healthy while indexing is silently dead — the agent would keep answering and every submitted repository would sit in queued with nothing to explain it.

R-2 — the platform closes long requests

A query had no overall ceiling at all: only per-hop timeouts, so fourteen steps plus rerank and synthesis could outlive the 5-minute cut, and an abandoned request kept spending on three metered APIs with nobody draining the queue.

  • a budget that expires inside the platform's window and emits a labelled TIMEOUT rather than a connection that simply stops;
  • heartbeat comment frames so a slow answer is not read as an idle connection.

: is a comment in the SSE grammar and the frontend parser already skips those, so no client contract changed. Nothing half-finished is emitted on timeout — a partial walk has not been through the groundedness verifier (Honesty_Constraints §3).

R-4 — nginx

The site config becomes a template rendered by the image's envsubst. NGINX_ENVSUBST_FILTER is the load-bearing part: without it envsubst also substitutes nginx's own $host, $remote_addr and $request_uri, producing a config that is valid and quietly broken.

The proxy target is a variable with a resolver, because Railway's private DNS hands out a new address on every redeploy while nginx caches a literal target for the life of the process. The API would keep working until it was next redeployed, then fail with no change on this side.

Defaults reproduce the previous behaviour exactly, so compose needs no change.

F-09 — the workbench had no way to discover what is indexed

GET /api/v1/repos, merged behind the localStorage recents rather than replacing them. Recents carry the URL as typed and this reader's ordering; the server knows what exists. Without this a reader on a new device opened an empty product and had to index a repository before they could ask anything.

Also

gzip was off (the base image ships it commented out and this config never enabled it); there was no .dockerignore anywhere; HOST/PORT were baked into the API image, and Railway injects PORT and runs an IPv6 private network where a service bound to 0.0.0.0 is reachable by nothing.

Verified — by building and running the image

Check Result
Template renders under both shapes defaults → listen 80 / 127.0.0.11 / api:8000; overrides → listen 8080 / [fd12::10] / api.railway.internal. $api_upstream and $request_uri intact
gzip 760,088 → 269,497 bytes on the built main chunk
Cache headers one Cache-Control on hashed assets — the first attempt emitted two — and no-store on index.html
GET /api/v1/repos live against the local database: 8 repositories, truncated: false
Heartbeat + budget 5 tests, including that close() still ends a stream mid-heartbeat and that an overrun emits TIMEOUT and no final_answer
Local stack unchanged api rebuilt and healthy; make check green

Not verified

No Railway deployment exists. Deploy.md §10.2 is a runbook written from the code, marked as such — private networking over IPv6, the real request limits against real heartbeats, the pgvector template, and the first hosted-provider index are all unproven until someone deploys.

The combined agent-worker container has never been run, locally or otherwise. Its entrypoint is Railway-only and the developer stack does not use it.

F-21 — the docs broke the stack

§10.1's setup block contained placeholders inside a copy-pasteable heredoc. It was pasted verbatim, the placeholder became the credential, and the API refused to boot — correctly, and with exactly the right message. The refusal was fine; the instructions were the defect. The block now substitutes its own values.

make check green: 358 passed / 5 skipped, 86 frontend tests, mypy strict over 86 files.

Deploy.md D-2 and D-6: the landing page and the evaluation write-up stay
public, the product does not. One shared account, so no user table and no
migration.

No new dependency. passlib, pyjwt and itsdangerous are all absent from this
workspace and pulling one in to authenticate a single demo account would be
the larger change, so this is stdlib: PBKDF2-HMAC-SHA256 at OWASP's 600k
floor, and an HMAC-signed session cookie that is HttpOnly, Secure and
SameSite=Lax.

The gate is off by default, so local development, every current compose
invocation and the existing tests are unaffected. docker-compose.prod.yml
HARDCODES it on rather than defaulting it — a production gate that can be
switched off by omitting a variable is not a gate — and the API refuses to
start when it is on but unconfigured, because an auth gate that fails open
looks exactly like one that works.

Also closes F-05: /docs, /redoc and /openapi.json enumerate the /internal/*
surface and are now off in production.

A per-session daily query cap sits on /query alone. The login wall removes
anonymous callers; it does nothing about a signed-in one looping a question
through three metered APIs. It is counted before the agent is reached and
it fails open on a Redis error, because a spend guard that takes the
service down when a cache blips has traded a bounded bill for an outage.

Two findings from verifying this, both fixed here and written up in
Deploy.md.

The first is a real trap. Docker Compose interpolates `$VAR` inside
env-file values, so the conventional `pbkdf2_sha256$600000$salt$hash`
reached the container as 22 characters with three of four segments eaten.
Nothing errored: the API booted, the health check passed, and every login
failed forever, indistinguishable from a wrong password. The format now
joins on "." so the character never appears, and the hash is parsed at
startup rather than checked for non-emptiness, so any corruption stops the
boot. This applies to every hand-picked secret containing `$`, not just
this one.

The second is that the test suite reads the developer's .env, so `make
check` is not hermetic. Switching the gate on locally failed four unrelated
tests and the failures pointed nowhere near the cause. A root conftest.py
pins the settings whose defaults tests assert.

Verified live on a gated container: protected routes 401, /healthz and the
session endpoints 200, /openapi.json 404, wrong password 401 with no
cookie, correct password sets the hardened cookie and opens the gate,
switching it back off restores everything. Not verified: the /workbench to
/login redirect in a real browser — it has four unit tests, but headless
screenshots do not work here and that is not a reason to claim otherwise.
Deploy.md says who needs to look at what.
The two verification items that need a human need the gate switched on
first, and nothing switches it on by default. That walkthrough existed only
in a conversation, which means the next person rediscovers it.

Records the part that actually decides whether the gate can be tested
locally at all: apps/frontend has no .env, so VITE_API_BASE_URL is
undefined and BASE_URL is the empty string, which makes the SPA call
same-origin /api/v1/* on 5173 with vite.config.ts proxying to the gateway.
No cross-origin request, so allow_credentials=False never comes into it.
Pointing VITE_API_BASE_URL at localhost:8000 breaks that, and the failure
would look like a cookie bug rather than a configuration one.

Plus the three things that otherwise cost time: the Secure-cookie fallback
on plain-HTTP localhost, not hand-editing the hash back to $ separators
(§2.3), and that make check is unaffected because conftest.py pins the
setting — which exists because a locally-enabled gate once failed four
unrelated tests with no hint of why.
Four platform constraints, one product gap, and two build fixes.

R-1, the volume. A Railway volume attaches to exactly one service, and the
worker writes the repository tree the agent's read_file / grep /
list_directory tools read back. The two processes that share it now share a
container — via a Railway-only Dockerfile and entrypoint. docker-compose.yml
still runs them separately against a shared Docker volume: local Docker can
share volumes, Railway cannot, and that is a platform difference rather than
a reason to degrade the local path. The entrypoint uses `wait -n` so either
child exiting takes the container down; waiting on both in sequence would
leave one that looks healthy while indexing is silently dead and every
submitted repository sits in `queued` with nothing to explain it.

R-2, the request limits. A query had no overall ceiling at all — only
per-hop timeouts, so fourteen steps plus rerank and synthesis could outlive
the platform's five-minute cut, and an abandoned request kept spending on
three metered APIs. There is now a budget that expires inside that window
and emits a labelled TIMEOUT rather than a connection that simply stops,
and heartbeat comment frames so a slow answer is not mistaken for an idle
one. `:` is a comment in the SSE grammar and the frontend parser already
drops those, so no client contract changed. Nothing half-finished is
emitted on timeout: a partial walk has not been through the groundedness
verifier.

R-4, nginx. The site config becomes a template rendered by the image's
envsubst, with NGINX_ENVSUBST_FILTER restricting it to three names —
without that it would also substitute nginx's own $host and $request_uri
and produce a config that is valid and quietly wrong. The proxy target is
a variable with a resolver because Railway's private DNS changes address on
every redeploy and nginx caches a literal target for the life of the
process; the API would keep working until it was next redeployed and then
fail with no change on this side. Defaults reproduce the previous behaviour
exactly, so compose is unaffected.

F-09, the product gap. GET /api/v1/repos, merged behind the localStorage
recents rather than replacing them: recents carry the URL as typed and this
reader's ordering, the server knows what exists. Without it a reader on a
new device opened an empty workbench and had to index something before they
could ask anything.

Also: gzip was off (the base image ships it commented out and this config
never enabled it), no .dockerignore anywhere, and HOST/PORT were baked into
the API image — Railway injects PORT and its private network is IPv6, so a
service bound to 0.0.0.0 there is reachable by nothing.

Verified by building and running the frontend image: the template renders
correctly under both the default and Railway shapes with nginx's own
variables intact, gzip takes the main chunk from 760,088 to 269,497 bytes,
hashed assets carry one Cache-Control rather than the two the first attempt
emitted, and index.html is no-store. The list endpoint was checked against
the live local database. Heartbeats and the budget have five tests.

Not verified: no Railway deployment exists, and the combined agent-worker
container has never been run. Deploy.md §10.2 is a runbook written from the
code, marked as such.

Deploy.md §10.1 is also rewritten. Its setup block contained placeholders
inside a copy-pasteable heredoc, that got pasted verbatim, and the
placeholder became the credential — the API refused to boot, correctly and
with the right message. The refusal was fine; the instructions were the
defect, so the block now substitutes its own values.
@Odiethebest
Odiethebest merged commit c8cbe27 into main Aug 3, 2026
1 of 2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant