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 deploy. 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 comes 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

The available values are

• nixpacks
• dockerfile

Build command

Build command to pass to the Nixpacks builder

Watch Patterns

Array of patterns used to conditionally trigger deploys

Dockerfile Path

Location of non-standard Dockerfile path

Start Command

The command to run when starting the container

Healthcheck Path

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

Healthcheck Timeout

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

Restart Policy Type

How to handle the deployment crashing

The available values are

• never
• on_failure
• always

Restart Policy Max Retries

The number of times to restart if the restart type is on_failure

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

Deploys for all 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.