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:
- Environment specific config in code
- Base config in code
- 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:
- Environment with the name of the ephemeral environment
- Environment with the hardcoded name "pr"
- Base environment of the pull request
- Base config as code
- 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.
Edit this file on GitHub