Integrate CircleCI with Railway for automated deployments

The speed and reliability of deploying backend and full-stack applications are usually a concern for development teams. Fortunately, Railway is a developer-friendly platform that allows you to deploy apps with limited configuration. It is also quick, easy to use, and has reasonable defaults.

Now, imagine pairing that with CircleCI, one of the strongest continuous integration platforms available. CircleCI enables you to automate deployment, meaning that every time you make a push to your repository, an automatic deployment to Railway will occur. This will help to conserve time, minimize human error, and provide you repeatable workflow for production-ready releases.

With the help of this tutorial, you will learn how to use CircleCI to develop an automated CI/CD process using a Node.js application and Railway.

Prerequisites

Before you begin, make sure you have the following:

• A GitHub account
• A Railway account
• A CircleCI account (linked to GitHub)
• Git installed
• Basic knowledge of Git, GitHub, and CircleCI workflows

Why Use CircleCI with Railway?

Trying to deploy applications manually through a CLI or Web UI can become repetitive and is usually prone to errors. This becomes more apparent as your project grows or your team expands. Combining both CircleCI and Railway helps to streamline this process and make everything easier. But what does that mean?

Seamless code-to-cloud automation

Railway enables you to go live with a Node.js application with a simple GitHub repo linkage, and CircleCI helps automate that entire process. Combined, all of your code pushes are automatically committed through your GitHub repository and are automatically deployed through CircleCI’s workflow, and appear live on Railway with no manual intervention.

Zero-DevOps with developer-friendly

Railway takes care of the infrastructure behind the scenes, no more need to deploy servers, manage Docker, or configure CI runners. CircleCI augments this by having your deployment logic run in a secure CI environment. The combination does not require special DevOps resources and still provides you with powerful deployment control and logging.

Reliable, repeatable deployments at every stage

By using the simplified hosting provided by Railway and the reproducible build pipelines with CircleCI, any deployment of yours is made the same way every time whether you are in development, staging, or production. The config file of CircleCI represents a version-controlled blueprint of the deployment, and Railway runs the blueprint in a stable manner. Combined, they reduce drift among environments and minimize human error.

Setting up a Node.js app and pushing to GitHub

To illustrate automated deployments, we will need a simple Node.js application. This application will just receive HTTP requests and respond plainly. This is ideal to serve as an example to test the hosting capabilities of Railway, and deploying pipeline of CircleCI. To get started, you will build a simple Node.js app for this tutorial. The app’s directory will include:

• index.js starts a simple HTTP server
• package.json contains metadata and the start script
• Procfile instructs Railway on how to run the app
• README.md contains the project’s description

For each file, add the content as shown.

index.js:

const express = require("express");
const app = express();
const port = process.env.PORT || 3000;

app.get("/", (req, res) => {
  res.send("🚀 Hello from Railway + CircleCI!");
});

app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

package.json:

{
  "name": "circleci-railway-demo",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "build": "echo \"No build step needed\""
  },
  "dependencies": {
    "express": "^4.18.4"
  }
}

Procfile:

web: npm start

README.md:

# CircleCI + Railway Demo App

This is a simple Node.js app used to demonstrate CI/CD deployment with CircleCI and Railway.

When you are satisfied, you can push the code files to a new GitHub repository. Both Railway and CircleCI will use this as their source in the next steps.

Deploy manually to Railway and get your Service ID

Before we automate deployments with CircleCI, it’s important to first deploy the app manually to Railway. This will assist in proving that the app is working properly in the platform and provide you with relevant configuration parameters such as your Service ID and Deploy Token values that you will require later in the CI/CD process.

During this step, you will tie your GitHub repo to Railway, initiate a one-time deployment, and collect the credentials needed to automate the deployment.

Connect your GitHub repo to Railway

• Visit the Railway app and sign in (it is recommended that you sign it with GitHub).
• Click on “Deploy a new project” and then “Deploy from GitHub Repo”

• On the next page, click Configure GitHub App. Follow the prompts to allow Railway to gain access to your repos and give them the necessary permissions.
• After configuring Railway with GitHub, your list of repositories should appear. Find and select the pushed project.

Railway will automatically detect the project structure and deploy it using the Procfile.

Get your Service ID

Railway assigns a unique ID to every service. This ID will play a key role when configuring the deployment command on CircleCI later, so you have to retrieve it and keep it safe. From the Railway dashboard, click on your project. After this, look at the URL. It should be similar to this:

https://railway.app/project/your-project-id/service/<YOUR-SERVICE-ID>

Copy <YOUR-SERVICE-ID>. It will be useful later on in the tutorial.

Generate a deploy token

You’ll need a deploy token to ensure that CircleCI deploys on your behalf:

1. In your Railway project, click Settings > Tokens.
2. Give the new token a name (something like RAILWAY_TOKEN).
3. Click Create.

Copy and save the token securely; this is the only time you will be able to view it. You will add it to CircleCI later as an environment variable.

Setting up a CircleCI config

By now, your manual deployment is finished and you have Railway service up and running. It’s time to automate the process with CircleCI. You’ll start by producing a special configuration file. This file will determine what CircleCI must do when you make changes and push them to your repo.

Create a folder at the root of your project:

mkdir .circleci && cd .circleci

Create the config file and add this content to it:

version: 2.1

jobs:
  deploy:
    docker:
      - image: cimg/node:18.20.2
    steps:
      - checkout
      - run:
          name: Deploy to Railway
          command: npx @railway/cli up --service=<YOUR_SERVICE_ID_HERE> --ci

workflows:
  deploy_on_main:
    jobs:
      - deploy:
          filters:
            branches:
              only: main

run: Deploy to Railway is the actual deployment step. It uses npx to run the Railway CLI without installing it globally.

The key part is this command: npx @railway/cli up --service=<YOUR_SERVICE_ID> --ci.

Replace <YOUR_SERVICE_ID> with the ID you copied from your Railway dashboard earlier. The --ci flag ensures the CLI runs in non-interactive mode, which is necessary in a CI environment like CircleCI.

Once this config is in place and committed to your repo, you’re ready to connect your GitHub project to CircleCI and trigger real deployments automatically.

Configure CircleCI

With your .circleci/config.yml file in place, and your project pushed to GitHub, the next step will be to connect your GitHub repository to CircleCI and add your Railway Deploy Token securely as an environment variable.

This configuration will allow CircleCI to deploy to Railway using authentication and does not allow Railway-sensitive credentials to be exposed in your codebase.

Step 1: Add your GitHub repo

• Visit CircleCI
• Sign into your account or Log in with GitHub
• After logging in, click Projects on the sidebar, then Create Project
• Name the project railway-circleci-demo

• Follow the next prompts to select the project repo and finish the setup.

Step 2: Add Railway deploy token

• In your CircleCI dashboard, go to your project settings
• Go to Environment Variables under the Project Settings
• Click “Add Environment Variable” and enter this:
  • Name: RAILWAY_TOKEN
  • Value: paste your deploy token from Railway

Test the deployment

Now that CircleCI is set up and your Railway token is safely in position, it is time to test the deployment pipeline. This step is to ensure that everything from pushing the code to auto-deploying on Railway is working as it should.

The idea here is to perform a basic change to your project and watch the CircleCI pipeline go to work and ensure that the modified application is running on Railway. To trigger the pipeline, make a small edit to the project by updating the README.md file. Once you’ve made changes, save the file and commit:

git add README.md
git commit -m "Update README to trigger deployment"
git push origin main

You can now watch the pipeline run by going to your CircleCI pipelines and selecting your project.

To verify that the app is live on Railway, open your dashboard and navigate to your project. You will get a Deployment successful text.

This deployment flow is now production-ready or team-ready. All the commits you push will take the same route, making you able to ship more safely, quickly, and regularly. Find the full code in this GitHub repository.

Conclusion

Now that you have connected CircleCI and Railway, you have an automated and stress-free deployment site for your Node.js application. Such integration will make each push to your repository capable of triggering a hands-free deployment, with less manual intervention and the possibility of human error.

Railway provides an easy to understand but potent hosting environment, while CircleCI is in charge of automation of building as well as deployment. In combination, they offer a developer-first experience that enables quicker delivery, more frequent output, and greater functionality of working together.

At this point, with your basic CI/CD pipeline live, you can begin to extend it. Possibly by including some tests, linting, or environments. Be it individual or team , this configuration provides you with a good foundation to expand and elevate your process of deployment with security.