How we built updatable starters

Starters are amongst the most popular features on Railway. We see hundreds of new deploys created daily from a combination of our official starters and starters created by our users using the Railway button.

If you aren’t aware already, our starters are one-click deploys of popular open-source applications. If a project requires a database, we automagically provision one for you and proceed to deploy the application. This behavior isn’t restricted only to popular open-source projects, all you need to do is point us to a Github repository and we’ll do our best to automatically deploy it for you.

While starters are great, they’re merely the starting point for your project. Which is fine if you’re deploying an API server or a frontend template that you intend to work on and build out on your own but what if the starter you were deploying was an open-source project that you intend to use as is? Think of applications like Umami or Cal which you just want to deploy and get going but what do you do when the open-source project gets updated and your deployment keeps falling a few versions behind with every update?

A user asking how they could update the Umami starter they’d deployed on Railway

The solution was kind of obvious. We had to figure out a way to allow our users to automatically update the starters they had deployed on Railway. While this wouldn’t be possible for all starters (especially if a user made a lot of changes), this would allow us to support the scenarios mentioned above where our users were using the starters as is.

At Railway, for any feature that requires some engineering thought, we like to start off the development cycle by writing an Engineering Requirements Document. An ERD typically comprises of the problem statement, possible solutions, the pros and cons of each solution and then feedback by teammates once it is ready for review.

As an example of a possible solution for updatable starters, we originally considered forking the repositories for updatable starters into our users Github accounts but then decided against it once we discovered that forks on Github offer very little flexibility.

Issues with using forks on Github for updatable starters

As mentioned above, once an ERD is marked Ready for review, someone from the team goes over it and shares their thoughts. This is pretty helpful as we get a few more sets of eyes on the original idea, answers to open questions and more often than not, suggestions on how the solution can be improved.

A discussion on whether or not updates should be made as PR deploys

Once an ERD has been approved, the person who wrote the ERD moves on to the implementation of the feature. To close the loop, in this scenario we decided to:

• Mirror the original repository and then use upstream remotes to keep the users repository in sync with the original repository.
• Check for updates to the users project whenever they visit their project dashboard on Railway and then prompt them to update the repository.
• Asynchronously try to update the repository and notify the users of the result of the update via email.

Auto-update status email

This was our first blog post on how we tackle an engineering problem so we’d love some feedback on it and to hear whether or not you enjoyed reading it. If you’re curious about how we work, you can read this blog post we wrote a while back.

As always, feel free to reach out to us with any suggestions/questions regarding updatable starters or anything at all about Railway. The easiest way to reach us is to join our Discord community!