Avatar of Melissa HaleMelissa Hale

Building Railway on Railway

How much of our production stack can we open source?

That’s the question we started with.

It turns out, quite a lot. So we did.

And we’re not saying we open-sourced some application code — we’re saying we open-sourced nearly the entire project in Railway, like the infrastructure itself.

If you’d like to see how we deliver our own large-scale, production-grade software on Railway, this blogpost is for you.

This is the story behind Railway Station.

Railway Station contains Railway’s Blog, Docs, Forum, and more

Railway Station contains Railway’s Blog, Docs, Forum, and more

The idea for Railway Station was inspired by a critical question: How can we show our users that Railway is built for highly complex, production workloads?

Traditional paths, like building a demo application for “Acme Corp” with a mechanism to generate artificial load, felt removed from Railway’s authenticity. So we thought: What if we used our production applications already running on Railway, would that be crazy?

After all, our Docs, Blog, and Community Forum are serving hundreds of thousands of users every day — and these aren't trivial services, they are the living, breathing heart of our operations.

Isn’t this something that people would like to see?

We thought so too. So we got to work.

Previously, these services were running in separate projects in the Railway team workspace:

Dashboard view of various projects that would come to make up Railway Station

Dashboard view of various projects that would come to make up Railway Station

We wanted to consolidate the services into a single project for simplicity.

By using environments and environment sync, we were able to stage each migrated service in an isolated staging environment and then sync them to production.

Reviewing changes to sync from Staging to Production

Reviewing changes to sync from Staging to Production

Voilà! After all the services had been migrated, Railway Station was born.

All the previous projects were consolidated into a single project

All the previous projects were consolidated into a single project

Once we had all of our services in a single project, it was kind of a mess. Clearly, we needed a way to organize things, but what?

Project Canvas without Service Groups

Project Canvas without Service Groups

So we built Service Groups, and we were able to turn a cluttered project canvas into a visual showcase of service architecture.

Project Canvas with Service Groups

Project Canvas with Service Groups

By using Railway to host our own production systems in a collaborative, multi-service project, we’ve created a 12-course dogfooding experience.

Some things we’ve already learned since building Railway Station:

  • Email alerts can be spammy without the ability to filter or subscribe to specific alerts
  • More granular visibility controls within public projects is necessary to give project owners control over what can be seen
  • A mechanism to prevent editor collision while managing service groups is necessary
  • Change diffs should be grouped, to avoid visually overwhelming users
  • Control over which services are deployed in a PR environment is necessary, especially in projects that contain disparate services

Some of these were immediately translated into feature revisions, and the rest are backlogged for later enhancements — but to say the least, we couldn’t be happier with our decision to build and open source Railway Station.

Now, let’s tour Railway Station, the hub of Railway’s operational services.

Railway Station is the heart of our operations

Station key:

How do we manage the code and infrastructure changes for all of these services in one project?

Let’s talk about it.

We use a combination of persistent and ephemeral environments plus environment sync to manage code and infrastructure seamlessly.

Railway Station development workflow

Railway Station development workflow

Code Changes

Since we branch from, and PR into main, all code changes are tested in PR environments prior to merge. Upon merge, the PR environment is torn down, and the affected services in production are redeployed.

Infrastructure Changes

All infrastructure changes, like adding new services or updating configuration or variables, are first done in our staging environment. We then Sync changes from staging to production.

Syncing changes from Staging to Production

With Railway Station now public, we invite you to explore our operations, understand our processes, and witness our growth. This open-source initiative is a step towards a more transparent, engaged, and community-focused Railway.

Click over to the public project and start exploring. You can even fork our documentation frontend, built with NextJS, and use it for your own.

Stop by every now and then, see what we are up to and what’s been added. If you ever have any questions about what you see, please get in touch!