Railway deploy target

Railway builds and runs services from your repository. @mayurajs/deploy-railway adds railway as a target for mayura deploy: deploy init writes one Railway config-as-code file per service, a server and a workflow worker, each building from the Dockerfile and migrating storage before it goes live, and each release runs the Railway CLI, signed in as you. The package has no dependencies besides mayura. It runs inside the mayura CLI on Node.js 22 or 24, on your machine or in CI.

#Install

npm install mayura
npm install --save-dev @mayurajs/deploy-railway

mayura deploy loads the target from the project's own node_modules, so a dev dependency is enough. You also need the Railway CLI on your PATH.

#Credentials

Mayura reads no credentials. The Railway CLI uses its own login (railway login), or RAILWAY_TOKEN in CI; a project token comes from your Railway project's settings. The login needs access to the linked project and both services.

#Use it

Link the directory to your Railway project once, write the files, and point each service at its file:

railway link
mayura deploy init --target railway --apply   # writes deploy/railway/server.json and worker.json

Once per service, in the service's settings, set its config-as-code path: /deploy/railway/server.json for the server and /deploy/railway/worker.json for the worker. Add PostgreSQL to the project, and give both services DATABASE_URL and the app's variables.

{
  "format": "mayura.deploy.v1",
  "name": "refunds",
  "targets": {
    "railway": { "serverService": "refunds-server", "workerService": "refunds-worker" }
  }
}

mayura deploy --target railway --tag v42                              # prints the plan and its digest
mayura deploy --target railway --tag v42 --apply --confirm <digest>

Your app module is the one the deployment guide describes. The server listens on Railway's PORT.

#Options

Service and environment names are letters, digits, spaces, _, . and -, up to 63 characters. Any other key under targets.railway is refused.

#Files it writes

Railway's start and pre-deploy commands replace the image's entry point, so they name the mayura CLI in full. Both services migrate before they go live; migrations take a lock, so whichever runs first does the work.

#A release

--ci returns once the build is done and Railway finishes the rollout; a failed build or migration fails the step. A run stops at the first failing step. The tag is used only in the deploy message, since Railway builds from your directory.

#Secrets and environment

Set DATABASE_URL and the app's variables on both services in Railway. env in mayura.deploy.json is not used by this target, and no value ever appears in a plan.

#What it never does

• Create services, add PostgreSQL, or set the services' config paths and variables: you do those once in Railway.
• Read credentials, or run a shell: each step is railway with its arguments as planned.
• Overwrite the service files or the Dockerfile without the digest of the file plan that shows the change.

#Errors

Failures are MayuraErrors with a code; the CLI prints the code and message and exits with 1.

A step that exits non-zero fails the run, skips the rest, and the CLI exits with 1.

#How it is tested

• Unit tests write the files into a temporary project and compare both config-as-code files in full.
• They plan releases with default and custom service and environment names and compare every step's arguments, refuse malformed settings and a release before deploy init, and run a plan with a fake runner in place of the Railway CLI to check that a failed server deploy never releases the worker.
• The package has not yet deployed to a real Railway account.

#Related

• Deploy with mayura deploy: plans, digests and mayura.deploy.json.
• Deployment: web and worker processes with a pre-deploy migration.
• Render deploy target: the same shape as a Render Blueprint.
• Railway sandboxes: Railway as a sandbox provider.