Railway Deployment Notes

Railway Deployment Notes

This repo uses Railway for preview and hosted runtime services under the beef project in the Foxy workspace.

Checked-in service config

Railway supports build and deploy config in railway.json or railway.toml, but in a monorepo the config file does not follow the service Root Directory automatically. Each Railway service must be configured once with both the correct Root Directory and the checked-in custom config path.

The apps/*/railway.json files are intended to be an exact mirror of the live main environment build/deploy manifest, including explicit defaulted cloud values such as watchPatterns, multiRegionConfig, replica counts, runtime flags, and healthcheck settings. If main changes, update the checked-in files from Railway before cloning the setup elsewhere.

Current main-environment service wiring

Service	Root Directory in Railway	Custom config path in Railway
beef-brain	apps/brain	/apps/brain/railway.json
beef-brisket	apps/brisket	/apps/brisket/railway.json
beef-fennec	apps/fennec	/apps/fennec/railway.json
beef-flank	/apps/flank	/apps/flank/railway.json
beef-round	apps/round	/apps/round/railway.json
beef-sirloin	apps/sirloin	/apps/sirloin/railway.json
beef-strip	apps/strip	/apps/strip/railway.json

Cloning the same setup for prod

For a second environment or prod-like clone, keep the following per service in sync:

1. Service name / service type in Railway.
2. Root Directory.
3. Custom config path.
4. Environment variables / secrets.
5. Domains, volumes, and any non-JSON service attachments.

With the current repo state, Railway build/deploy settings should come from the checked-in railway.json files, so recreating the service layout is mostly a matter of pointing each service at the same Root Directory and config path.

Healthchecks

All Railway-tracked beef-* services are expected to have healthchecks configured.

Current healthcheck paths:

Service	Healthcheck path	Notes
beef-brain	/health	NestJS controller health endpoint
beef-brisket	/api/health	Next.js app route
beef-fennec	/	Static serve -s dist response
beef-flank	/sign-in	Existing app route
beef-round	/health	Served on the same listener as gRPC so Railway can keep PORT aligned with GRPC_PORT
beef-sirloin	/health	Served on the same listener as gRPC so Railway can keep PORT aligned with SIRLOIN_PORT
beef-strip	/health	Go SSR health route

For both round and sirloin, /health is exposed on the same socket as gRPC using HTTP/2 cleartext + HTTP routing. This avoids any extra port binding and keeps Railway’s required PORT variable aligned with the service’s primary gRPC port.

Quick verification

Use this from the repo root to compare the checked-in files with the live main manifest:

railway status --json

The serviceManifest block under each beef-* service in the main environment should match the corresponding apps/<service>/railway.json file’s build and deploy sections.

Preview database mapping

Preview environments are named beef-pr-<PR_NUMBER>.

Preview database consumers that must be rewired to Neon PR branches:

• beef-sirloin -> SIRLOIN_DATABASE_URL -> Neon database rump
• beef-brain -> DATABASE_URL and DIRECT_DATABASE_URL -> Neon database fennec with schema=fennec

The workflow at .github/workflows/neon-branching.yml creates the Neon PR branch, updates both Railway variables, and verifies that the preview environment no longer points at railway.internal.

Required manual secrets

The GitHub workflow requires one Railway auth secret:

• RAILWAY_TOKEN for project-scoped CI access, or
• RAILWAY_API_TOKEN for account/workspace-scoped CI access

Without one of these secrets, preview environments will keep using their cloned Railway Postgres values.

Current flank status

beef-flank is currently present in the Railway project and has a checked-in config mirror at /apps/flank/railway.json.

Minimum runtime wiring for beef-flank includes:

• SIRLOIN_GRPC_URL
• FLANK_ENCRYPTION_KEY
• CLERK_PUBLISHABLE_KEY
• CLERK_SECRET_KEY

Sirloin-side workflow execution also expects:

• SIRLOIN_FLANK_HOST
• SIRLOIN_FLANK_SERVICE_TOKEN

Docs Site Deployment

The internal docs site is built from docs/ and deployed with Cloudflare Pages.

Recommended Cloudflare Pages settings:

• Build command: pnpm install && pnpm build
• Build output directory: dist
• Root directory: docs
• Access policy: protect the Pages hostname with Cloudflare Access

Do not put secrets, live DSNs, bearer tokens, or credentials in docs.