Documentation

Deploying

Docker Compose is the portable baseline. Railway is documented service by service, including the port and start-command traps.

Docker Compose is the canonical portable deployment baseline. Railway is documented service by service. Nothing about the kit assumes a specific platform.

Compose

docker compose up --build

Migrations run once in a dedicated migrate service before the API starts. The portal serves on 3006, the API health endpoint on 3001/health, and PostgreSQL is exposed on 5432 for local tools. Data persists in the postgres-data named volume.

Operations:

docker compose config                 # validate interpolation and the service graphdocker compose run --rm migrate       # re-run pending migrations explicitlydocker compose down                   # stop containers, retain named volumesdocker compose down --volumes         # also remove local persisted data

The API's npm start does not run migrations. Any deployment outside Compose must run npm run db:migrate as a separate release step. That step also creates your portal on the first deploy; Going live covers what its log line means and how to check it.

Replace the placeholder database password and JWT secret before any shared or production deployment, and use an external secret manager or an untracked environment file for real credentials.

Railway

Runtime

Node.js >=22.12.0 <23; use 22.12.0 to match the repository and the API Dockerfile. Use npm ci with the root package-lock.json for reproducible builds.

Services

Service Source Required
Portal apps/portal Yes
API apps/api Yes
PostgreSQL Railway PostgreSQL Yes
MLS worker apps/mls-service Deploy when MLS sync is configured
Redis External or Railway service No
Typesense External or Railway service No

API service

Create a service from the repository root:

Build command: npm ci && npm run build:apiStart command: npm run start:api

Do not use the root npm run build for the API — it builds every buildable workspace.

The API builds with Railpack rather than its Dockerfile. prisma generate reads DATABASE_URL through packages/db/prisma.config.ts, and Railpack has service variables in scope at build time while a Docker build does not, so apps/api/Dockerfile fails at that step unless you supply DATABASE_URL as a build argument.

Minimum variables:

DATABASE_URL=${{Postgres.DATABASE_URL}}API_PORT=${{PORT}}NODE_ENV=productionJWT_SECRET=${{JWT_SECRET}}JWT_EXPIRES_IN=7dFRONTEND_URL=https://portal.example.comALLOWED_ORIGINS=https://portal.example.comAGENT_API_ENABLED=falseMLS_PUBLIC_DISPLAY_ENABLED=falseLOG_LEVEL=info

Generate a unique JWT_SECRET in a secret manager or a secure local shell. Never commit its value.

Portal service

A second service, also from the repository root. It builds from apps/portal/Dockerfile, which apps/portal/railway.json selects:

Builder:         DockerfileDockerfile path: apps/portal/DockerfileRoot directory:  /            (the image builds from the monorepo root)

Leave the start command empty, and clear any command an existing service already has. The image runs the standalone server itself, binding HOSTNAME=0.0.0.0 so the platform can reach it.

A Railway start command overrides the image's CMD. Routing startup back through npm run start binds the container hostname rather than all interfaces, and the service returns 502 while its logs still cheerfully report ✓ Ready. A stale command left over from an earlier setup fails the same way, or crashes the container outright if it names a script the repository no longer has. Check the build command too — switching builders clears neither.

Match the domain to the port actually bound

Railway injects its own PORT into the running container, and a runtime variable overrides the image's ENV, so the server follows the injected value — 8080 by default, not the 3006 the image declares.

The startup log reports the truth:

▲ Next.js- Network:  http://0.0.0.0:8080     <- set the domain's target port to this

A target port that does not match the bound port returns 502. Honouring an injected PORT is what every managed platform expects, so prefer matching the domain to it over forcing the port back to 3006 with a service variable. 3006 applies where nothing injects a port: Docker Compose, and a plain docker run.

Next

Agent API — the one flag that opens the commercial seam.