Config as Code allows you to specify service build and deploy settings in a file alongside your code. This can be a railway.toml or railway.json file by default or a custom file anywhere in your app that you specify in the service settings.

Specify service build and deploy settings in a railway.toml or railway.json file

Whether a new deployment is triggered via railway up using the Railway CLI, or via a git push event, Railway will combine the service settings from the dashboard with the settings in the config file.

The file-based config will always override the dashboard config. This means that you can incorporate Config as Code settings at your own convenience. For a full reference of what you can put in the config file, please check out the docs.

If you’re wondering why you’d want to start using Config as Code instead of the Railway dashboard, we put together a few reasons below.

As the code for your application grows and evolves, the configuration used to build and deploy it can change as well. Config as Code allows this configuration to live alongside the code it configures which means it will be tracked in version control.

Config as Code brings the power of git to your service build and deploy configuration. If you update the start command in a way that breaks the application, you may simply rollback to the previous commit and the config will rollback as well. This is not currently possible in the Railway dashboard.

In general, it is a good practice to keep environments as similar as possible. However, there are scenarios in which you would want slightly different service settings for a development or staging environment. With Config as Code that is easily accomplished.

One example that comes to mind is a start command. It’s not uncommon to require different start commands for production and staging or development environments.

Custom start command in the production environment

Separate config per environment is useful if you want to run with a --prod flag only on the production environment or have an infinite restart policy in prod but a never restart policy in dev/staging.

Similar to the above point, sometimes you’d like pull request deploys to have different settings than the production environment.

This is not possible on the Railway dashboard, but is possible with Config as Code using the special pr environment. The following priority is assigned to configs resolved via pull request:

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

For more information on the priority order, please read the docs.

Want to share your project as a template for other Railway users?

Specifying the service build and deploy settings in code means that anyone who forks your repo or uses your Railway template will be able to use the same config when deploying to Railway. This allows you to guarantee reproducibility for the projects that you share as a template.

Config as Code is an easy way to get started tracking service settings in Git. It also makes it easy to enable different settings on a per-environment basis and helps guarantee determinism for your Railway collaborators.

Please check out the docs for a detailed reference guide.

Psst… Config as Code is just the start when it comes to codifying your Railway project. If you have suggestions on what you would like us to codify next, please don’t hesitate to reach out on Discord and tell us what you think.