Config as Code

Railway supports defining the configuration for a single deployment in a file alongside your code. By default, we will look for a railway.toml or railway.json file. Everything in the build and deploy sections of the service settings page can be specified in this configuration file.

When a new deployment is triggered, Railway will look for any config files in your code and combine these values with the settings from the dashboard. The resulting build and deploy config will be used only for the current deployment. The settings in the dashboard will not be updated with the settings defined in code. Configuration defined in code will always override values from the dashboard.

Example

These configuration examples are equivalent.

Toml

In a railway.toml file:

Json

In a railway.json file:

Config Source Location

On the deployment details page, all the settings that a deployment went out with are shown. For settings that come from a configuration file, there is a little file icon. Hovering over the icon will show exactly what part of the file the values originated from.

Configurable Settings

Everything in the build and deploy sections of the service settings can be configured. The settings are...

Builder

Set the builder for the deployment.

Possible values are:

• NIXPACKS
• DOCKERFILE

Note: Railway will always build with a Dockerfile if it finds one. To build with nixpacks, you can remove or rename the Dockerfile..

Watch Patterns

Array of patterns used to conditionally trigger a deploys.

Build Command

Build command to pass to the Nixpacks builder.

This field can be set to null.

Dockerfile Path

Location of non-standard Dockerfile.

This field can be set to null.

Nixpacks Config Path

Location of a non-standard Nixpacks config file.

This field can be set to null.

Nixpacks Plan

Full nixpacks plan. See https://nixpacks.com/docs/configuration/file for more info.

This field can be set to null.

Nixpacks Version

Version of Nixpacks to use. Must be a valid Nixpacks version. EXPERIMENTAL: USE AT YOUR OWN RISK!.

This field can be set to null.

Start Command

The command to run when starting the container.

This field can be set to null.

Num Replicas

The number of instances to run for the deployment.

This field can be set to null.

Healthcheck Path

Path to check after starting your deployment to ensure it is healthy.

This field can be set to null.

Healthcheck Timeout

Number of seconds to wait for the healthcheck path to become healthy.

This field can be set to null.

Restart Policy Type

How to handle the deployment crashing.

Possible values are:

• ON_FAILURE
• ALWAYS
• NEVER

Restart Policy Max Retries

This field can be set to null.

Cron Schedule

Cron schedule to run the deployment on.

This field can be set to null.

Custom Config File

You can use a custom config file by setting it on the service settings page. The file is relative to your app source.

Environment Overrides

Configuration can be overridden for a specific environment by nesting it in a environments.[name] block.

When resolving the settings for a deployment, Railway will use this priority order:

1. Environment specific config in code
2. Base config in code
3. Service settings

The following example changes the start command just in the production environment.

In a railway.toml file:

In a railway.json file:

PR Environment Overrides

Deployments for pull requests can be configured using a special pr environment. This configuration is applied only to deploys that belong to an ephemeral environment. When resolving the settings for a PR deployment, the following priority order is used:

1. Environment with the name of the ephemeral environment
2. Environment with the hardcoded name "pr"
3. Base environment of the pull request
4. Base config as code
5. Service settings

JSON Schema

You can find an always up-to-date JSON schema at railway.app/railway.schema.json.

If you include it in your railway.json file, many editors (e.g. VSCode) will provide autocomplete and documentation.