via command palette
via right-click menu
Hello World
This is a Rails app running on Railway
bin/rails server railway init railway up bundle add sidekiq bundle add sidekiq-cron # Axum Source: https://docs.railway.com/guides/axum Learn how to deploy an Axum app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, GitHub, Dockerfile and other deployment strategies. This guide covers how to deploy an Axum app to Railway in four ways: 1. One-click deploy from a template. 2. From a GitHub repository. 3. Using the CLI. 4. Using a Dockerfile. Now, let's create an Axum app! 🚀 ## Create an Axum App **Note:** If you already have an Axum app locally or on GitHub, you can skip this step and go straight to the Deploy Axum App to Railway. To create a new Axum app, ensure that you have Rust installed on your machine. Run the following command in your terminal to create a new Axum app: The command creates a new binary-based Cargo project in a helloworld directory. Next, cd into the directory and add axum and tokio as dependencies by running the following command: This will add axum and tokio as dependencies, with tokio configured to use the "full" feature, which includes its complete set of capabilities. You’ll find both dependencies listed in your Cargo.toml file. These dependencies are required to create a bare minimum axum application. ### Modify the Application File Next, open the app in your IDE and navigate to the src/main.rs file. Replace the content with the code below: The code above sets up a simple web server using the Axum framework and the Tokio async runtime. The server listens on the port gotten from the environment variable, PORT and defaults to 3000 if there's none set. It defines one route, /, which is mapped to a handler function called root. When a GET request is made to the root path, the handler responds with the static string "Hello World, from Axum!". The Router from Axum is used to configure the route, and tokio::net::TcpListener binds the server to listen for connections on all available network interfaces (address 0.0.0.0). The asynchronous runtime, provided by the #[tokio::main] macro, ensures the server can handle requests efficiently. The axum::serve function integrates with the Hyper server to actually process requests. ### Run the Axum App Locally Run the following command in the helloworld directory via the terminal: All the dependencies will be installed and your app will be launched. Open your browser and go to http://localhost:3000 to see your app. ## Deploy the Axum App to Railway Railway offers multiple ways to deploy your Axum app, depending on your setup and preference. ### One-Click Deploy From a Template If you’re looking for the fastest way to get started, the one-click deploy option is ideal. Click the button below to begin:  We highly recommend that you eject from the template after deployment to create a copy of the repo on your GitHub account. **Note:** You can also choose from a variety of Axum templates created by the community. ### Deploy From the CLI 1. **Install the Railway CLI**: - Install the CLI and authenticate it using your Railway account. 2. **Initialize a Railway Project**: - Run the command below in your Axum app directory. - Follow the prompts to name your project. - After the project is created, click the provided link to view it in your browser. 3. **Deploy the Application**: - Use the command below to deploy your app: - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal. 4. **Verify the Deployment**: - Once the deployment completes, go to **View logs** to check if the server is running successfully. **Note:** During the deployment process, Railway will automatically detect that it’s a Rust app. 5. **Set Up a Public URL**: - Navigate to the **Networking** section under the Settings tab of your new service. - Click Generate Domain to create a public URL for your app.Welcome to Play!
Hello World, Railway!
} libraryDependencies += "org.postgresql" % "postgresql" % "42.7.4" // Always use the latest stable version # Default database configuration using PostgreSQL db.default.driver = org.postgresql.Driver db.default.url = "jdbc:postgresql://username:password@127.0.0.1:5432/scala_play" # Replace with correct credentials sbt update addSbtPlugin("io.github.davidmweber" % "flyway-sbt" % "7.4.0") name := """helloworld""" organization := "com.railwayguide" version := "1.0-SNAPSHOT" executableScriptName := "main" lazy val root = (project in file(".")).enablePlugins(PlayScala).enablePlugins(FlywayPlugin) scalaVersion := "2.13.15" libraryDependencies += guice libraryDependencies += "org.scalatestplus.play" %% "scalatestplus-play" % "7.0.1" % Test libraryDependencies += "org.postgresql" % "postgresql" % "42.7.4" // Latest version flywayUrl := "jdbc:postgresql://127.0.0.1:5432/scala_play?user= → Filter by response details (Only populated when the application fails to respond)
- @clientUa: → Filter by a specific client's user agent
- @srcIp: → Filter by source IP (The client's IP address that made the request)
- @edgeRegion: → Filter by edge region (The region of the edge node that handled the request)
**Examples:**
Find logs for a specific path.
Find logs for a specific path that returned a 500 error.
Find logs for a specific path that returned a 500 or 501 error.
Find all non-200 responses.
Find all requests that originated from or around Europe.
Find all requests that originated from a specific IP address.
## View In Context
When searching for logs, it is often useful to see surrounding logs. To view a log in context:
right-click any log, then select the "View in Context" option from the dropdown menu.
## Structured Logs
Structured logs are logs emitted in a structured JSON format, useful if you want
to attach custom metadata to logs or preserve multi-line logs like stack traces.
Structured logs are best generated with a library for your language. For example, the default Winston. JSON format emits logs in the correct structure by default.
Logs with a level field will be coloured accordingly in the log explorer.
Logs emitted to stderr will be converted to level.error and coloured red.
### Examples
Here are a few examples of structured logs.
**Note:** The entire JSON log must be emitted on a single line to be parsed correctly.
### Normalization Strategy
In order to ensure a consistent query format across Railway services, incoming logs are normalized to the above format automatically.
- Non-structured logs are converted to {"message":"...","level":"..."}
- log.msg converted to log.message
- log.level converted to log.severity
- Logs from stderr are converted to level.error
- Logs from stdout are converted to level.info
- Levels are lowercased and matched to the closest of debug, info, warn, error
## Code Examples
request
"POST /api"
@level:error
@level:warn
@level:error AND "failed to send batch"
@customAttribute:value
@arrayAttribute[i]:value
-@service:
-@service: AND -@service:
@service: OR @service:
@path:/api/v1/users
@path:/api/v1/users AND @httpStatus:500
@path:/api/v1/users AND (@httpStatus:500 OR @httpStatus:501)
-@httpStatus:200
@edgeRegion:europe-west4-drams3a
@srcIp:66.33.22.11
console.log(
JSON.stringify({
message: "A minimal structured log", // (required) The content of the log
level: "info", // Severity of the log (debug, info, warn, error)
customAttribute: "value", // Custom attributes (query via @name:value)
}),
);
{ "level": "info", "message": "A minimal structured log" }
{ "level": "error", "message": "Something bad happened" }
{ "level": "info", "message": "New purchase!", "productId": 123, "userId": 456 }
{
"level": "info",
"message": "User roles updated",
"roles": ["editor", "viewer"],
"userId": 123
}
# Observability
Source: https://docs.railway.com/guides/observability
Explore the built-in observability dashboard on Railway.
or "key phrase" → Filter by exact text
- @key:value → Filter by key/value pair
- Valid keys are replica, deployment, service, plugin
- @attribute:value → Filter by custom attribute (see structured logs below)
Any of the above expressions can be combined with boolean operators AND,
OR, and - (negation).
## Arranging the Dashboard
The Dashboard is customizable in content and layout. Widgets can be stacked, repositioned and resized.
Clicking the "Edit" button on the top right corner of the dashboard will transition the dashboard into edit mode, the dashboard then allows the ability to resize and reposition your widgets using the provided handle on each widget. To persist your changes, select "Save".
|Node||
|
|Deno||
|
|Bun||
|
|Gin||
|
|Flask||
## Kickback Program
If your published template is deployed into other users' projects, you are immediately eligible for a 50% kickback, in the form of Railway credits or cash. Refer to the template reference page for more information.
## Template Verification
Templates are verified when the creator and maintainer of the technology becomes a partner and reviews the template.
If you are or have a relationship with the creator, please reach out to us by submitting the form on our partners page.
## Code Examples
[](https://railway.com/new/template/ZweBXA?utm_medium=integration&utm_source=button&utm_campaign=generic)
# Deploy
Source: https://docs.railway.com/guides/deploy
Learn how to deploy Railway templates.
connected to infrastructure.
You can find featured templates on our template marketplace.
## Template Deployment Flow
To deploy a template -
- Find a template from the marketplace and click Deploy Now
- If necessary, configure the required variables, and click Deploy
- Upon deploy, you will be taken to your new project containing the template service(s)
- Services are deployed directly from the defined source in the template configuration
- After deploy, you can find the service source by going to the service's settings tab
- Should you need to make changes to the source code, you will need to eject from the template repo to create your own copy. See next section for more detail.
_Note: You can also deploy templates into existing projects, by clicking + New from your project canvas and selecting Template._
## Eject from Template Repository
As of March 2024, the default behavior for deploying templates, is to attach to and deploy directly from the template repository. Therefore, you will not automatically get a copy of the repository on deploy. Follow the steps below to create a repository for yourself.
By default, services deployed from a template are attached to and deployed directly from the template repository. In some cases, you may want to have your own copy of the template repository.
Follow these steps to eject from the template repository and create a mirror in your own GitHub account.
1. In the service settings, under Source, find the **Upstream Repo** setting
2. Click the Eject button
3. Select the appropriate GitHub organization to create the new repository
4. Click Eject service
## Updatable Templates
When you deploy any services from a template based on a GitHub repo, every time you visit the project in Railway, we will check to see if the project it is based on has been updated by its creator.
If it has received an upstream update, we will create a branch on the GitHub repo that was created when deploying the template, allowing for you to test it out within a PR deploy.
If you are happy with the changes, you can merge the pull request, and we will automatically deploy it to your production environment.
If you're curious, you can read more about how we built updatable templates in this blog post
_Note: This feature only works for services based on GitHub repositories. At this time, we do not have a mechanism to check for updates to Docker images from which services may be sourced._
# Manage Projects
Source: https://docs.railway.com/guides/manage-projects
Learn how to manage projects via the public GraphQL API.
### Fetch All Your Projects
The query below will fetch all your personal projects along with all the services and environments for them.
### Delete a Project
This is a destructive action
The mutation below will delete the project with the specified id.
## Code Examples
query me {
me {
projects {
edges {
node {
id
name
services {
edges {
node {
id
name
}
}
}
environments {
edges {
node {
id
name
}
}
}
}
}
}
}
}
mutation projectDelete {
projectDelete(id: "5e594338-0faa-415f-b2a7-2b5f2d4ec11a")
}
# Manage Services
Source: https://docs.railway.com/guides/manage-services
Learn how to create services via the public GraphQL API.
### Create a New Service With a GitHub Repo
The mutation below will create a new service with the specified GitHub repo attached. The response will contain the newly created service.
You can also use image inside the source to attach a Docker image to the service.
## Code Examples
mutation serviceCreate {
serviceCreate(
input: {
projectId: "8df3b1d6-2317-4400-b267-56c4a42eed06"
source: { repo: "railwayapp-templates/django" }
}
) {
id
}
}
# Manage Deployments
Source: https://docs.railway.com/guides/manage-deployments
Learn how to manage deployments via the public GraphQL API.
### Fetch Latest Active Deployment
The query below will fetch the latest active deployment for a service for a specific environment.
### Restarting a Deployment
The query below will restart the deployment with the specified id.
## Code Examples
query deployments {
deployments(
first: 1
input: {
projectId: "8df3b1d6-2317-4400-b267-56c4a42eed06"
environmentId: "9fb4baf0-809a-40ec-af32-751f50890802"
serviceId: "4bd252dc-c4ac-4c2e-a52f-051804292035"
}
) {
edges {
node {
id
staticUrl
}
}
}
}
mutation deploymentRestart {
deploymentRestart(id: "9d5b1306-e22e-4357-9b3f-cc3b97ed8240")
}
# Manage Variables
Source: https://docs.railway.com/guides/manage-variables
Learn how to manage variables via the public GraphQL API.
### Fetch Variables For a Service
The query below will fetch all the variables for a service for a specific environment. The response will contain all the variables in a key/value object.
You can omit the serviceId from this query to fetch the shared variables for the environment.
### Upsert Variable For a Service
The mutation below will upsert a new variable for the specified service within the specified environment. You can use this to both create and update variables.
You can omit the serviceId from this mutation to create a shared variable.
## Code Examples
query variables {
variables(
projectId: "8df3b1d6-2317-4400-b267-56c4a42eed06"
environmentId: "9fb4baf0-809a-40ec-af32-751f50890802"
serviceId: "4bd252dc-c4ac-4c2e-a52f-051804292035"
)
}
mutation variableUpsert {
variableUpsert(
input: {
projectId: "8df3b1d6-2317-4400-b267-56c4a42eed06"
environmentId: "9fb4baf0-809a-40ec-af32-751f50890802"
serviceId: "4bd252dc-c4ac-4c2e-a52f-051804292035"
name: "NEW_VARIABLE"
value: "SECRET_VALUE"
}
)
}
# Config as Code
Source: https://docs.railway.com/guides/config-as-code
Learn how to manage and deploy apps on Railway using config as code with toml and json files.
alongside your code in 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.
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.
## Toml vs Json
The format you use for your config-as-code (toml or json) file is entirely dependent on preference, and the resulting behavior in Railway is the same no matter which you choose.
For example, these configuration definitions are equivalent:
## JSON Schema
You can find an always up-to-date JSON schema at railway.com/railway.schema.json.
If you include it in your railway.json file, many editors (e.g. VSCode) will provide autocomplete and documentation.
## Understanding Config Source
On a service's deployment details page, all the settings that a deployment went out with are shown.
For settings that come from a configuration file, there is a file icon. Hovering over the icon will show exactly what part of the file the values originated from.
DD_HOSTNAME=${{RAILWAY_PRIVATE_DOMAIN}}
DD_SITE=
DD_AGENT_HOST=${{datadog-agent.DD_HOSTNAME}}
DD_AGENT_STATSD_PORT=8125
DD_AGENT_SYSLOG_PORT=514
DD_TRACE_AGENT_PORT=8126
railway link
railway service
railway up -d
railway domain
import logging.handlers
from fastapi import FastAPI
from datadog import initialize, statsd, DogStatsd
import logging
import random
import os
import json_log_formatter
## Configuration for sending logs
formatter = json_log_formatter.JSONFormatter()
json_handler = logging.handlers.SysLogHandler(address=(os.getenv("DD_AGENT"), os.getenv("DD_AGENT_SYSLOG_PORT")))
json_handler.setFormatter(formatter)
logger = logging.getLogger('python-app')
logger.addHandler(json_handler)
logger.setLevel(logging.INFO)
# Configuration for sending metrics
config = {
"api_key": os.getenv("DD_API_KEY"),
"statsd_host": os.getenv("DD_AGENT_HOST"),
"statsd_port": os.getenv("DD_AGENT_STATSD_PORT"),
"statsd_constant_tags": ["env:prod"],
}
initialize(**config)
app = FastAPI()
# Use DogStatsd client for more custom metrics
dog_statsd = DogStatsd()
@app.get("/")
async def root():
# Increment a simple counter
statsd.increment('example_app.page.views')
# Record a random gauge value
gauge_value = random.uniform(1, 100)
statsd.gauge('example_app.random_value', gauge_value)
# Log a message
logger.info(f"Page viewed, gauge value: {gauge_value}")
# Custom metric using DogStatsd
dog_statsd.histogram('example_app.response_time', random.uniform(50, 300))
return {"message": "Hello World"}
# Additional route for testing
@app.get("/test")
async def test():
# Custom metrics and logging
statsd.increment('example_app.test.endpoint.hits')
test_value = random.randint(1, 10)
dog_statsd.gauge('example_app.test.value', test_value)
logger.info(f"Test endpoint hit, value: {test_value}")
return {"test_value": test_value}
logs:
- type: udp
port: 514
service: "node-app"
source: syslog
- type: udp
port: 515
service: "python-app"
source: syslog
# Deploy an Otel Collector Stack
Source: https://docs.railway.com/tutorials/deploy-an-otel-collector-stack
Monitor and trace your applications by deploying an OpenTelemetry Collector and backend on Railway.
> OpenTelemetry is an Observability framework and toolkit designed to create and manage telemetry data such as traces, metrics, and logs. Crucially, OpenTelemetry is vendor- and tool-agnostic, meaning that it can be used with a broad variety of Observability backends, including open source tools like Jaeger and Prometheus, as well as commercial offerings.
## About this Tutorial
There is an overwhelming number of options for applying OpenTelemetry in your software stack. This tutorial uses the libraries and tools endorsed and/or maintained by the OpenTelemetry community.
OpenTelemetry is commonly referred to simply as "Otel". You will see both terms used throughout this tutorial.
**Objectives**
In this tutorial you will learn how to -
- Deploy the OpenTelemetry Collector, listening for traces, metrics, and logs.
- Deploy a backend stack (Jaeger, Zipkin, and Prometheus) to receive the traces, metrics, and logs from the collector
- Build and instrument an Express application to send data to the collector.
**Prerequisites**
To be successful using this tutorial, you should already have -
- Latest version of Railway CLI installed
- A GitHub account
**OpenTelemetry Collector Template and Demo**
If you are looking for a quicker way to get started, you can deploy the collector and backend stack from a template by clicking the button below.
We also have a live demo of the project you will build in this tutorial here, and you can access the code repository here in Github. You can find some example apps, including the one we will build in this tutorial, in the exampleApps folder.
**Let's get started!**
## 1. Deploy the Backend Services
First, we will deploy the backend services:
- Jaeger - an open-source, distributed tracing system that will receive telemetry data from the collector
- Zipkin - also an open-source, distributed tracing system that will receive telemetry data from the collector
- Prometheus - an open-souce, systems monitoring and alerting toolkit that will receive telemetry data from the collector
_Jaeger and Zipkin offer similar functionality, and it is not necessary to run both. The intent is to give you different examples of backend services._
Each of the following steps should be completed in the same Railway project.
### Add Jaeger Service
- Add a New service by clicking + New
- Select Docker Image as the Source
- Add jaegertracing/all-in-one as the image name and hit Enter
- Add the following variable to the service
_This is the port that serves the UI. Setting this variable allows you to access the Jaeger UI from your browser_
- In the Settings tab, rename the service Jaeger
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
You should be able to access the Jaeger UI by clicking on the service domain.
### Add Zipkin Service
- Add a New service by clicking + New
- Select Docker Image as the Source
- Add openzipkin/zipkin as the image name and hit Enter
- Add the following variable to the service
_This is the port that serves the UI. Setting this variable allows you to access the Zipkin UI from your browser_
- In the Settings tab, rename the service Zipkin
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
You should be able to access the Zipkin UI by clicking on the service domain.
### Add Prometheus Service
- Add a New service by clicking + New
- Select Template as the Source
- Type Prometheus and select the Prometheus template (be sure to select this one)
- Click Deploy to apply and deploy the service
_The template deploys with the proper UI port already configured to enable accessing the Prometheus UI from your browser_
You should be able to access the Prometheus UI by clicking on the service domain.
## 2. Deploy the OpenTelemetry Collector
The OpenTelemetry Collector is a vendor-agnostic service that receives, processes, and exports telemetry data.
It is not strictly necessary to run a collector when implementing OpenTelemetry, but it is recommended by the OpenTelemetry community. More information on the subject can be found here.
### Fork the Open Telemetry Collector repository
- Navigate to the Open Telemetry Collector repository in GitHub
- Click Fork then Create fork
### Add the Open Telemetry Service
In the Railway project -
- Add a New service by clicking + New
- Select GitHub Repo as the Source
- Select the opentelemetry-collector-stack repository (if you renamed the repo in the previous step, yours will be named differently)
- Add the following variable to the service
_This is the port that serves the collector's debugging UI. Setting this variable allows you to access the UI from your browser_
- In the Settings tab, rename the service OpenTelemetry Collector
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
The Collector's debugging UI is enabled by default and accessible from the browser. This is controlled by the inclusion of the zpages extension in the collector's configuration yaml. You can read more about the UI and the available routes, in the collector's source repo.
---
## Checkpoint
Congrats! You should now have a working OpenTelemetry Collector along with a backend stack to which the collector will forward data. Your project in Railway should look something like this -
/rolldice?rolls=10
Generate some traffic to this route, updating the number of rolls to different numbers, and verify that you see traces and spans in Jaeger and Zipkin.
OTEL_LOG_LEVEL=debug
# Add a CDN using CloudFront
Source: https://docs.railway.com/tutorials/add-a-cdn-using-cloudfront
Learn how to integrate Amazon CloudFront as a CDN for your Fastify app in this step-by-step guide.
> A CDN improves efficiency [of web applications] by introducing intermedeiary servers between the client and the server. [These CDN servers] decrease web traffic to the web server, reduce bandwidth consumption, and improve the user experience of your applications.
_Source: What is a CDN?_
## About this Tutorial
We know that performance of your web applications is critical to your business, and one way to achieve higher performance is by implementing a CDN to serve data from servers closest to your users.
Many CDN options are available (list from G2), but in this tutorial, we will cover step-by-step how to implement a CDN using Amazon CloudFront.
**Objectives**
In this tutorial, you will learn how to -
- Deploy a simple Fastify server to Railway
- Create a CloudFront distribution in AWS and connect it to the Fastify server
- _(Optional)_ Setup SSL and DNS for a custom domain managed in Namecheap
**Prerequisites**
To be successful using this tutorial, you should already have -
- Latest version of the Railway CLI installed
- An AWS account with permissions to create new resources
- Latest version of the AWS CLI installed and authenticated to your AWS account
- Latest version of the AWS CDK installed
- _(Optional)_ A Namecheap account to connect a custom domain
**Let's get started!**
## 1. Create and Deploy a Fastify Server
First, let's create and deploy a simple Fastify server using the Railway CLI
- On your local machine, create a folder called "fastify"
- Inside of the folder, create a file called "server.js"
- Run the following commands to initialize the project and install the required packages using npm
- Add the following code to the "server.js" file
- Run the following command to initialize a new project in Railway
- Follow the prompts and name your project "fastify-cdn"
- Run the following command to deploy your Fastify server
- Run the following command to generate a domain for the Fastify service
- Run the following command to open your Railway project in your browser
### Checkpoint
Nice! You now have a Fastify server running in Railway serving three routes, which will serve to demonstrate a few different concepts related to caching:
- /static - the static route serves a static message which never changes, unless the code is updated
- /dynamic - the dynamic route servers a dynamic message which changes when the route is accessed and the Date() function runs
- /staticEtag - the staticEtag route demonstrates how you can manually set an HTTP Etag on a route
_Note: The Fastify server code above implements Fastify's eTag plugin._
#### Observe Route Behavior with no CDN
To observe the behavior without a CDN in place, navigate to any of the routes above from the Railway-provided domain, your request will always go directly to the service running in Railway.
One way you can visualize this, is by navigating to the /static route in your browser, opening up Network Tools, and observing that each request always receives a **HTTP 200** status code:
..rds.amazonaws.com. You can grab this from the output of the terraform run we did earlier, or in the AWS console.
- **TS_AUTH_KEY**: The tailscale auth key we set up earlier. In the format: tskey-auth-0123456789
- **TS_HOSTNAME**: The friendly DNS name you can reference in your Tailnet. You can name this whatever you want. railtail or railtail-project-name is a good name here.
Click **Deploy Template**.
## Bridge Traffic to RDS
Now you can connect any service to your RDS backend. Add a variable to your connecting Service like: DATABASE_URL="postgresql://USERNAME:PASSWORD@${{railtail.RAILWAY_PRIVATE_DOMAIN}}:${{railtail.LISTEN_PORT}}/postgres"
That's it! Now you're bridging traffic privately from Railway to RDS.
postgres rds-tailscale
psql -h -U postgres -d tailscale_test_db
terraform destroy -auto-approve
# Post-Deploy
Source: https://docs.railway.com/tutorials/github-actions-post-deploy
Learn how to use GitHub Actions to run post-deployment commands.
At Railway, we've set up Github triggers for automatic deployments when you push to a selected branch, and with Github Actions, you can automate several parts of your development workflow. Recently, within our Discord and Slack, we've had a couple of users ask us how they'd go about running commands or webhooks after their app is deployed so we thought it'd be a good idea to publish a short tutorial doing just that, with Github Actions.
## The Action
Since Railway makes the deployment status available to Github, we'll be using the deployment_status event to trigger our action. This event is triggered when a deployment status changes, and we'll be using the success state to trigger our action.
Make a new file in your repository called .github/workflows/post-deploy.yml and add the following -
If you have your repository deploying to multiple services, you can modify the if condition to check for the service you want to run the command for -
You can also see what github.event contains and build your own conditions from there.
Information on how to find the Service ID and Environment IDs as needed can be found here.
It's that simple! You can now customize the final run step to execute any commands or send webhooks using Curl or other methods of your choice.
## Conclusion
We hope this tutorial has been helpful and that you'll find it useful for your own projects. If you have any questions or feedback, please feel free to reach out to us on Discord, Slack or the Central Station. Happy coding!
## Code Examples
name: Post-Deployment Actions
on:
deployment_status:
states: [success]
jobs:
post-deploy:
runs-on: ubuntu-latest
if: github.event.deployment_status.state == 'success'
steps:
- name: Debug - Print github.event object
run: |
echo "github.event context:"
echo '${{ toJSON(github.event) }}'
# Only run if this is a production environment deployment that succeeded
- name: Run post-deploy actions
if: github.event.deployment.environment == 'production'
run: |
echo "Production deployment succeeded"
if: github.event.deployment.environment == 'production' && github.event.deployment.payload.serviceId == ''
# PR Environment
Source: https://docs.railway.com/tutorials/github-actions-pr-environment
Learn how to use the CLI in a GitHub Action to create environments for PRs
This can be useful if you need to create a branch on a Neon database, allowing you to automatically inject the correct database url.
## The Action
Make a new file in your repository called .github/workflows/railway-pr-envs.yml and add the following -
**Note:** if you are using a team project, you need to ensure that the token specified is scoped to your account, not a workspace.
This can very easily be modified to run commands in order to find variables and values, and can simply be passed as flags to the railway environment create command.
## Conclusion
We hope this tutorial has been helpful and that you'll find it useful for your own projects. If you have any questions or feedback, please feel free to reach out to us on Discord, Slack or the Central Station. Happy coding!
## Code Examples
# NOTE
# if you have 2fa on your account, the pr close part of the action will hang (due to 2fa not being supported non-interactively)
name: Manage PR environments (Railway)
on:
pull_request:
types: [opened, closed]
env:
RAILWAY_API_TOKEN: "" # get this in account settings (make sure this is NOT a project token), and scope it to your account (not a workspace)
SERVICE_ID: "" # service ID to inject database variable into
ENV_NAME: "" # the environment variable name to inject (e.g DATABASE_URL)
ENV_VALUE: "" # the value to inject
DUPLICATE_FROM_ID: "" # railway environment to duplicate from
LINK_PROJECT_ID: "" # project ID
# TEAM_ID: "" if you are linking to a project in team, uncomment this
jobs:
pr_opened:
if: github.event.action == 'opened'
runs-on: ubuntu-latest
container: ghcr.io/railwayapp/cli:latest
steps:
- name: Link to project
run: railway link --project ${{ env.LINK_PROJECT_ID }} --environment ${{ env.DUPLICATE_FROM_ID }} # --team ${{ env.TEAM_ID }} # uncomment this if you are linking to a team project
- name: Create Railway Environment for PR
run: railway environment new pr-${{ github.event.pull_request.number }} --copy ${{ env.DUPLICATE_FROM_ID }} --service-variable ${{ env.SERVICE_ID }} "${{ env.ENV_NAME }}=${{ env.ENV_VALUE }}"
pr_closed:
if: github.event.action == 'closed'
runs-on: ubuntu-latest
container: ghcr.io/railwayapp/cli:latest
steps:
- name: Link to project
run: railway link --project ${{ env.LINK_PROJECT_ID }} --environment ${{ env.DUPLICATE_FROM_ID }} # --team ${{ env.TEAM_ID }} # uncomment this if you are linking to a team project
- name: Delete Railway Environment for PR
run: railway environment delete pr-${{ github.event.pull_request.number }} || true
# Self Hosted Runners
Source: https://docs.railway.com/tutorials/github-actions-runners
Learn how to deploy your own scalable self hosted GitHub Actions Runners on Railway. Build your own fleet of runners for your Enterprise and then scale your self-hosted runners with Railway replicas for blazing fast builds.
"
alt="screenshot of a deployment of a self hosted GitHub Actions runner on Railway"
layout="responsive"
width={1211} height={820} quality={100} />
Deploying GitHub Actions Self Hosted Runners on Railway is an excellent way to run your own CI infrastructure because you only pay for what you use. With self-hosted runners, you also unlock the ability to cache expensive and time-consuming dependencies (node_modules, cargo, etc.) or large git repositories. Best of all, Railway's built-in replicas means you can scale your runners horizontally, or even distribute them to different regions with just a click and redeploy. You'll save build times and costs over using standard runners, _AND_ you'll unlock more sophistocated workflows to streamline building your app.
In this guide you'll learn:
1. The basics to deploy a GitHub Actions Self Hosted Runner on Railway.
1. How to authenticate self-hosted runners on Railway with your GitHub Organization or Enterprise.
1. How to scale up replicas to serve bigger Actions workloads.
1. Best Practices for configuring your self-hosted runners on Railway.
**Quickstart:** Deploy your self-hosted Runners with our Railway template.
## Deploy a GitHub self-hosted runner on Railway
1. Navigate to the GitHub Actions self-hosted Runner Template. You'll notice the template requires an ACCESS_TOKEN. This token, along with our RUNNER_SCOPE will determine _where_ our self-hosted runners get registered on GitHub. Thankfully, this template supports self registration of your runners -- which means you can dynamically scale up or down the number of runners you have just by adjusting your replicas!
2. Set your RUNNER_SCOPE to org. We want to set up our self-hosted runners to register with a GitHub Organization, so any repositories within our organization can use the same pool of runners. This is super useful because you don't have to set up permissions for every single repository!
If you have a GitHub Enterprise, you can similarly set up your runners using an ACCESS_TOKEN, you just need to set your RUNNER_SCOPE as ent instead.
If you need additional configuration, then you can simply add a variable to your Service.
## Setup a GitHub ACCESS_TOKEN
For this guide, we will create a new GitHub Fine-Grained Personal Access Token. These are modern personal access tokens that obey the principle of least privilege, making them easy to secure, revoke, and audit!
**Note:** You need to have Admin access to the organization for which you are making the ACCESS_TOKEN.
.yml. You can easily incorporate pre-built steps to get up-and-running quickly.
- When you want to run a workflow every time a pull request is opened, set the on key to pull_request in your .github/workflows/.yml.
- Set the runs-on key when you want to route your workflow job to a particular runner. Use a comma delimited list for greater specificity. For example, a [self-hosted, linux, x86, railway] workflow needs to match all labels to an appropriate runner in order to route the job correctly.
## Example GitHub Actions Workflow
If you've never made a workflow before, here is a basic out-of-the-box example of a NuxtJS project using Bun to execute an eslint check.
## Best Practices
1. **Only use private repositories and disable forks:** Make sure when using self-hosted runners, that you only attach them to private repositories. A known attack vector is for a malicious actor to fork a public repository and then exfiltrate your private keys from your self-hosted runners by executing workflows on them. Disabling forks can also mitigate this attack, and it's a good idea in general for locking down security on your repositories!
1. **Seal your ACCESS_KEY:** While all variables are encrypted on Railway, you can prevent prying eyes (including your future self) from ever viewing your API Key. Navigate to the Variables tab and next to the ACCESS_KEY variable click the three-dots-menu ... -> Seal. Make sure your ACCESS_KEY is stored in a secure Password Vault before doing this!
1. **Security Harden your self-hosted Runners:** Security Hardening will make your runners robust and prevent any concerns about your build infrastructure. GitHub's detailed guide can help you secure secrets, authentication, auditing, and managing your runners. Similarly dduzgun-security and Wiz both have excellent guides to securing your runners that are worth your time.
### Known Limitations
- Because Railway containers are non-privileged, GitHub Workflows that build-and-then-mount containers on the same host (i.e. Docker-in-Docker) will fail.
- Using the Serverless Setting on this Service is _not_ recommended and will result in idle runners disconnecting from GitHub and needing to reauthenticate. GitHub Runners have a 50 second HTTP longpoll which keeps them alive. While the runners in this template can automatically reauth with an ACCESS_TOKEN it will result in unnecessary offline / abandoned runners. If you want your runners to deauthenticate and spin down, consider using ephemeral runners instead.
### Troubleshooting self-hosted runner communication
> A self-hosted runner connects to GitHub to receive job assignments and to download new versions of the runner application. The self-hosted runner uses an HTTPS long poll that opens a connection to GitHub for 50 seconds, and if no response is received, it then times out and creates a new long poll. The application must be running on the machine to accept and run GitHub Actions jobs.
GitHub's documentation details all of the different endpoints your self-hosted runner needs to communicate with. If you are operating in a GitHub Allow List environment you must add your self-hosted runners IP Address to this allow list for communication to work.
If you are using a proxy server, refer to GitHub's documentation on configuring your self-hosted runner. You can simply add the required environment variables by adding them to the Variables tab of your Service.
### Cost Comparison
On Railway you only pay for what you use, so you'll find your GitHub workflows are significantly cheaper. For this guide we tested over ~2,300 1 minute builds on Railway self-hosted runners and our usage costs were $1.80 compared to GitHub's Estimated Hosted Runner cost of $18.40 for the same workload. Even better? We had 10x Railway replicas with 32 vCPU and 32GB RAM for this test, meaning that our actions workflows would never slow down.
On other platforms you pay for the _maximum available_ vCPUs and Memory. On Railway, you're only paying for usage, or in the below screenshot, the filled in purple area. This enables your workloads to still burst up to the _maximum available_ resources you have configured, with no tradeoffs on cost.
- The local shell via railway shell
In Railway, there is also a notion of configuration variables which allow you to control the behavior of the platform.
## Template Syntax
Railway's templating syntax gives you flexibility in managing variables:
- NAMESPACE - The value for NAMESPACE is determined by the location of the variable being referenced. For a shared variable, the namespace is "shared". For a variable defined in another service, the namespace is the name of the service, e.g. "Postgres" or "backend-api".
- VAR - The value for VAR is the name, or key, of the variable being referenced.
You can also combine additional text or even other variables, to construct the values that you need:
## Types of Variables
In Railway, there is a notion of service variables, shared variables, reference variables, sealed variables, and a few kinds of reserved variables.
### Service Variables
Service variables are scoped to a specific service. They can be referenced in other services by using a Reference Variable.
### Shared Variables
Shared variables are scoped to a project and environment. They help reduce duplication of variables across multiple services within the same project.
### Reference Variables
Reference variables are those defined by referencing variables in other services, shared variables, or even variables in the same service. This is useful for ease of maintenance, allowing you to set a variable in a single place and reference it as needed.
Reference variables use Railway's template syntax.
### Sealed Variables
Sealed variables are scoped to a specific service. Once a variable is sealed, its value is not visible via the UI or the Railway API.
### Variable Functions
Template variable functions allow you to dynamically generate variables (or parts of a variable) on demand when the template is deployed.
### Railway-Provided Variables
Railway provides the following additional system environment variables to all
builds and deployments.
| Name | Description |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| RAILWAY_PUBLIC_DOMAIN | The public service or customer domain, of the form example.up.railway.app |
| RAILWAY_PRIVATE_DOMAIN | The private DNS name of the service. |
| RAILWAY_TCP_PROXY_DOMAIN | (see TCP Proxy for details) The public TCP proxy domain for the service, if applicable. Example: roundhouse.proxy.rlwy.net |
| RAILWAY_TCP_PROXY_PORT | (see TCP Proxy for details) The external port for the TCP Proxy, if applicable. Example: 11105 |
| RAILWAY_TCP_APPLICATION_PORT | (see TCP Proxy for details) The internal port for the TCP Proxy, if applicable. Example: 25565 |
| RAILWAY_PROJECT_NAME | The project name the service belongs to. |
| RAILWAY_PROJECT_ID | The project id the service belongs to. |
| RAILWAY_ENVIRONMENT_NAME | The environment name of the service instance. |
| RAILWAY_ENVIRONMENT_ID | The environment id of the service instance. |
| RAILWAY_SERVICE_NAME | The service name. |
| RAILWAY_SERVICE_ID | The service id. |
| RAILWAY_REPLICA_ID | The replica ID for the deployment. |
| RAILWAY_REPLICA_REGION | The region where the replica is deployed. Example: us-west2 |
| RAILWAY_DEPLOYMENT_ID | The ID for the deployment. |
| RAILWAY_SNAPSHOT_ID | The snapshot ID for the deployment. |
| RAILWAY_VOLUME_NAME | The name of the attached volume, if any. Example: foobar |
| RAILWAY_VOLUME_MOUNT_PATH | The mount path of the attached volume, if any. Example: /data |
### Git Variables
These variables are provided if the deploy originated from a GitHub trigger.
| Name | Description |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RAILWAY_GIT_COMMIT_SHA | The git SHA of the commit that triggered the deployment. Example: d0beb8f5c55b36df7d674d55965a23b8d54ad69b |
| RAILWAY_GIT_AUTHOR | The user of the commit that triggered the deployment. Example: gschier |
| RAILWAY_GIT_BRANCH | The branch that triggered the deployment. Example: main |
| RAILWAY_GIT_REPO_NAME | The name of the repository that triggered the deployment. Example: myproject |
| RAILWAY_GIT_REPO_OWNER | The name of the repository owner that triggered the deployment. Example: mycompany |
| RAILWAY_GIT_COMMIT_MESSAGE | The message of the commit that triggered the deployment. Example: Fixed a few bugs |
### User-Provided Configuration Variables
Users can use the following environment variables to configure Railway's behavior.
| Name | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| RAILWAY_DEPLOYMENT_OVERLAP_SECONDS | How long the old deploy will overlap with the newest one being deployed, its default value is 0. Example: 20 |
| RAILWAY_DOCKERFILE_PATH | The path to the Dockerfile to be used by the service, its default value is Dockerfile. Example: Railway.dockerfile |
| NIXPACKS_CONFIG_FILE | The path to the Nixpacks configuration file relative to the root of the app, its default value is nixpacks.toml. Example: frontend.nixpacks.toml |
| NIXPACKS_VERSION | The version of Nixpacks to use, if unspecfied a default version will be used. Example: 1.29.1 |
| RAILWAY_HEALTHCHECK_TIMEOUT_SEC | The timeout length (in seconds) of healthchecks. Example: 300 |
| RAILWAY_DEPLOYMENT_DRAINING_SECONDS | The SIGTERM to SIGKILL buffer time (in seconds), its default value is 0. Example: 30 |
| RAILWAY_RUN_UID | The UID of the user which should run the main process inside the container. Set to 0 to explicitly run as root. |
| RAILWAY_SHM_SIZE_BYTES | This variable accepts a value in binary bytes, with a default value of 67108864 bytes (64 MB) |
## Support
For information on how to use variables refer to the Variables guide.
## Dockerfiles
For information on how to use variables in your Dockerfile refer to the Dockerfiles guide.
## Code Examples
${{NAMESPACE.VAR}}
DOMAIN=${{shared.DOMAIN}}
GRAPHQL_PATH=/v1/gql
GRAPHQL_ENDPOINT=https://${{DOMAIN}}/${{GRAPHQL_PATH}}
# Volumes
Source: https://docs.railway.com/reference/volumes
Volumes are a feature that enables persistent data for services on Railway.
## How it works
When mounting a volume to a service, a volume is made available to the service on the specified mount path.
## Size Limits
Volumes have a default size based on the subscription plan.
- Free and Trial plans: **0.5GB**
- Hobby plans: **5GB**
- Pro and team plans: **50GB**
Volumes can be "Grown" after upgrading to a different plan.
Pro users and above can self-serve to increase their volume up to 250 GB.
For Pro and above users, please reach out to us on our Central Station if you need more than 250GB. Enterprise users with $2,000/month committed spend can also use Slack.
## I/O Specifications
Volumes have the following I/O characteristics:
- **Read IOPS**: 3,000 operations per second
- **Write IOPS**: 3,000 operations per second
These specifications apply to all volume sizes and subscription plans.
## Pricing
Volumes are billed at a rate per GB / minutely, and invoiced monthly. You can find specific per-minute pricing here.
You are only charged for the amount of storage used by your volumes. _Each volume requires approx 2-3% of the total storage to store metadata about the filesystem, so a new volume will always start with some used amount of space used depending on the size._
## Backups
Services with volumes support manual and automated backups, backups are covered in the backups reference guide.
## Caveats
Here are some limitations of which we are currently aware:
- Each service can only have a single volume
- Replicas cannot be used with volumes
- There is no built-in S/FTP support
- To prevent data corruption, we prevent multiple deployments from being active
and mounted to the same service. This means that there will be a small amount
of downtime when re-deploying a service that has a volume attached, even if there is a healthcheck endpoint configured
- Down-sizing a volume is not currently supported, but increasing size is supported
- When resizing a volume, all deployments must be taken offline to prevent data
corruption
- There is no file browser, or direct file download. To access your files,
you must do so via the attached service's mount point
- Docker images that run as a non-root UID by default will have permissions issues when performing operations within an attached volume. If you are affected by this, you can set RAILWAY_RUN_UID=0 environment variable in your service.
## Support
Refer to the guide on how to use volumes for more details on how to use the feature.
# Functions
Source: https://docs.railway.com/reference/functions
Write and deploy code from the Railway canvas without managing infrastructure or creating a git repository.
Functions are Services that run a single file of TypeScript code using the Bun runtime.
Use them like any other Service, but without the overhead of a repository.
They are ideal for small tasks like handling webhooks, cron jobs, or simple APIs.
## Key features
- **Instant deploys**: Deploy code changes _in seconds_. No need to wait for a build step.
- **Import any NPM package**: Use any NPM package in your function. We will automatically install it for you when your code runs. Pin specific versions by using a package@version syntax in your imports, e.g. import { Hono } from "hono@4"
- **Use native Bun APIs**: Access Bun APIs like Bun.file() and Bun.serve().
- **Service variables**: Service Variables are automatically available in the function editor via import.meta.env, process.env, or Bun.env
- **Attach volumes**: Persist data in your function using Volumes.
- **Use Vim**: Enable Vim keybindings in the function editor by using the shortcut Cmd+Option+V on a Mac or Ctrl+Alt+V on Windows.
- Subdomains and wildcards cannot overlap (foo.hello.com cannot exist with *.hello.com unless owned by the same service).
- Root domains need a DNS provider with ALIAS records or CNAME flattening.
- Unicode domains should be PUNYcode encoded.
- Non-public/internal domain names are not supported. | | **Certificate Issuance** | - Railway attempts to issue a certificate for **up to 72 hours** after domain creation before failing.
- Certificates are expected to be issued within an hour. | | **TLS** | - Support for TLS 1.2 and TLS 1.3 with specific cipher sets.
- Certificates are valid for 90 days and renewed every 30 days. | | **Edge Traffic** | - Support for HTTP/1.1.
- Support for websockets over HTTP/1.1.
- Proxy Keep-Alive timeout of 60 seconds (1 minute).
- Max 32 KB Combined Header Size
- Max duration of 15 minutes for HTTP requests. | | **Request Headers** | - X-Real-IP for identifying client's remote IP.
- X-Forwarded-Proto always indicates https.
- X-Forwarded-Host for identifying the original host header.
- X-Railway-Edge for identifying the edge region that handled the request.
- X-Request-Start for identifying the time the request was received (Unix milliseconds timestamp).
- X-Railway-Request-Id for correlating requests against network logs. | | **Requests** | - Inbound traffic must be TLS-encrypted
- HTTP GET requests to port 80 are redirected to HTTPS.
- HTTP POST requests to port 80 are redirected to HTTPS as GET requests.
- SNI is required for correct certificate matching. | ## Domain Rate Limits _This information is subject to change at any time._ To ensure the integrity and performance of our network, we enforce the following limits for all services. | Category | Limit | Description | | --------------------------- | ----------------------------- | --------------------------------------------------------- | | **Maximum Connections** | 10,000 concurrent connections | The number of concurrent connections. | | **HTTP Requests/Sec** | 3,000 RPS | The number of HTTP requests to a given domain per second. | | **Requests Per Connection** | 10,000 requests | The number of requests each connection can make. | If your application requires higher limits, please don't hesitate to reach out to us at team@railway.com. ## Custom Domain Count Limits The Hobby plan is limited to 2 custom domains per service. The Pro Plan is limited to 20 domains per service by default but can be increased for Pro users on request, by reaching out to us at team@railway.com or via private thread. ## FAQ
We currently support HTTP and HTTP2 traffic from the internet to your services.
All traffic must be HTTPS and use TLS 1.2 or above, and TLS SNI is mandatory for requests.
- Plain HTTP GET requests will be redirected to HTTPS with a 301 response.
- Plain HTTP POST requests will be converted to GET requests.
For services that require TCP traffic, like databases, we also have a TCP Proxy feature.
We provide LetsEncrypt SSL certificates using RSA 2048bit keys. Certificates are valid for 90 days and are automatically renewed 2 months into their life.
Certificate issuance should happen within an hour of your DNS being updated with the values we provide.
For proxied domains (Cloudflare orange cloud), we may not always be able to issue a certificate for the domain, but Cloudflare to Railway traffic will be encrypted with TLS using our default *.up.railway.app certificate.
Railway Metal infrastructure is built to mitigate attacks at network layer 4 and below, however we do not provide protection on the application layer. If you need WAF functionality, we recommend using Cloudflare alongside Railway.
To have traffic from the public internet properly forwarded to your service's exposed port, you must ensure that you are properly using the PORT environment variable made available to every service deployment.
- If your application is listening on an explicitly defined port, you must define a PORT variable with the proper assignment in your service's variables.
- If you do not explicitly define the PORT, Railway provides one for you and exposes it during deployment.
More on this in the Public Networking guide.
# Outbound Networking
Source: https://docs.railway.com/reference/outbound-networking
Learn about outbound networking features and email delivery options on Railway.
## Email Delivery
SMTP is only available on the Pro plan and above.
Free, Trial, and Hobby plans must use transactional email services with HTTPS APIs. SMTP is disabled on these plans to prevent spam and abuse. However, even when SMTP is available, we recommend transactional email services with HTTPS APIs for all plans due to their enhanced features and analytics.
Upon upgrading to Pro, please re-deploy your service that needs to use SMTP for the changes to take effect.
### Email Service Examples
Here are examples of transactional email services you can use:
**Note:** These services are required for Free, Trial, and Hobby plans since outbound SMTP is disabled.
- Resend - **Railway's recommended approach**
- SendGrid
- Mailgun
- Postmark
These services provide detailed analytics and robust APIs designed for modern applications. They also work on all Railway plans since they use HTTPS instead of SMTP.
### Debugging SMTP Issues
If you are experiencing issues with SMTP on the Pro plan, please the follow the steps below to help us diagnose the problem:
1. First, ensure that you have tried re-deploying your service
2. SSH into your service using the Railway CLI:
The link above takes you to the usage page for your personal account. If you want to set a usage limit for your team, you can use the account switcher in the top left corner of your dashboard to access the team's usage page.
## Custom Email Alert
You can think of this as a _soft limit_. When your resource usage reaches the specified amount, we will email you that this threshold has been met. Your resources will remain unaffected.
## Hard Limit
Once your resource usage hits the specified hard limit, all your workloads will be taken offline to prevent them from incurring further resource usage. Think of the hard limit as the absolute maximum amount you're willing to spend on your infrastructure.
We will send you multiple reminders as your usage approaches your hard limit:
1. When your usage reaches 75% of your hard limit
2. When your usage reaches 90% of your hard limit
We will send you another email if your workloads are taken down due to your specified usage limits.
Setting a hard limit is a possibly destructive action as you're risking having all your resources shut down once your usage crosses the specified amount.
## FAQ
Yes, usage limits are available for all subscription plans.
No. You can leave the hard limit blank if you simply want to be notified at a particular amount of usage.
The minimum amount you can specify as the hard limit is $10.
To restart your resources, you can either increase your usage limit or remove it entirely.
For guidance on restarting your resources, please refer to our FAQ section.
No. Once your resources are shut down, it is your responsibility to restart them.
# CLI API
Source: https://docs.railway.com/reference/cli-api
Learn about the Railway CLI commands.
Railway project from the command line.
This document describes the commands available in the CLI.
For information on how to install the CLI and more examples of usage, see the CLI guide.
## Add
_Add a service to your project_
## Completion
_Generate a shell-completions for the following shells: bash, elvish, fish, and powershell_
## Connect
_Connect to a database's shell (psql for Postgres, mongosh for MongoDB, etc.)_
This requires you to have the database's appropriate shell/client installed in your $PATH:
- Postgres: psql (https://www.postgresql.org/docs/current/app-psql.html)
- Redis: redis-cli (https://redis.io/docs/ui/cli/)
- MongoDB: mongosh (https://www.mongodb.com/docs/mongodb-shell/)
- MySQL: mysql (https://dev.mysql.com/doc/refman/8.0/en/mysql.html)
## Deploy
_Deploy a template into your project_
## Domain
_Create a domain for a service_
## Docs
_Open the Railway documentation site in the default browser_
````
## Down
_Remove the most recent deployment_
## Environment
_Create, delete or link an environment_
View environment docs for more information.
If you run railway environment without specifying a name, you will be prompted
with an environment selector that lists all your environments for the project.
### railway environment new
_Create a new environment_
### railway environment delete
_Delete an environment_
**Note**: railway environment delete will not work if an account has 2FA and the terminal is not being run interactively.
## Init
_Create a new Project from the CLI_
## Link
_Connect to an existing Railway project_
Running link with no project ID will prompt you to select a team and project.
## List
_List all projects in your Railway account_
## Login
_Login to your Railway account_
This will open the browser to https://railway.com/cli-login.
### Browserless
If you are in an environment where the terminal cannot open a web browser, (i.e.
SSH session or Codespaces), you can
perform a _browserless_ login.
This will prompt you to go to a URL (you can copy and paste) and present you
with a 4 word code that you need to verify. If the codes match, click "Verify"
and you will be logged in.
## Logout
_Logout of your Railway account_
## Logs
_View logs for the most recent deployment_
## Open
_Open your current Railway project in the browser_
## Run
_Run a command using the Railway environment_
This also injects all environment variables associated with the databases you have
installed in your project.
## Service
_Link a service to the current project_
## Shell
_Create a subshell (based on $SHELL) with all the variables from your project/environment/service loaded and accessible_
## SSH
_SSH into a project/service_
## Status
_View the status of your Railway project and user_
## Unlink
_Disconnects the current directory from Railway_
You will need to rerun railway link to use railway in this directory again.
## Up
_Deploy a directory to your Railway project_
If no path is provided, the top linked directory is deployed. The currently selected environment is used.
## Variables
_View a table of all the environment variables associated with your project and environment_
## Whoami
_View what user is currently authenticated with Railway_
## Volume
_Manage project volumes with options to list, add, delete, update, attach, and detach volumes_
## Redeploy
_Redeploy the currently deployed version of a service_
## Help
_Help command reference_
## Code Examples
~ railway add --help
Add a service to your project
Usage: railway add [OPTIONS]
Options:
-d, --database
The name of the database to add
[possible values: postgres, mysql, redis, mongo]
-s, --service []
The name of the service to create (leave blank for randomly generated)
-r, --repo
The repo to link to the service
-i, --image
The docker image to link to the service
-v, --variables
The "{key}={value}" environment variable pair to set the service variables. Example:
railway add --service --variables "MY_SPECIAL_ENV_VAR=1" --variables "BACKEND_PORT=3000"
--json
Output in JSON format
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
~ railway completion --help
Generate completion script
Usage: railway completion [OPTIONS]
Arguments:
[possible values: bash, elvish, fish, powershell, zsh]
Options:
--json Output in JSON format
-h, --help Print help
-V, --version Print version
~ railway connect --help
Connect to a database's shell (psql for Postgres, mongosh for MongoDB, etc.)
Usage: railway connect [OPTIONS] [SERVICE_NAME]
Arguments:
[SERVICE_NAME] The name of the database to connect to
Options:
-e, --environment Environment to pull variables from (defaults to linked environment)
--json Output in JSON format
-h, --help Print help
-V, --version Print version
railway deploy --help
Provisions a template into your project
Usage: railway deploy [OPTIONS]
Options:
-t, --template The code of the template to deploy
-v, --variable The "{key}={value}" environment variable pair to set the template variables
To specify the variable for a single service prefix it with "{service}." Example:
bash railway deploy -t postgres -v "MY_SPECIAL_ENV_VAR=1" -v "Backend.Port=3000"
--json Output in JSON format
-h, --help Print help (see a summary with '-h')
-V, --version Print version
~ railway domain --help
Add a custom domain or generate a railway provided domain for a service
Usage: railway domain [OPTIONS] [DOMAIN]
Arguments:
[DOMAIN] Optionally, specify a custom domain to use. If not specified, a domain will be generated
Options:
-p, --port The port to connect to the domain
-s, --service The name of the service to generate the domain for
--json Output in JSON format
-h, --help Print help (see more with '--help')
-V, --version Print version
`~ railway docs --help
Open Railway Documentation in default browser
Usage: railway docs [OPTIONS]
Options:
--json Output in JSON format
-h, --help Print help
-V, --version Print version
`
## Down
_Remove the most recent deployment_
## Environment
_Create, delete or link an environment_
View [environment docs](/reference/environments) for more information.
If you run `railway environment` without specifying a name, you will be prompted
with an environment selector that lists all your environments for the project.
### railway environment new
_Create a new environment_
### railway environment delete
_Delete an environment_
**Note**: `railway environment delete` will not work if an account has 2FA and the terminal is not being run interactively.
## Init
_Create a new Project from the CLI_
## Link
_Connect to an existing Railway project_
Running `link` with no project ID will prompt you to select a team and project.
## List
_List all projects in your Railway account_
## Login
_Login to your Railway account_
This will open the browser to `https://railway.com/cli-login`.
### Browserless
If you are in an environment where the terminal cannot open a web browser, (i.e.
SSH session or [Codespaces](https://github.com/features/codespaces)), you can
perform a _browserless_ login.
This will prompt you to go to a URL (you can copy and paste) and present you
with a 4 word code that you need to verify. If the codes match, click "Verify"
and you will be logged in.
## Logout
_Logout of your Railway account_
## Logs
_View logs for the most recent deployment_
## Open
_Open your current Railway project in the browser_
## Run
_Run a command using the Railway environment_
This also injects all environment variables associated with the databases you have
installed in your project.
## Service
_Link a service to the current project_
## Shell
_Create a subshell (based on `$SHELL`) with all the variables from your project/environment/service loaded and accessible_
## SSH
_SSH into a project/service_
## Status
_View the status of your Railway project and user_
## Unlink
_Disconnects the current directory from Railway_
You will need to rerun `railway link` to use `railway` in this directory again.
## Up
_Deploy a directory to your Railway project_
If no path is provided, the top linked directory is deployed. The currently selected environment is used.
## Variables
_View a table of all the environment variables associated with your project and environment_
## Whoami
_View what user is currently authenticated with Railway_
## Volume
_Manage project volumes with options to list, add, delete, update, attach, and detach volumes_
## Redeploy
_Redeploy the currently deployed version of a service_
## Help
_Help command reference_
# MCP Server
Source: https://docs.railway.com/reference/mcp-server
Learn about the official Railway MCP (Model Context Protocol) server and how to use it.
With this server, you can ask your IDE or AI assistant to create projects, deploy templates, create/select environments, or pull environment variables.
> 🚨 The Railway MCP Server is **highly experimental**. Expect bugs and missing features. By design, destructive actions (e.g., deleting services or environments) are excluded, but you should still carefully review any tool executions before running them.
The Railway MCP Server is open-source and available on GitHub.
## Understanding MCP and Railway MCP Server
The **Model Context Protocol (MCP)** defines a standard for how AI applications (hosts) can interact with external tools and data sources through a client-server architecture.
* **Hosts**: Applications such as Cursor, VS Code, Claude Desktop, or Windsurf that connect to MCP servers.
* **Clients**: The layer within hosts that maintains one-to-one connections with individual MCP servers.
* **Servers**: Standalone programs (like the Railway MCP Server) that expose tools and workflows for managing external systems.
The **Railway MCP Server** acts as the server in this architecture, translating natural language requests into CLI workflows powered by the Railway CLI.
## Prerequisites
To get started with the MCP server, you need to have the Railway CLI installed and authenticated.
## Installation
### Cursor
You can one-click install the MCP server in Cursor by clicking the "Add to Cursor" button below:
Alternatively, you can add the following configuration to your .cursor/mcp.json file manually:
### VS Code
Add the following configuration to your .vscode/mcp.json file:
### Claude Code
To install the MCP server in Claude Code, you can use the following command:
## Example Usage
* **Create and deploy a new app**
* **Deploy from a template**
* **Pull environment variables**
* **Create a new environment**
## Available MCP Tools
The Railway MCP Server provides a curated set of tools. Your AI assistant will automatically call these tools based on the context of your request.
* **Status**
* check-railway-status — Verify CLI installation and authentication
* **Project Management**
* list-projects — List all projects
* create-project-and-link — Create a project and link it to the current directory
* **Service Management**
* list-services — List project services
* link-service — Link a service to the current directory
* deploy — Deploy a service
* deploy-template — Deploy from the Railway Template Library
* **Environment Management**
* create-environment — Create a new environment
* link-environment — Link environment to current directory
* **Configuration & Variables**
* list-variables — List environment variables
* set-variables — Set environment variables
* generate-domain — Generate a Railway domain
* **Monitoring & Logs**
* get-logs — Retrieve service logs
## Security Considerations
Under the hood, the Railway MCP Server runs the Railway CLI commands. While destructive operations are intentionally excluded and not exposed as MCP tools, you should still:
* **Review actions** requested by the LLM before running them.
* **Restrict access** to ensure only trusted users can invoke the MCP server.
* **Avoid production risks** by limiting usage to local development and non-critical environments.
## Feature requests
The Railway MCP Server is a work in progress. We are actively working on adding more tools and features. If you have a feature request, leave your feedback on this Central Station post.
## Code Examples
{
"mcpServers": {
"Railway": {
"command": "npx",
"args": ["-y", "@railway/mcp-server"]
}
}
}
{
"servers": {
"Railway": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@railway/mcp-server"]
}
}
}
claude mcp add Railway npx @railway/mcp-server
Create a Next.js app in this directory and deploy it to Railway.
Also assign it a domain.
Deploy a Postgres database
Deploy a single node ClickHouse database
Pull environment variables for my project and save them to a .env file
Create a development environment called `development`
cloned from production and set it as linked
# Public API
Source: https://docs.railway.com/reference/public-api
Learn about the Railway GraphQL Public API.
## Endpoint
The public API is accessible at the following endpoint:
## Authentication
To use the API, you will need an API token. There are three types of tokens you can create.
#### Team Token and Personal Token
You can create an API token by visiting the tokens page in your account settings.
- **Team tokens** are tied to a team and will have access to all the team's resources. This token cannot be used to access your personal resources on Railway so feel free to share it with your teammates.
- **Non-team tokens** will be tied to your Railway account and will have access to all your resources. Do not share this token with anyone else.
#### Project Token
You can create a project token by visiting the tokens page in your project settings.
Project tokens are scoped to a specific environment within a project and can only be used to authenticate requests to that environment.
## Schema
The Railway API supports introspection meaning you can use popular tools like Postman or Insomnia to query the schema. Simply set up your connection with the endpoint and Authorization token, and fetch the schema.
### API Collection File
We provide a collection file which can be imported into your preferred API client. Once imported, you should only need to add your API token to get connected and start executing queries in the collection. Click here to download it.
### GraphiQL Playground
Use our GraphiQL playground to view the schema and test your queries.
Make sure to set an Authorization header with an auth token. Click the "Headers" tab at the bottom of the GraphiQL page and enter this json, using your own token:
## Rate Limits
In order to protect the Railway API from spam and misusage, we have established some basic rate limits. The current limits to the API are:
- Requests per hour: **100** RPH for Free customers, **1000** RPH for Hobby customers, **10000** RPH for Pro customers; custom for Enterprise.
- Requests per second: **10** RPS for Hobby customers; **50** RPS for Pro customers; custom for Enterprise.
To help you keep track of your usage, Railway sends a few headers with the response on each request.
| Header | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| X-RateLimit-Limit | The maximum number of API requests allowed per day. |
| X-RateLimit-Remaining | The number of API requests your token can make in the current window. |
| X-RateLimit-Reset | The time at which the current window ends and your remaining requests reset. |
| Retry-After | The amount of time after which you can make another request. This header is only sent once you've used up all your requests in the current window. |
## Support
For more information on how to use the Public API and for examples of queries, view the Public API guide.
If you run into problems using the API or have any suggestions, feel free to join our Discord server where you can interact with the engineers working on the API directly.
## Code Examples
https://backboard.railway.com/graphql/v2
curl --request POST \
--url https://backboard.railway.com/graphql/v2 \
--header 'Authorization: Bearer ' \
--header 'Content-Type: application/json' \
--data '{"query":"query { me { name email } }"}'
curl --request POST \
--url https://backboard.railway.com/graphql/v2 \
--header 'Project-Access-Token: ' \
--header 'Content-Type: application/json' \
--data '{"query":"query { projectToken { projectId environmentId } }"}'
{ "Authorization": "Bearer " }
# Templates
Source: https://docs.railway.com/reference/templates
Learn how Railway’s Kickback program rewards template publishers for their contributions.
As a user in Railway, you can create and publish templates for others to use, or you can deploy templates from our template marketplace.
For information on how to create, publish, and deploy templates, visit our Templates guides.
## Kickback program
If you publish a template, and it is deployed into other users' projects, you are immediately eligible for a 50% kickback of the usage cost incurred, in the form of Railway credits.
If a user deploys your template, and the usage of the services cost the user $100, you would receive $50 in Railway credits or $50 in cash (USD).
Read more about the kickback program here.
### Kickback Eligibility Requirements
- Your template must be published to the marketplace to be eligible for kickback.
- For Hobby users with a $5 discount, only usage in excess of the discount is counted in the kickback.
- All service types and resource usage of those services (compute, volume, egress, etc) _do count_ towards the kickback.
- Platform fees are not included in the kickback, but usage fees of the platform are included. Examples of platform fees are:
- Cost of Subscription Plan ($5 for Hobby, $20 for Pro)
- Additional Team Seats
As an example, if a user pays $20 in platform fees, then incurs $200 of usage from your template, you are eligible for a $100 kickback (50% of $200).
- The minimum kickback our program supports is $0.01, meaning usage of your template must incur at least $0.04 in usage after discounts and/or platform fees.
## Earnings and Withdrawals
By default, your template kickbacks are automatically converted into Railway Credits. But we also offer cash withdrawals. Visit the /earnings tab inside your account settings for more details. There you can add your details and request a withdrawal.
Cash Withdrawals are **not** supported in countries like **Brazil, China, and Russia**. A full list of supported countries is available on the earnings page.
### FAQ
#### How do I start earning cash?
- Simply flip the switch on the Earnings page marked Direct Deposit to Railway Credits. This will stop auto-depositing your earnings into our Credits system. You will then begin accruing cash in your Available Balance.
#### How do I request a withdrawal?
- Follow the instructions inside the Earnings tab. We use Stripe Connect to handle withdrawals. After completing the onboarding process, you will be able to request a withdrawal.
#### Why is my country not supported?
- Due to local regulations and compliance requirements, certain regions are not eligible for cash withdrawals. You can choose from the 130+ countries that are supported in the onboarding process.
#### Can I make manual withdrawals to credits too?
- Yes! Choose to Credits in the dropdown and then make your withdrawal request.
#### I have earned a lot of kickbacks from a template, but this page says my available balance is $0. Why?
- The current kickback method is to automatically apply your kickbacks as Railway Credits. You can opt out of this if you wish to start accruing cash.
#### Can I still use the older, automatic-credits setting?
- Yes. This behavior is enabled by default. You can opt out of it, and back in to it, at any time. Simply use the switch on the Earnings page marked Direct Deposit to Railway Credits.
#### What is the minimum and maximum withdrawal amount?
- For now, withdrawals may be made in $100 - $10,000 increments.
#### What is the timeframe from withdrawal request to payout?
- Withdrawals are usually processed instantly. Once processed, the funds will usually take up to 10 business days to reach your account. Depending on your region and bank, this may take longer.
## Updatable Templates
When you deploy any services from a template based on a GitHub repo, every time you visit the project in Railway, we will check to see if the project it is based on has been updated by its creator.
If it has received an upstream update, we will create a branch on the GitHub repo that was created when deploying the template, allowing for you to test it out within a PR deploy.
If you are happy with the changes, you can merge the pull request, and we will automatically deploy it to your production environment.
If you're curious, you can read more about how we built updatable templates in this blog post.
Note that this feature only works for services based on GitHub repositories. At this time, we do not have a mechanism to check for updates to Docker images from which services may be sourced.
# Plans
Source: https://docs.railway.com/reference/pricing/plans
Learn about Railway's plans and pricing.
## Plans
Railway offers four plans in addition to a Trial:
| | |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Free** | For running small apps with $1 of free credit per month |
| **Hobby** | For indie hackers and developers to build and deploy personal projects |
| **Pro** | For professional developers and their teams shipping to production |
| **Enterprise** | For teams building and deploying production applications with the need for enterprise features related to compliance, SLAs, and account management |
### Subscription Pricing
Each Railway account needs an active subscription. The base subscription fee allows you to use the Railway platform and features included in the tier of your subscription. The subscription fee goes towards your usage-costs on the platform.
| Plan | Price |
| -------------- | ----------- |
| **Free** | $0 / month |
| **Hobby** | $5 / month |
| **Pro** | $20 / month |
| **Enterprise** | Custom |
Read more about our plans at railway.com/pricing.
Curious about potential savings? Upload your current invoice and see how much you can save by running your workloads on Railway.
### Default Plan Resources
Depending on the plan you are on, you are allowed to use up these resources per service.
| Plan | **RAM** | **CPU** | **Ephemeral Storage** | **Volume Storage** | **Image Size** |
| -------------- | --------- | ----------- | --------------------- | ------------------ | -------------- |
| **Trial** | **1 GB** | **2 vCPU** | **1 GB** | **0.5 GB** | **4 GB** |
| **Free** | **0.5 GB**| **1 vCPU** | **1 GB** | **0.5 GB** | **4 GB** |
| **Hobby** | **8 GB** | **8 vCPU** | **100 GB** | **5 GB** | **100 GB** |
| **Pro** | **32 GB** | **32 vCPU** | **100 GB** | **50 GB \*** | **Unlimited** |
| **Enterprise** | **48 GB** | **64 vCPU** | **100 GB** | **2 TB \*** | **Unlimited** |
Note that these are initial values and users on the Pro and Enterprise plans can request limit increases.
\* For Volumes, Pro users and above can self-serve to increase their volume up to 250 GB. Check out this guide for information.
### Resource Usage Pricing
On top of the base subscription fee above, Railway charges for the resources that you consume.
You are only charged for the resources you actually use, which helps prevent runaway cloud costs and provides assurances that you're always getting the best deal possible on your cloud spend.
| Resource | Resource Price |
| ---------------------------------------- | ----------------------------------------------------- |
| **RAM** | $10 / GB / month ($0.000231 / GB / minute) |
| **CPU** | $20 / vCPU / month ($0.000463 / vCPU / minute) |
| **Network Egress** | $0.05 / GB ($0.000000047683716 / KB) |
| **Volume Storage** | $0.15 / GB / month ($0.000003472222222 / GB / minute) |
To learn more about controlling your resource usage costs, read our FAQ on How do I prevent spending more than I want to?
## Included Usage
The Hobby plan includes $5 of resource usage per month.
If your total resource usage at the end of your billing period is $5 or less, you will not be charged for resource usage. If your total resource usage exceeds $5 in any given billing period, you will be charged the delta.
Included resource usage is reset at the end of every billing cycle and does not accumulate over time.
**Examples**:
- If your resource usage is $3, your total bill for the cycle will be $5. You are only charged the subscription fee because your resource usage is below $5 and therefore included in your subscription
- If your resource usage is $7, your total bill for the cycle will be $7 ($5 subscription fee + $2 of usage), because your resource usage exceeds the included resource usage
Similarly, the Pro plan includes $20 of resource usage per month and the same examples and billing logic apply. If your usage stays within $20, you'll only pay the subscription fee. If it exceeds $20, you'll be charged the difference on top of the subscription.
### Additional Services
Railway offers Business Class Support as an add-on service to the Pro plan. Business Class Support is included with Enterprise. Contact us to get started.
## Image Retention Policy
Railway retains images for a period of time after a deployment is removed. This is to allow for rollback to a previous deployment.
| Plan | **Policy** |
| ---------------- | ------------- |
| **Free / Trial** | **24 hours** |
| **Hobby** | **72 hours** |
| **Pro** | **120 hours** |
| **Enterprise** | **360 hours** |
When a deployment is removed, the image will be retained for the duration of the policy.
Rolling back a removed deployment within the retention policy will restore the previous image, settings, and all variables with a new deployment; no redeployment is required.
A removed deployment that is outside of the retention policy will not have the option to rollback; instead, you will need to use the redeploy feature. This will rebuild the image from the original source code with the deployment's original variables.
## Committed Spend Tiers
Railway offers committed spend tiers for customers with consistent usage needs. Instead of negotiated contract pricing, customers can commit to a specific monthly spend level to unlock additional features and services.
For example, customers who commit to a $10,000/month spend rate can access dedicated hosts, with all pricing going towards their usage. This approach provides more flexibility and transparency compared to traditional contract pricing.
| Feature | Commitment Spend | Description |
| -------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| **90-day log history** | $200/month | Extended log retention for better historical analysis and auditing. |
| **48 GB RAM / 64 vCPU** | $500/month | Access to increased computing resources at a committed monthly spend level. |
| **HIPAA BAAs** | $1,000/month | HIPAA Business Associate Agreements for compliant health data handling. Requires a year commitment paid monthly. |
| **Slack Connect channels** | $2,000/month | Dedicated Slack Connect channels for enhanced communication and support with the Railway team. |
| **SLOs** | $2,000/month | Service Level Objectives to ensure and track application performance. |
| **Dedicated Hosts** | $10,000/month | Custom dedicated infrastructure for enhanced performance and control. |
To learn more about committed spend tiers, please contact our team.
### One-time Grant of Credits on the Free Trial
Users who create a new Trial account receive a free one-time grant of $5. Railway will expend any free credit before consuming any purchased credits. Trial plan users are unable to purchase credits without upgrading to the Hobby plan.
Learn more about Railway's Free Trial here.
## Partial Month Charges
In some cases, your billing method may be charged for the partial amount of your bill earlier in the billing cycle.
This ensures that your account remains in good standing, and helps us mitigate risk and fraud.
## FAQs
### Which plan is right for me?
- **Hobby** is for indie hackers and developers to build and deploy personal projects
- **Pro** is for professional developers and their teams shipping to production
- **Enterprise** is for dev teams building and deploying production applications with the need for enterprise features related to compliance, SLAs, and account management
### Can I upgrade or downgrade at any time?
You can upgrade any time, and when you do, you will get to the features of your new plan, as well as access to more powerful resources, immediately. When you downgrade, the changes will take effect at the beginning of your next billing cycle.
### What is the difference between subscription and resource usage?
There are two main components to your bill:
| Component | Description |
| ------------------ | ----------------------------------------------------------------------- |
| **Subscription** | Cost of the plan you're on |
| **Resource Usage** | Cost of the resources you've consumed: [cost per unit] x [used units] |
Subscription is a flat fee you pay monthly for the tier you're subscribed to, and Resource Usage varies according to your resource consumption for the month.
### Can I add collaborators to my project?
Railway's Pro and Enterprise plans are designed for collaboration. These plans allow you to add members to your team and manage their permissions.
Read more about adding members to your Pro or Enterprise team here.
### How long does Railway keep my volume data if I am no longer on a paid plan?
Railway will delete your data from the platform as per the timeline below after sufficient warning.
| Plan | Days |
| ---------------------- | -------------------------- |
| **Free or Trial plan** | 30 days after expiry |
| **Hobby plan** | 60 days after cancellation |
| **Pro plan** | 90 days after cancellation |
### Is the Hobby Plan free?
No. The Hobby Plan is $5 a month, and it includes a resource usage credit of $5. Even if you do not use the $5 in usage (CPU, Memory, egress), you always pay the $5 subscription fee.
### Can I get the Hobby plan subscription fee waived?
Railway waives the monthly Hobby plan subscription fee for a small set of active builders on the platform.
Eligibility is automatically assessed based on several factors, including your usage on the platform, your GitHub account, and more. If you qualify, you will be notified in the Dashboard or when you upgrade to the Hobby plan. If you do not qualify, you will not be eligible for the waiver.
This is a fully automated process, and Railway does not respond to requests for waiver.
### I prefer to prepay. Is that possible?
Not anymore as of March 30th, Railway requires the use of a post-paid card.
### What happens if I use credits as a payment method and my account runs out of credits?
If you are using credits as a payment method and your credit balance reaches zero, your subscription will be cancelled. You will no longer be able to deploy to Railway and we will stop all of your workloads. To resolve this, you will need to sign up for a new subscription after topping up sufficient credits.
### Why was I charged for a partial month of usage?
Railway has an automated system in place which can result in a partial amount of your bill being charged to your payment method, earlier in the billing cycle.
This is intended to ensure that your account remains in good standing, and helps us to mitigate risk and fraud.
# Free Trial
Source: https://docs.railway.com/reference/pricing/free-trial
Learn about Railway's free trial plan.
After 30 days passes or $5 is spent, the free trial reverts to the Free plan, which provides $1 of free credit per month. The credit does not roll over month to month.
## Full vs Limited Trial
Your trial experience depends on whether Railway can verify your account.
| Trial Type | Deploy Code | Deploy Databases |
| ----------------- | ----------- | ---------------- |
| **Full Trial** | ✅ | ✅ |
| **Limited Trial** | ❌ | ✅ |
When you sign up for a free Trial, you can connect your GitHub account to initiate verification. Your verification status depends on a number of factors, including the age and activity of your GitHub account.
If your account is not verified — either because you have not initiated the verification process or your account does not meet our criteria for verification — your trial experience will be limited to deploying databases.
Verification is a necessary measure to prevent abuse of the free Trial, limiting users from creating multiple accounts and reducing the risk of trial users deploying or hosting content that violates Railway's Terms of Service.
This is a fully automated process, and Railway does not respond to requests for verification. If your account is not verified, you can upgrade to the Hobby plan to unlock the full Railway experience.
## FAQs
### How do I get started with the free Trial?
If you do not already have a Railway account, you can sign up for a free Trial by clicking "Login" at railway.com.
### How does the Trial work?
When you sign up for the free Trial, you will receive a one-time grant of $5 in credits that you can use to try out Railway. The credits will be applied towards any usage on the platform and expire in 30 days. If you upgrade to a plan while you still have a credit balance from the trial, the remaining balance will carry over to your new plan.
### What resources can I access during the Trial?
During the trial, you can access the same features as on the Hobby plan, however you will be limited to 1 GB of RAM and shared (rather than dedicated) vCPU cores. Additionally, your projects will be limited to 5 services per project.
As a trial user, you can always spin-up databases. However, to deploy code, you must be on the Full Trial.
### What's the difference between the Limited Trial and the Full Trial?
If you connect your GitHub account, and we are able to verify it against a set of parameters, you will be on the Full Trial where you can deploy both code and databases.
If you do not connect a GitHub account, or we are not able to verify your account, you will be on the Limited Trial, where you can only deploy databases.
While you're on the Limited Trial, you can initiate verification at any time by visiting railway.com/verify in order to access the Full Trial experience.
### How far will the $5 one-time Trial grant last?
The longevity of your one-time trial grant depends on how many resources you consume within the 30 day period you sign-up for the platform. The more resources you deploy, the greater the consumption.
### Data Retention
Railway deletes stateful volumes created by Trial accounts 30 days after the expiration of your credits. To retain your data, upgrade your account after the Trial period.
# FAQs
Source: https://docs.railway.com/reference/pricing/faqs
General common Questions & Answers related to Railway's pricing.
### Can I try Railway without a credit-card?
Yes. As a new Railway user, you can sign up for a Free Trial. You will receive a one-time grant of $5 to use on resources.
### What payment methods are accepted?
Railway only accepts credit cards for plan subscriptions. We also support custom invoicing for customers on the Enterprise plan.
### What will it cost to run my app?
With Railway, you are billed for the subscription fee of the plan you're subscribed to, and the resource usage of your workloads.
To understand how much your app will cost to run on Railway, we recommend you to:
1. Deploy your project with the Trial or Hobby plan
2. Allow it to run for one week
3. Check your Estimated Usage in the Usage Section of your Workspace settings
Keeping it running for one week allows us to rack up sufficient metrics to provide you with an estimate of your usage for the current billing cycle. You can then use this information to extrapolate the cost you should expect.
We are unable to give exact quotes or estimates for how much it will cost to run your app because it is highly dependent on what you're deploying.
For a rough approximation of the cost for running your app, try our pricing calculator.
If you are supporting a commercial application, we highly recommend you to upgrade to the Pro plan for higher resource limits and access to priority support.
### How do I prevent spending more than I want to?
Check out our guide on optimizing usage.
### Why is my resource usage higher than expected?
You can check your resource usage in the Usage Section of your Workspace settings. This includes a breakdown of your resource usage by project, along with the resource it's consuming (CPU, Memory, Network, etc.)
Common reasons for high resource usage include:
- Memory leaks in your application, causing it to consume more memory than necessary
- Higher traffic than usual, causing your app to consume more CPU and/or Network
- Certain templates or apps may be inherently more resource-intensive than others
- If you notice high egress cost in your bill, ensure that you are connecting to your Railway databases over Private Networking
- If you have PR deploys enabled in your project, Railway will deploy a mirror copy of your workload(s) based on the environment it forks from (production by default). You are billed for those workload(s) running in the ephemeral environment
Unfortunately, we are unable to assist with figuring out why your bill is higher than normal, as it is entirely dependent on what you have deployed. Resource usage is billed in a manner akin to how a utility company operates: they can tell you the amount of electricity you've consumed, but they can't explain the reasons for your high usage. Similarly, we can only provide information on the quantity of resources you consume, not the reasons behind it.
### Why am I charged for more than $5 on the Hobby plan?
Railway's pricing has two components: a monthly subscription fee, and resource usage costs. While the Hobby plan includes $5 of resource usage per month, you are charged for any usage that exceeds this amount.
Learn more here.
### Why is there an "Applied balance" on my invoice?
When the amount due on your invoice is less than $0.50, and you do not have a credit balance, Railway marks the invoice as paid and registers the amount to your credit balance as a debit to be charged on a future invoice.
### How do I view or upgrade my current plan?
Your current plan is listed in the Account Selector in the top left corner of your Dashboard. You can also view your active plan and upgrade options from the Plans page.
### How do I cancel my subscription?
To cancel your active subscription, go to the "Active Plan" section of your Billing page and click Cancel Plan.
When you cancel your subscription, Railway will stop all deployments in your workspace to prevent further charges. Your plan will remain active until the end of your billing cycle.
### How do I add or update billing information?
To add or update your Billing information, go to the Billing page. In the "Billing Info" section, you can add or update the following information:
- Payment Method
- Billing Email
- Billing Address
- Tax ID / VAT number
When Billing Information is added or updated, it will be reflected on all future invoices from Railway.
### How is Salex Tax/VAT handled?
Railway may collect applicable sales tax and VAT on your account based on your billing location and local tax requirements, where and when applicable. When assessed and collected, Sales Tax/VAT is explicitly outlined on your invoice.
To ensure accurate tax assessment, Workspace Admins must verify that their billing information, including Billing Address, Organization Name, and Tax ID (when applicable), is accurate. Organization Name and Tax ID are not required when using Railway for personal use.
To view and manage your subscription, visit the billing section of your workspace.
### How do I remove my saved payment method from my account?
If your subscription is canceled and you have no pending invoices, you can remove your saved payment method by doing the following:
1. Go to the billing page for your workspace
2. Click "Delete" in the payment method section
### What happens if the payment fails for my subscription?
If your subscription payment fails, we retry the payment method on file over several days. We also inform you of the payment failure, in case your payment method needs to be updated.
If payment continues to fail, we flag your services to be stopped and send you a warning.
If we do not receive payment, your services are stopped until all open invoices have been paid.
### My services were stopped, what do I do?
Your services may be stopped by Railway for the following reasons, along with their solutions -
- **Usage limits reached:** You've hit your usage limits. Increase your usage limit or wait until the next billing period.
- **Trial credits exhausted:** You've run out of trial credits. Consider upgrading to a paid plan to continue using the service.
- **Failed payment:** Your payment method has failed. Update your payment method and pay your outstanding invoice.
- **Unpaid invoice:** You have an outstanding invoice. Pay your outstanding invoice.
In all cases, you can redeploy your services once the underlying issue is resolved, this can be done from the Removed deployment's 3-dot menu.
**Note:** Although Railway will remove your deployment for any of the above reasons, Railway will not remove the volume attached to the service.
### I am a freelancer or represent an agency. How do I manage my billing relationships with my clients?
Create a Pro plan on Railway and add the client to the workspace. If you run into issues when it's time to hand over your workload to your client, you can reach out to us over our Central Station.
### Why did I receive another invoice after cancelling my subscription?
You may receive an invoice containing charges for Resource Usage after you cancel your subscription. These are resource usages you have consumed in that billing cycle that we reserve the right to charge you for.
### How do I request a refund?
Please refer to Pricing -> Refunds.
### Requesting an invoice re-issuance
If you encounter "This invoice can no longer be paid on Stripe" error or need
your Tax ID added to a previous invoice, follow the steps below to get an
invoice reissued.
1. Go to your workspace's billing page at https://railway.com/workspace/billing. Ensure you select the correct workspace using the Workspace Switcher in the top left corner.
2. Scroll to **Billing History**. For the invoice you want to reissue, click on the Gear icon next to it and select **Re-issue**.
- Use pg_dump to export your database
- pg_dump -Fc --no-acl --no-owner -h localhost -p 5432 -U -d -f flyio_db_backup.dump
- Use pg_restore to connect to your Railway database and restore the data from the dump.
- pg_restore -U -h -p -W -F t -d
For detailed instructions, check out this comprehensive tutorial on migrating PostgreSQL data between services.
Once the migration is complete, update the DATABASE_URL environment variable in your Railway app to point to the new PostgreSQL database and redeploy.
### 4. Replicas & Multi-region deployments
In this Fly.io app, the setting **min_machines_running=2** ensures that at least **two instances** of the service remain active. On Railway import, we automatically translate this configuration to ensure that two **service instances** are running without any extra setup.
!Replicas
If your app needs to use multi-region deployments, you can leverage Railway’s multi-region replicas.
Enable this in the **Settings** section of your Railway service to keep your app close to users worldwide.
**Note:** Multi-region replicas is currently available to Pro users.
And that’s it. That’s all you need to migrate your app from Flyio to Railway.
# Migrate from Vercel
Source: https://docs.railway.com/migration/migrate-from-vercel
Learn how to migrate your Next.js app from Vercel to Railway with this step-by-step guide. Fast, seamless, and hassle-free.
With features like instant rollbacks, integrated observability, and seamless environment management, Railway empowers developers to focus on building great applications rather than managing infrastructure.
Railway offers -
- **Next.js Optimization**: Built-in support for all Next.js features including ISR, SSR, and API routes
- **Zero Config Deployments**: Automatic framework detection and build optimization
- **Enhanced Development Flow**: Local development with production parity
- **Collaborative Features**: Team management, deployment protection, and role-based access
- **Priority Support**: Dedicated support for Railway users
## Migration Steps
Let's walk through migrating a Next.js application to Railway. For this guide, we'll use a sample e-commerce app that showcases common Next.js features and configurations.
### Deploying Your Application
To get started deploying our NextJS app, we will first make a new project.
- Open up the dashboard → Click **New Project**.
- Choose the **GitHub repo** option.
Apply Now
## Conductor Benefits
Being a Conductor comes with several exciting perks and rewards to recognize your valuable contributions to the community.
As part of the program, conductors will receive -
- 100% off discount for the Hobby plan's subscription and resource costs.
- Cash payouts for solving complex issues for users.
- The opportunity to earn payouts for OSS contributions (CLI, Nixpacks, Docs, etc).
- First access to template bounties.
- Letters of recommendation for educational institutions and employer references.
- Moderation status on Discord and the Central Station.
- Access to a team workspace shared with other Conductors.
- A direct line to the team via the private Conductor only channel.
- Your choice of Railway Swag.
And to top it all off, each quarter we reward our most outstanding conductor with a pizza party! 🎉
## Conductor Participation
We believe in fostering an active and supportive Conductor program that enables everyone to make meaningful contributions. To help keep our community vibrant, we conduct friendly quarterly check-ins with all Conductors.
As a Conductor, you'll contribute regularly in these key areas -
- Community Engagement
- Being an active, welcoming presence in community channels.
- Building connections with fellow community members.
- Joining community conversations and sharing experiences.
- Looking out for the community by making sure discussions stay positive and helpful.
- Support Activities
- Helping others in Discord and the Central Station.
- Showing consistent engagement by regularly contributing to meaningful solutions across all Railway platforms.
- Open Source Contributions
- Contributing through either small improvements or substantial feature additions.
- New features should address community-requested needs with demonstrated user demand.
- Bug fixes should focus on issues affecting multiple users.
We understand that maintaining consistent participation across these areas requires dedication and time. As part of our commitment to supporting Conductors, we have quarterly check-ins to discuss your experience and ensure you have everything needed to succeed.
While we aim for regular engagement, we recognize that life circumstances and priorities can change. If participation becomes limited, we may need to transition members out of the program during our bi-annual review. However, our door always remains open – former Conductors are welcome to rejoin the program when their schedule better accommodates regular participation!
# Affiliate Program
Source: https://docs.railway.com/community/affiliate-program
Show Railway to your network, earn 15% cash commission on referral revenue.
Anyone that signs up from your link will receive $20 in Railway credits, equivalent to a free month on the Pro tier.
Once the signup becomes a Railway customer, you will receive 15% commission on the first 12 months of invoices from the new customer moving forward.
## How Do I Become an Affiliate?
|Node||
||Deno||
||Bun||
||Gin||
||Flask||
## Kickback Program
If your published template is deployed into other users' projects, you are immediately eligible for a 50% kickback, in the form of Railway credits or cash. Refer to the template reference page for more information.
## Template Verification
Templates are verified when the creator and maintainer of the technology becomes a partner and reviews the template.
If you are or have a relationship with the creator, please reach out to us by submitting the form on our partners page.
## Code Examples
[](https://railway.com/new/template/ZweBXA?utm_medium=integration&utm_source=button&utm_campaign=generic)
# Deploy
Source: https://docs.railway.com/guides/deploy
Learn how to deploy Railway templates.
connected to infrastructure.
You can find featured templates on our template marketplace.
## Template Deployment Flow
To deploy a template -
- Find a template from the marketplace and click Deploy Now
- If necessary, configure the required variables, and click Deploy
- Upon deploy, you will be taken to your new project containing the template service(s)
- Services are deployed directly from the defined source in the template configuration
- After deploy, you can find the service source by going to the service's settings tab
- Should you need to make changes to the source code, you will need to eject from the template repo to create your own copy. See next section for more detail.
_Note: You can also deploy templates into existing projects, by clicking + New from your project canvas and selecting Template._
## Eject from Template Repository
A railway.toml file
A railway.json file
We also have a live demo of the project you will build in this tutorial here, and you can access the code repository here in Github. You can find some example apps, including the one we will build in this tutorial, in the exampleApps folder.
**Let's get started!**
## 1. Deploy the Backend Services
First, we will deploy the backend services:
- Jaeger - an open-source, distributed tracing system that will receive telemetry data from the collector
- Zipkin - also an open-source, distributed tracing system that will receive telemetry data from the collector
- Prometheus - an open-souce, systems monitoring and alerting toolkit that will receive telemetry data from the collector
_Jaeger and Zipkin offer similar functionality, and it is not necessary to run both. The intent is to give you different examples of backend services._
Each of the following steps should be completed in the same Railway project.
### Add Jaeger Service
- Add a New service by clicking + New
- Select Docker Image as the Source
- Add jaegertracing/all-in-one as the image name and hit Enter
- Add the following variable to the service
_This is the port that serves the UI. Setting this variable allows you to access the Jaeger UI from your browser_
- In the Settings tab, rename the service Jaeger
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
You should be able to access the Jaeger UI by clicking on the service domain.
### Add Zipkin Service
- Add a New service by clicking + New
- Select Docker Image as the Source
- Add openzipkin/zipkin as the image name and hit Enter
- Add the following variable to the service
_This is the port that serves the UI. Setting this variable allows you to access the Zipkin UI from your browser_
- In the Settings tab, rename the service Zipkin
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
You should be able to access the Zipkin UI by clicking on the service domain.
### Add Prometheus Service
- Add a New service by clicking + New
- Select Template as the Source
- Type Prometheus and select the Prometheus template (be sure to select this one)
- Click Deploy to apply and deploy the service
_The template deploys with the proper UI port already configured to enable accessing the Prometheus UI from your browser_
You should be able to access the Prometheus UI by clicking on the service domain.
## 2. Deploy the OpenTelemetry Collector
The OpenTelemetry Collector is a vendor-agnostic service that receives, processes, and exports telemetry data.
It is not strictly necessary to run a collector when implementing OpenTelemetry, but it is recommended by the OpenTelemetry community. More information on the subject can be found here.
### Fork the Open Telemetry Collector repository
- Navigate to the Open Telemetry Collector repository in GitHub
- Click Fork then Create fork
### Add the Open Telemetry Service
In the Railway project -
- Add a New service by clicking + New
- Select GitHub Repo as the Source
- Select the opentelemetry-collector-stack repository (if you renamed the repo in the previous step, yours will be named differently)
- Add the following variable to the service
_This is the port that serves the collector's debugging UI. Setting this variable allows you to access the UI from your browser_
- In the Settings tab, rename the service OpenTelemetry Collector
- Click Deploy to apply and deploy the service
- In the Settings tab, under Networking, click Generate Domain
The Collector's debugging UI is enabled by default and accessible from the browser. This is controlled by the inclusion of the zpages extension in the collector's configuration yaml. You can read more about the UI and the available routes, in the collector's source repo.
---
## Checkpoint
Congrats! You should now have a working OpenTelemetry Collector along with a backend stack to which the collector will forward data. Your project in Railway should look something like this -
Jaeger
Zipkin
Notice theSubnets
Info box under the machine name.
- Click on the machine's 3-dot menu → **Edit route settings**.
- Subdomains and wildcards cannot overlap (foo.hello.com cannot exist with *.hello.com unless owned by the same service).
- Root domains need a DNS provider with ALIAS records or CNAME flattening.
- Unicode domains should be PUNYcode encoded.
- Non-public/internal domain names are not supported. | | **Certificate Issuance** | - Railway attempts to issue a certificate for **up to 72 hours** after domain creation before failing.
- Certificates are expected to be issued within an hour. | | **TLS** | - Support for TLS 1.2 and TLS 1.3 with specific cipher sets.
- Certificates are valid for 90 days and renewed every 30 days. | | **Edge Traffic** | - Support for HTTP/1.1.
- Support for websockets over HTTP/1.1.
- Proxy Keep-Alive timeout of 60 seconds (1 minute).
- Max 32 KB Combined Header Size
- Max duration of 15 minutes for HTTP requests. | | **Request Headers** | - X-Real-IP for identifying client's remote IP.
- X-Forwarded-Proto always indicates https.
- X-Forwarded-Host for identifying the original host header.
- X-Railway-Edge for identifying the edge region that handled the request.
- X-Request-Start for identifying the time the request was received (Unix milliseconds timestamp).
- X-Railway-Request-Id for correlating requests against network logs. | | **Requests** | - Inbound traffic must be TLS-encrypted
- HTTP GET requests to port 80 are redirected to HTTPS.
- HTTP POST requests to port 80 are redirected to HTTPS as GET requests.
- SNI is required for correct certificate matching. | ## Domain Rate Limits _This information is subject to change at any time._ To ensure the integrity and performance of our network, we enforce the following limits for all services. | Category | Limit | Description | | --------------------------- | ----------------------------- | --------------------------------------------------------- | | **Maximum Connections** | 10,000 concurrent connections | The number of concurrent connections. | | **HTTP Requests/Sec** | 3,000 RPS | The number of HTTP requests to a given domain per second. | | **Requests Per Connection** | 10,000 requests | The number of requests each connection can make. | If your application requires higher limits, please don't hesitate to reach out to us at team@railway.com. ## Custom Domain Count Limits The Hobby plan is limited to 2 custom domains per service. The Pro Plan is limited to 20 domains per service by default but can be increased for Pro users on request, by reaching out to us at team@railway.com or via private thread. ## FAQ