Repository navigation
feat(deploy): make the stack deployable on Railway - #22
Merged
Merged
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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_directorytools read back at query time. They cannot be two services, so they become one container — through a Railway-only Dockerfile and entrypoint.docker-compose.ymlis 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 inqueuedwith 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.
TIMEOUTrather than a connection that simply stops;: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_FILTERis the load-bearing part: without it envsubst also substitutes nginx's own$host,$remote_addrand$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
.dockerignoreanywhere;HOST/PORTwere baked into the API image, and Railway injectsPORTand runs an IPv6 private network where a service bound to0.0.0.0is reachable by nothing.Verified — by building and running the image
listen 80/127.0.0.11/api:8000; overrides →listen 8080/[fd12::10]/api.railway.internal.$api_upstreamand$request_uriintactCache-Controlon hashed assets — the first attempt emitted two — andno-storeonindex.htmlGET /api/v1/repostruncated: falseclose()still ends a stream mid-heartbeat and that an overrun emitsTIMEOUTand nofinal_answermake checkgreenNot 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-workercontainer 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 checkgreen: 358 passed / 5 skipped, 86 frontend tests, mypy strict over 86 files.