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 --buildMigrations 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 dataThe 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:apiDo 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=infoGenerate 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 thisA 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.