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
- 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
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:
- 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