## What is the purpose of a CDN?

> 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?](https://aws.amazon.com/what-is/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](https://www.g2.com/categories/content-delivery-network-cdn)), but this tutorial covers step-by-step how to implement a CDN using [Amazon CloudFront](https://aws.amazon.com/cloudfront/).

**Objectives**

In this tutorial, you will learn how to -

- Deploy a simple [Fastify server](https://fastify.dev/) to Railway
- Create a [CloudFront distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html) in AWS and connect it to the Fastify server
- _(Optional)_ Setup SSL and DNS for a custom domain managed in [Namecheap](https://www.namecheap.com/)

**Prerequisites**

To be successful using this tutorial, you should already have -

- Latest version of the Railway [CLI installed](/cli#installing-the-cli)
- An [AWS account](https://aws.amazon.com/) with permissions to create new resources
- Latest version of the [AWS CLI](https://aws.amazon.com/cli/) installed and authenticated to your AWS account
- Latest version of the [AWS CDK](https://aws.amazon.com/cdk/) installed
- _(Optional)_ A Namecheap account to connect a custom domain

**Let's get started!**

## 1. Create and deploy a Fastify server

First, create and deploy a simple Fastify server using the [Railway CLI](/cli#installing-the-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
  ```plaintext
  npm init -y
  npm i fastify @fastify/etag
  ```
- Add the following code to the "server.js" file

  ```javascript
  const Fastify = require("fastify");
  const fastifyEtag = require("@fastify/etag");

  const fastify = Fastify();
  fastify.register(fastifyEtag);

  fastify.get("/dynamic", async (request, reply) => {
    console.log("Received request on dynamic route");

    const staticContent = {
      message: "This is some dynamic content",
      timestamp: new Date().toISOString(),
    };

    reply.type("application/json");
    reply.headers({
      "cache-control": "must-revalidate, max-age=60",
    });

    reply.send(staticContent);
  });

  fastify.get("/static", async (request, reply) => {
    console.log("Received request on static route");

    const staticContent = {
      message: "This is some static content",
    };

    reply.type("application/json");
    reply.headers({
      "cache-control": "must-revalidate, max-age=60",
    });

    reply.send(staticContent);
  });

  fastify.get("/staticEtag", async (request, reply) => {
    console.log("Received request on staticEtag route");

    const staticContent = {
      message: "This will serve a static etag",
    };

    reply.type("application/json");

    reply.headers({
      "cache-control": "must-revalidate, max-age=60",
    });

    reply.header("etag", '"foobar"');
    reply.send(staticContent);
  });

  const start = async () => {
    try {
      await fastify.listen({
        port: Number(process.env.PORT) || 3000,
        host: "0.0.0.0",
      });
      console.log(
        `Server is running at PORT:${Number(process.env.PORT) || 3000}`,
      );
    } catch (err) {
      fastify.log.error(err);
      process.exit(1);
    }
  };

  start();
  ```

- Run the following command to initialize a new project in Railway
  ```plaintext
  railway init
  ```
- Follow the prompts and name your project "fastify-cdn"
- Run the following command to deploy your Fastify server
  ```plaintext
  railway up -d
  ```
- Run the following command to generate a domain for the Fastify service
  ```plaintext
  railway domain
  ```
- Run the following command to open your Railway project in your browser
  ```plaintext
  railway open
  ```

### 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](https://www.rfc-editor.org/rfc/rfc9110.html#section-8.8.3) on a route

  _Note: The Fastify server code above implements [Fastify's eTag plugin](https://www.npmjs.com/package/@fastify/etag)._

#### 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:

<Image src="https://res.cloudinary.com/railway/image/upload/v1719001891/docs/tutorials/CDN/CleanShot_2024-06-21_at_15.28.36_2x_em6o5s.png"
alt="Screenshot of DevTools no CDN"
layout="responsive"
width={1477} height={623} quality={100} />

Since the data for the route has not been cached on a CDN, the server receives every request, generates a new timestamp, and sends it back with a 200 status code.

Once the CloudFront CDN is set up, you will see how this behavior changes.

## 2. Create a CloudFront distribution in AWS

_This step assumes you have already [configured the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) to connect to your AWS account._

Now create a CloudFront distribution using the AWS CDK.

- In your "fastify" folder, create a new folder called "cloudfront"
- Within the "cloudfront" folder, run the following command to initialize a new CDK project in TypeScript
  ```plaintext
  cdk init app --language typescript
  ```
- Run the following command to install the CDK packages for CloudFront
  ```plaintext
  npm install @aws-cdk/aws-cloudfront @aws-cdk aws-cloudfront-origins @aws-cdk/core
  ```
- Replace the contents of the "/bin/cloudfront.ts" file with the following code.

  _When you run `cdk bootstrap` in the following steps, the account and region environment variables should be added for you._

  ```javascript
  #!/usr/bin/env node
  import "source-map-support/register";
  import * as cdk from "@aws-cdk/core";
  import { CloudfrontCdkStack } from "../lib/cloudfront-stack";

  const app = new cdk.App();
  new CloudfrontCdkStack(app, "CloudfrontCdkStack", {
    env: {
      account: process.env.CDK_DEFAULT_ACCOUNT,
      region: process.env.CDK_DEFAULT_REGION,
    },
  });
  ```

- Replace the contents of the "/lib/cloudfront-stack.ts" file with the following code

  ```javascript
  import * as cdk from "@aws-cdk/core";
  import * as cloudfront from "@aws-cdk/aws-cloudfront";
  import * as origins from "@aws-cdk/aws-cloudfront-origins";

  export class CloudfrontCdkStack extends cdk.Stack {
    constructor(scope: cdk.Construct, id: string, props?: cdk.StackProps) {
      super(scope, id, props);

      // Replace with the Domain provided by Railway
      const origin = new origins.HttpOrigin("RAILWAY PROVIDED DOMAIN");

      // Custom Cache Policy
      const cachePolicy = new cloudfront.CachePolicy(
        this,
        "CustomCachePolicy",
        {
          cachePolicyName: "CustomCachePolicy",
          minTtl: cdk.Duration.seconds(0),
          maxTtl: cdk.Duration.seconds(86400),
          defaultTtl: cdk.Duration.seconds(60),
          cookieBehavior: cloudfront.CacheCookieBehavior.all(),
          queryStringBehavior: cloudfront.CacheQueryStringBehavior.all(),
          headerBehavior: cloudfront.CacheHeaderBehavior.allowList(
            "CloudFront-Viewer-Country",
            "CloudFront-Is-Mobile-Viewer",
          ),
        },
      );

      // CloudFront distribution
      const distribution = new cloudfront.Distribution(this, "Distribution", {
        defaultBehavior: {
          origin,
          cachePolicy: cachePolicy,
          viewerProtocolPolicy:
            cloudfront.ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
          allowedMethods: cloudfront.AllowedMethods.ALLOW_ALL,
        },
      });
    }
  }
  ```

  **IMPORTANT: Be sure to replace the `HttpOrigin` in the code above with the Railway-provided domain (e.g. _fastify-server.up.railway.app_)**

- Run the following command to bootstrap the environment for the CDK
  ```plaintext
  cdk bootstrap
  ```
- Run the following command to deploy the CloudFront distribution
  ```plaintext
  cdk deploy
  ```

_If you experience any problems with the AWS utilities used in this step, you can create and configure the CloudFront distribution manually using the AWS Management Console, using the same settings defined in the "cloudfront-stack.ts" file._

### Checkpoint 2

Great job! You should now have a CloudFront distribution pointed to your Fastify service in Railway. Your distribution will be assigned a domain similar to the one below:

- `https://d1a23bcdefg.cloudfront.net`

Now let's see how the behavior for the `/dynamic` route has changed when accessing the server from the CloudFront distribution domain.

<Image src="https://res.cloudinary.com/railway/image/upload/v1719001866/docs/tutorials/CDN/CleanShot_2024-06-21_at_15.24.47_2x_knqo9f.png"
alt="Screenshot of DevTools with CDN"
layout="responsive"
width={1477} height={623} quality={100} />

Notice how the first request was served an **HTTP 200** from the server with the dynamically generated data, but subsequent requests were served a **HTTP 304 Not Modified** code.

This is the CloudFront CDN in action!

If you inspect the route definition for `/dynamic`, you'll see that the headers include a `cache-control` parameter:

    ```javascript
    reply.headers({
        'cache-control': 'must-revalidate, max-age=60'
    });
    ```

This cache control definition tells CloudFront to revalidate the data at the route after 60s.

#### Cache behavior

When the initial request is made to the route, CloudFront retrieves the data from the server, then stores it. For 60s after the initial request, CloudFront will serve the cached response with **HTTP 304**, and after 60s, it will check the server for new data.

#### Faster response time

In the screenshot above, take note of the Size and Time columns.

When CloudFront serves the cached data, it takes significantly less time to resolve the route, and, probably due to less headers, the Size of the message is also smaller.

## 3. Connect a custom domain with SSL enabled

Now that the CloudFront distribution is up and running, you may want to connect a custom domain and ensure SSL is enabled.

This step will _quickly_ cover how to generate a SSL certificate in AWS and configure the custom domain in Namecheap and CloudFront.

First generate an SSL certificate -

- In AWS Management Console, navigate to your CloudFront distribution
- Under the General tab, click the `Edit` button
- Under _Custom SSL certificate_, click the _"Request certificate"_ link below the input field. This will take you to AWS Certificate Manager.
- Click the `Next` button to request a public certificate
- Enter your fully qualified domain name, e.g. `www.railway.com`
  - If you'd like the cert to include the apex domain, click `Add another name to this certificate` and enter it, e.g. `railway.com`
- Click the `Next` button to generate the certificate
- In **Namecheap**, in the Advanced DNS section for the domain, add the host record(s).
  - If you set up the certificate for both www and the apex domain, you will add two **CNAME** records
  - The CNAME name value provided by AWS, should be used as the **Host** value in Namecheap.
  - The CNAME name value provided by AWS, includes the domain name, but in Namecheap, you should add everything except the domain, e.g.
    - if your CNAME name is `_6cf3abcd1234abcd1234aabb11cc22.www.railway.com`
    - you should add `_6cf3abcd1234abcd1234aabb11cc22.www` to the **Host** value in Namecheap
- Once you add the DNS records in Namecheap, refresh the Certificate status page in AWS to confirm the Status shows **Success**

Now, add the certificate in the CloudFront distribution settings and finish setting up the custom domain -

- Return the the CloudFront distribution settings
- Under _Custom SSL certificate_, choose the certificate you just created from the drop down menu
- Under _Alternate domain name (CNAME)_, add your custom domain.
  - If you want both www and apex domain, be sure to add both
- At the bottom, click the `Save changes` button
- In **Namecheap**, in the Advanced DNS section for the domain, add the host record(s)
  - If you are setting up both www and the apex domain, you will add two **ALIAS** records
  - The record value should be your Cloudfront distribution domain, e.g. `d1a23bcdefg.cloudfront.net`
  - The **Host** value should be `@` for the apex domain and `www` for the www subdomain.

That's it! You should now be able to navigate to the three routes in the Fastify service from your custom domain.

## Conclusion

Congratulations! You have deployed a Fastify app to Railway, created a CloudFront distribution in AWS connected to the Railway service, and (optionally) connected your custom domain in Namecheap to the CloudFront distribution with SSL enabled.

#### Additional resources

This is a _very_ simple tutorial covering the most basic steps to implement CloudFront CDN in your stack. There are many, many more concepts you should explore related to CDNs and caching in general, to take full advantage of the technology and tailor it to your specific needs.

We recommend checking out these resources to start:

- [What is a CDN?](https://aws.amazon.com/what-is/cdn/)
- [What is caching?](https://www.cloudflare.com/learning/cdn/what-is-caching/)
- [CDN vs Caching](https://www.fastly.com/blog/leveraging-browser-cache-fastlys-cdn/)

Learn how to integrate Amazon CloudFront as a CDN for your Fastify app in this step-by-step guide.

Add a CDN using Amazon CloudFront

[Angular](https://angular.dev) is a JavaScript web framework that empowers developers to build fast and reliable applications. It is designed to work at any scale, keep large teams productive and is proven in some of Google's largest web apps such as [Google fonts](https://fonts.google.com) and [Google Cloud](https://console.cloud.google.com).

This guide covers how to deploy an Angular app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template)
2. [From a GitHub repository](#deploy-from-a-github-repo)
3. [Using the CLI](#deploy-from-the-cli)
4. [Using a Dockerfile](#use-a-dockerfile)

Now, let's create an Angular app!

## Create an Angular app

**Note:** If you already have an Angular app locally or on GitHub, you can skip this step and go straight to the [Deploy Angular App on Railway](#deploy-the-angular-app-to-railway).

To create a new Angular app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) and [Angular CLI](https://angular.dev/installation#install-angular-cli) installed on your machine.

Run the following command in your terminal to create a new Angular app:

```bash
ng new gratitudeapp
```

You'll be presented with some config options in the prompts for your project.

- Select `CSS`
- Select `Yes` for enabling Server-Side Rendering (SSR) and Static Site Generation (SSG)
- Select `Yes` for enabling Server Routing and App Engine APIs (Developer Preview)

### Run the Angular app locally

Next, `cd` into the directory and run the app.

```bash
npm start
```

Open your browser and go to `http://localhost:4200` to see your app.

## Modify start script

Before deploying, update the `package.json` file.

Angular builds the project into the `dist` directory. For server-side rendered apps, the server starts with the command: `node dist/gratitudeapp/server/server.mjs` as defined in the scripts section below:

```js
"scripts": {
    "ng": "ng",
    "start": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test",
    "serve:ssr:gratitudeapp": "node dist/gratitudeapp/server/server.mjs"
  },
```

- The development server starts with `npm start`.
- The production server runs with `npm run serve:ssr:gratitudeapp`.

Since Railway relies on the `build` and `start` scripts to automatically build and launch applications, update the `start` script to ensure it runs the production server correctly.

Your scripts section should look like this:

```js
...
"scripts": {
    "ng": "ng",
    "dev": "ng serve",
    "build": "ng build",
    "watch": "ng build --watch --configuration development",
    "test": "ng test",
    "start": "node dist/gratitudeapp/server/server.mjs"
  },
...
```

Now you're good to go!

## Deploy the Angular app to Railway

Railway offers multiple ways to deploy your Angular 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/A5t142)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=angular" target="_blank">variety of Angular app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Angular app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/v1741028014/CleanShot_2025-03-03_at_18.49.07_2x_ewelfy.png"
alt="screenshot of the deployed Angular service"
layout="responsive"
width={2644} height={2114} quality={100} />

### Deploy from a GitHub repo

To deploy an Angular app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `gratitudeapp` or Angular app's root directory.
2. Add the content below to the `Dockerfile`:

   ```dockerfile
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Angular apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy an Angular app to Railway with this step-by-step guide. It covers quick setup, caddy server setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy an Angular App

[Astro](https://astro.build) is the web framework for content-driven websites. It's a JavaScript framework optimized for building fast, content-driven websites. It also supports every major UI framework, allowing you to bring in your existing components and benefit from Astro's optimized client build performance.

This guide covers how to deploy an Astro app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create an Astro app!

## Create an Astro app

**Note:** If you already have an Astro app locally or on GitHub, you can skip this step and go straight to the [Deploy Astro Apps on Railway](#deploy-the-astro-app-to-railway).

To create a new Astro app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new Astro app:

```bash
npm create astro@latest
```

Follow the prompts and provide a directory name, such as `blog`, where you'd like to set up your app.

When prompted to choose how you'd like to start your project, select **Use blog template**. For TypeScript, choose **Yes**.

For the remaining options, select the defaults and press Enter. All necessary dependencies will then be installed.

A new Astro app will be provisioned for you in the `blog` directory.

### Run the Astro app locally

Enter your project directory using `cd blog`.

Start the local dev server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:4321` to see your app.

### Enable server side rendering (SSR)

Astro has several [SSR adapters](https://docs.astro.build/en/guides/server-side-rendering/). These adapters are used to run your project on the server and handle SSR requests.

Add the Node adapter to enable SSR in your blog project.

Run the command below in your terminal:

```bash
npx astro add node
```

Select **Yes** at the prompt to proceed. The Node adapter will be installed, and your Astro config file will be updated accordingly.

Open up the `astro.config.mjs` file:

```js
// @ts-check
import { defineConfig } from "astro/config";
import mdx from "@astrojs/mdx";

import sitemap from "@astrojs/sitemap";

import node from "@astrojs/node";

// https://astro.build/config
export default defineConfig({
  site: "https://example.com",
  integrations: [mdx(), sitemap()],
  output: "server",

  adapter: node({
    mode: "standalone",
  }),
});
```

In the config file, `output` is set to `server`, meaning every page in the app is server-rendered by default.

For mostly static sites, set `output` to `hybrid`. This allows you to add `export const prerender = false` to any file that needs to be server-rendered on demand.

### Modify start script and Astro config

Astro builds your project into a `dist` directory. In `standalone` mode, a server starts when the server entry point is executed, which is by default located at `./dist/server/entry.mjs`.

In this mode, the server handles file serving as well as page and API routes.

Open up the `package.json` file and modify the start script from `astro dev` to `node ./dist/server/entry.mjs`.

```js
{
    "name": "astroblog",
    "type": "module",
    "version": "0.0.1",
    "scripts": {
        "dev": "astro dev",
        "start": "node ./dist/server/entry.mjs",
        "build": "astro check && astro build",
        "preview": "astro preview",
        "astro": "astro"
    },
    "dependencies": {
        "@astrojs/check": "^0.9.4",
        "@astrojs/mdx": "^3.1.8",
        "@astrojs/node": "^8.3.4",
        "@astrojs/rss": "^4.0.9",
        "@astrojs/sitemap": "^3.2.1",
        "astro": "^4.16.6",
        "typescript": "^5.6.3"
    }
}
```

Open the `astro.config.mjs` file and configure the server to run on host `0.0.0.0` by adding the following block inside the `defineConfig` function.

```js
...
server: {
    host: '0.0.0.0'
},
```

Your app needs to listen on either `0.0.0.0` or `::` to accept traffic. If not configured properly, you'll encounter a 502 error.

## Deploy the Astro app to Railway

Railway offers multiple ways to deploy your Astro 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/Ic0JBh)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=astro" target="_blank">variety of Astro app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Vue app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729535599/astro_blog_app.png"
alt="screenshot of the deployed Astro service"
layout="responsive"
width={2556} height={2164} quality={100} />

### Deploy from a GitHub repo

To deploy an Astro app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `blog` or Astro app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Astro apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy an Astro app to Railway with this step-by-step guide. It covers quick setup, server side rendering, one-click deploys, Dockerfile and other deployment strategies.

Deploy an Astro App

[Axum](https://docs.rs/axum/latest/axum) is a web framework for Rust that focuses on ergonomics and modularity. It is designed to work with [tokio](https://docs.rs/tokio/1.40.0/x86_64-unknown-linux-gnu/tokio/index.html) and [hyper](https://docs.rs/hyper/1.4.1/x86_64-unknown-linux-gnu/hyper/index.html).

This guide covers how to deploy an Axum app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-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](#deploy-the-axum-app-to-railway).

To create a new Axum app, ensure that you have [Rust](https://www.rust-lang.org/tools/install) installed on your machine.

Run the following command in your terminal to create a new Axum app:

```bash
cargo new helloworld --bin
```

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:

```bash
cargo add axum
cargo add tokio --features full
```

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:

```rust
use axum::{
    routing::get,
    Router,
};

#[tokio::main]
async fn main() {
    // build your application with a single route
    let app = Router::new().route("/", get(root));

    // Get the port number from the environment, default to 3000
    let port: u16 = std::env::var("PORT")
        .unwrap_or_else(|_| "3000".to_string()) // Get the port as a string or default to "3000"
        .parse() // Parse the port string into a u16
        .expect("Failed to parse PORT");

    // Create a socket address (IPv6 binding)
    let address = SocketAddr::from(([0, 0, 0, 0, 0, 0, 0, 0], port));
    let listener = tokio::net::TcpListener::bind(&address).await.unwrap();

    // Run the app with hyper, listening on the specified address
    axum::serve(listener, app).await.unwrap();
}

// basic handler that responds with a static string
async fn root() -> &'static str {
    "Hello World, from Axum!"
}
```

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:

```bash
cargo run
```

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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/5HAMxu)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=axum" target="_blank">variety of Axum templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Axum app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - 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](https://nixpacks.com/docs/providers/rust).

5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729880417/docs/quick-start/axum_app_service.png"
alt="screenshot of the deployed Axum service"
layout="responsive"
width={1982} height={1822} quality={100} />

### Deploy from a GitHub repo

To deploy an Axum app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
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](https://nixpacks.com/docs/providers/rust).

5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Axum app's root directory.
2. Add the content below to the `Dockerfile`:

   ```docker
   FROM lukemathwalker/cargo-chef:latest-rust-1 AS chef

   # Create and change to the app directory.
   WORKDIR /app

   FROM chef AS planner
   COPY . ./
   RUN cargo chef prepare --recipe-path recipe.json

   FROM chef AS builder
   COPY --from=planner /app/recipe.json recipe.json

   # Build dependencies - this is the caching Docker layer!
   RUN cargo chef cook --release --recipe-path recipe.json

   # Build application
   COPY . ./
   RUN cargo build --release

   CMD ["./target/release/helloworld"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Axum apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

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.

Deploy a Rust Axum App

[Beego](https://github.com/beego/beego) is a high-performance, open-source web framework designed for building robust applications in Go (Golang). It is used for rapid development of enterprise apps, including RESTful APIs, web apps and backend services.

This guide covers how to deploy a Beego app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Beego app!

## Create a Beego app

**Note:** If you already have a Beego app locally or on GitHub, you can skip this step and go straight to the [Deploy Beego App to Railway](#deploy-the-beego-app-to-railway).

To create a new Beego app, ensure that you have [Go](https://go.dev/dl) and [Bee tool](https://doc.meoying.com/en-US/beego/developing/#manual-installation) installed on your machine.

Run the following command in your terminal to create a new Beego app and install all dependencies:

```bash
bee new helloworld
cd helloworld
go mod tidy
```

A new Beego app will be provisioned for you in the `helloworld` directory.

### Configure database

Run `go get github.com/lib/pq` in your terminal to install the Go Postgres driver.

Create a database, `helloworld_dev` in your local Postgres instance.

Open the `main.go` file and modify the content to the code below:

```go
package main

import (
	"fmt"
	_ "helloworld/routers"

	_ "github.com/lib/pq"

	"github.com/beego/beego/v2/client/orm"
	beego "github.com/beego/beego/v2/server/web"
)

// Users -
type Users struct {
	ID        int    `orm:"column(id)"`
	FirstName string `orm:"column(first_name)"`
	LastName  string `orm:"column(last_name)"`
}

func init() {
	// set default database
	orm.RegisterDriver("postgres", orm.DRPostgres)

	// set default database
	orm.RegisterDataBase("default", "postgres", "postgres://unicodeveloper:@localhost/helloworld_dev?sslmode=disable")

	// register model
	orm.RegisterModel(new(Users))

	// create table
	orm.RunSyncdb("default", false, true)
}

func main() {
	o := orm.NewOrm()

	// Create a slice of Users to insert
	users := []Users{
		{FirstName: "John", LastName: "Doe"},
		{FirstName: "Jane", LastName: "Doe"},
		{FirstName: "Railway", LastName: "Deploy Beego"},
	}

	// Iterate over the slice and insert each user
	for _, user := range users {
		id, err := o.Insert(&user)
		if err != nil {
			fmt.Printf("Failed to insert user %s %s: %v\n", user.FirstName, user.LastName, err)
		} else {
			fmt.Printf("Inserted user ID: %d, Name: %s %s\n", id, user.FirstName, user.LastName)
		}
	}

	beego.Run()
}
```

Replace this `postgres://username:@localhost/helloworld_dev?sslmode=disable` with the appropriate URL for your local Postgres database.

**Code Summary**:

- The Users struct defines the schema for the users table in the database.
- The `init()` function registers the Postgres driver, registers the Users model, and automatically creates the users table in the database. If any errors occur while inserting users, they are logged.
- The `main()` function creates an ORM instance, defines sample user data (first name and last name), inserts the data into the users table, and starts the Beego web server to serve your app.

### Run the Beego app locally

To start your app, run:

```bash
bee run
```

Once the app is running, open your browser and navigate to `http://localhost:8080` to view it in action.

In your terminal, you’ll see logs indicating that the user data is being inserted. Head over to your database, and you should see the users table populated with the seeded data.

### Prepare Beego app for deployment

1. Open the `conf/app.conf` file and add an environment variable, `DATABASE_URL` to it.

```go
db_url = ${DATABASE_URL}
```

2. Head over to the `main.go` file and make some modifications to the way the Postgres database url is retrieved. The `init()` function should look like this:

```go
func init() {
	// set default database
	orm.RegisterDriver("postgres", orm.DRPostgres)

	// set default database
	dbURL, err := beego.AppConfig.String("db_url")
	if err != nil {
		log.Fatal("Error getting database URL: ", err)
	}

	orm.RegisterDataBase("default", "postgres", dbURL)

	// register model
	orm.RegisterModel(new(Users))

	// create table
	orm.RunSyncdb("default", false, true)
}
```

## Deploy the Beego app to Railway

Railway offers multiple ways to deploy your Beego 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/CPq9Ry)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=beego" target="_blank">variety of Beego app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Beego app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:

   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter `DATABASE_URL=${{Postgres.DATABASE_URL}}`.
     - The value, `${{Postgres.DATABASE_URL}}`, references the URL of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.

5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731331898/docs/quick-start/beego_on_railway.png"
alt="screenshot of the deployed Beego service"
layout="responsive"
width={2420} height={1986} quality={100} />

### Deploy from a GitHub repo

To deploy a Beego app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s a Go app](https://nixpacks.com/docs/providers/go).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the Beego app's root directory.
2. Add the content below to the `Dockerfile`:

   ```docker
   # Use the Go 1.22 official image
   # https://hub.docker.com/_/golang
   FROM golang:1.22

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . ./

   # Install project dependencies
   RUN go mod download

   # Build the app
   RUN go build -o app

   # Run the service on container startup.
   ENTRYPOINT ["./app"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Beego apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Beego app to Railway with this step-by-step guide. It covers quick setup, private networking, database integration, one-click deploys and other deployment strategies.

Deploy a Beego App

## How can you privately send traffic from Railway to RDS?

In this tutorial, you will set up a Tailscale bridge to AWS RDS. This creates a secure tunnel between your Railway services and your AWS RDS database instances. This allows you to connect to your RDS databases privately without exposing traffic to the public internet.

### Objectives

In this tutorial, you will:

1. Deploy a Tailscale subnet router EC2 instance
1. Set up split DNS for domain resolution
1. Verify and test connectivity to your RDS instance
1. Route traffic from Railway to RDS using Railtail

This tutorial is in depth, so if it's your first time using Tailscale or setting up a bridge to your RDS instance, every detail is covered!

### Prerequisites

1. You will need an [AWS IAM access key or IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html) to stand up resources with Terraform or OpenTofu.

   **NOTE:** While you can just put these secrets in a `~/.aws` folder or a `terraform.tfvars` file, it's a good practice to avoid putting secrets on disk unencrypted. If you have 1Password, you can use [1Password Secret References](https://developer.1password.com/docs/cli/secret-references/) so that your secrets are never stored permanently on disk. This is especially important to prevent AI tools from reading your keys and as an extra layer of protection from committing secrets to your git repositories.

2. You'll need to install [Terraform](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli) or [OpenTofu](https://opentofu.org/docs/intro/install/).

3. You will need to generate a new ssh key that can be used to provision the AWS Instance.

4. You will need a [Tailscale account](https://tailscale.com/) and have [Tailscale installed](https://tailscale.com/kb/1347/installation) on your local machine. The free tier is generous and sufficient for this tutorial.

5. You will need to generate, store, and reference a [Tailscale Auth Key](https://login.tailscale.com/admin/settings/keys)

```bash
# Set your AWS credentials
export AWS_ACCESS_KEY_ID=my-access-key
export AWS_SECRET_ACCESS_KEY=my-secret-key
# Or with 1password
export AWS_ACCESS_KEY_ID=$(op read op://vault-name/aws-personal-access-key/access_key_id)
export AWS_SECRET_ACCESS_KEY=$(op read op://vault-name/aws-personal-access-key/secret_access_key)

# Generate an SSH key for the EC2 instance if you don't have one
ssh-keygen -t rsa -b 2048 -f ~/.ssh/tailscale-rds

# Set your Tailscale auth key
# terraform.tfvars
#...
tailscale_auth_key = "tskey-auth-1234567890"
# Or with 1password
tailscale_auth_key = $(op read op://vault-name/tailscale-auth-key/credential)
```

### Generate a Tailscale auth key

- Head over to the [Keys](https://login.tailscale.com/admin/settings/keys) page located within the settings menu on the Tailscale dashboard.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349121/docs/tutorials/tailscale-subnet-router/keys_page_vohahp.png"
alt="screenshot of the tailscale settings page"
layout="intrinsic"
width={1261} height={772} quality={100} />

- Click **Generate auth key**.

  Put in a description like "AWS RDS Subnet Router" and leave all other settings as the default.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349121/docs/tutorials/tailscale-subnet-router/generate_auth_key_oxqr8m.png"
alt="screenshot of the generate auth key modal in tailscale"
layout="intrinsic"
width={602} height={855} quality={100} />

- Click **Generate key**.

  Tailscale will now show you the newly generated auth key. **Be sure to copy it down, and store it in secret store (like 1Password)**.

- Click **Done**.

## Git clone the example project

There is [an example project built in Terraform](https://github.com/echohack/rds-tailscale) (or OpenTofu if you prefer) to stand up all the AWS resources you'll need to test out connectivity to RDS.

```bash
git clone git@github.com:echohack/rds-tailscale.git
```

### Create terraform.tfvars

Create a `terraform.tfvars` file to store your variables:

```
aws_account = "your-aws-account-id"
rds_password = "your-secure-rds-password"
tailscale_auth_key = "tskey-your-tailscale-auth-key"
```

**!IMPORTANT**: Make sure you update your `userlist.txt` password to the same password as your new `rds_password`.

### Deploy

Initialize and apply the Terraform configuration:

```bash
terraform init
terraform plan
terraform apply
```

Review the changes and type `yes` to confirm deployment.

When the deployment completes, you'll see outputs including instructions for configuring split DNS and how to run the test script to verify your deployment.

## Configure split DNS in Tailscale

Split DNS allows Tailscale to resolve AWS RDS domain names using AWS DNS servers, which is required for RDS connectivity.

- Go to the [Tailscale Admin Console DNS settings](https://login.tailscale.com/admin/dns)
- Click **Add Nameserver** → Choose **Custom**

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349122/docs/tutorials/tailscale-subnet-router/tailscale_nameservers_en8oma.png"
alt="screenshot of the nameservers dropdown in tailscale"
layout="intrinsic"
width={813} height={683} quality={100} />

- Enter the VPC DNS server IP: `172.16.0.2` (VPC CIDR base + 2)
- Enable **Restrict to domains**
- Enter: `us-west-2.rds.amazonaws.com` (replace `us-west-2` with your AWS region)

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349120/docs/tutorials/tailscale-subnet-router/add_nameserver_mlkk5y.png"
alt="screenshot of the add nameserver modal in tailscale"
layout="intrinsic"
width={602} height={572} quality={100} />

- Click **Save**

## Approve advertised subnet routes and/or enable route acceptance on your devices

For devices you can't install Tailscale on, you need to [approve the routes in the Tailscale admin UI](https://login.tailscale.com/admin/machines).

- You will see a `Subnets !` badge on the machine you set up. This indicates it is advertising routes but hasn't been approved.
- Click the `...` next to the machine
- Click the checkbox and click save.
- Now the `!` will be removed from the `Subnets` badge, indicating that the advertised routes are approved.

For your local devices to access the subnet routes advertised by the subnet router, you can also enable route acceptance via the CLI:

```bash
tailscale set --accept-routes=true
```

## Verify connectivity

Run the verification script:

```bash
./verify_tailscale_routing.sh <rds_endpoint> postgres <password> rds-tailscale
```

The endpoint and other details can be found in the Terraform outputs after deployment.

If you're running into issues at this point, head down to the Troubleshooting section to help figure out what might be wrong.

## Connect to your RDS instance

Once the verification passes, you can connect to your RDS instance directly from your local machine using standard PostgreSQL tools or any database client:

```bash
psql -h <rds_endpoint> -U postgres -d tailscale_test_db
```

If you've never used Tailscale before, take a moment to familiarize yourself with the `tailscale` CLI and wrap your head around what's happening here. This is fantastic! You're routing traffic privately to your RDS instance from your local machine!

Similarly, you can now use this subnet router to route traffic from other devices in your Tailnet, including as a way to create a bridge between networks. Now you're ready to connect your Railway services! Let's do that next.

## Deploy railtail into your project

Railtail is a project that will forward SOCK5 traffic to RDS, because right now Railway containers don't allow privilege escalation. This way you can use private IPv6 networking to Railtail and forward your traffic privately to your AWS Subnet Router, which will then route to RDS.

- In a project where you want to bridge services privately to RDS, click the Create button in the upper right corner. Then select Template -> Type in RailTail.

You will need four variables to deploy Railtail and start bridging traffic to your RDS instance:

- **LISTEN_PORT**: This is the port that Railtail listens on to forward traffic. We like `41641`, which is Tailscale's default UDP port for making peer-to-peer connections.
- **TARGET_ADDR**: The target address that Railtail will forward traffic to. In this case it should be `tailscale-test-db.<subnet>.<region>.rds.amazonaws.com`. You can grab this from the output of the terraform run you did earlier, or in the AWS console.
- **TS_AUTH_KEY**: The tailscale auth key you 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.

<Image src="https://res.cloudinary.com/railway/image/upload/v1747163544/docs/tutorials/tailscale-subnet-router/railtail-to-rds_g10rrq.png"
alt="screenshot of railtail"
layout="intrinsic"
width={1544} height={533} quality={100} />

## Cleanup

When you're done with the tutorial, and so that AWS doesn't charge you money while your instances sit idle, you can destroy the resources you created automatically with:

```bash
terraform destroy -auto-approve
```

## Troubleshooting

If you encounter issues with connectivity check the `verify_tailscale_routing` script included with the repository. You may be encountering:

1. **DNS Resolution**:

- Verify split DNS configuration in Tailscale.
- Check that the correct AWS DNS server IP is being used.

2. **Route Acceptance**:

- Ensure subnet routes are being advertised by the subnet router and that you've approve those routes in the Tailscale Admin Console.
- Verify your client is accepting routes with `tailscale status`.

3. **Database Connection Failures**:

- Check security group rules to ensure the subnet router can access RDS.
- Confirm you're using the correct credentials. (!IMPORTANT `manage_master_user_password = false` must be set or else the RDS module will ignore using your set password)

4. **Subnet Router Issues**:

- Check that IP forwarding on is enabled with `cat /proc/sys/net/ipv4/ip_forward`.
- Verify Tailscale is running with `sudo systemctl status tailscaled`.

## Additional resources

- [Tailscale: Subnet Routers](https://tailscale.com/kb/1019/subnets)
- [Tailscale: AWS RDS](https://tailscale.com/kb/1235/rds-aws/)
- [Tailscale: High Availability](https://tailscale.com/kb/1115/high-availability)
- [AWS RDS PostgreSQL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_PostgreSQL.html)
- [PgBouncer Documentation](https://www.pgbouncer.org/usage.html)
- [RDS Parameter List](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Appendix.PostgreSQL.CommonDBATasks.Parameters.html)
- [Terraform AWS VPC Provider](https://registry.terraform.io/modules/terraform-aws-modules/vpc/aws/latest)
- [Terraform AWS RDS Module Provider](https://registry.terraform.io/modules/terraform-aws-modules/rds/aws/latest#input_parameters)
- [Tailscale Site-to-Site VPN Example (Terraform)](https://github.com/tailscale/terraform-aws-tailscale-site2sitevpn/tree/main)
- [Set Up a Tailscale Subnet Router on Railway](https://docs.railway.com/tutorials/set-up-a-tailscale-subnet-router)

Learn how to securely access your AWS RDS database from Railway using a Tailscale subnet router.

Create a Bridge from Railway to AWS RDS with Tailscale

## What is OpenTelemetry?

> 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 <a href="https://opentelemetry.io/docs/collector/" target="_blank">OpenTelemetry Collector</a>, listening for traces, metrics, and logs.
- Deploy a backend stack ([Jaeger](https://www.jaegertracing.io/), [Zipkin](https://zipkin.io/), and [Prometheus](https://prometheus.io/)) to receive the traces, metrics, and logs from the collector
- Build and instrument an <a href="https://expressjs.com/" target="_blank">Express</a> application to send data to the collector.

**Prerequisites**

To be successful using this tutorial, you should already have -

- Latest version of Railway [CLI installed](/cli#installing-the-cli)
- 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.
<a href="https://railway.com/template/7KNDff" target="_blank"><img src="https://railway.com/button.svg" alt="Deploy on Railway" /></a>

There is also a live demo of the project you will build in this tutorial <a href="https://classy-writing-production.up.railway.app/" target="_blank">here</a>, and you can access the code repository <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack" target="_blank">here in Github</a>. You can find some example apps, including the one you will build in this tutorial, in the <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack/tree/main/exampleApps" target="_blank">exampleApps folder</a>.

**Let's get started!**

## 1. Deploy the backend services

First, deploy the backend services:

- <a href="https://www.jaegertracing.io/" target="_blank">Jaeger</a> - an open-source, distributed tracing system that will receive telemetry data from the collector
- <a href="https://zipkin.io/" target="_blank">Zipkin</a> - also an open-source, distributed tracing system that will receive telemetry data from the collector
- <a href="https://prometheus.io/" target="_blank">Prometheus</a> - 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
  ```plaintext
  PORT=16686
  ```
  _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
  ```plaintext
  PORT=9411
  ```
  _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](https://railway.com/template/KmJatA))
- 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 <a href="https://opentelemetry.io/docs/collector/#when-to-use-a-collector" target="_blank">here</a>.

### Fork the open telemetry collector repository

- Navigate to the <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack" target="_blank">Open Telemetry Collector repository</a> 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
  ```plaintext
  PORT=55679
  ```
  _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 <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack/blob/main/otel-collector-config.yaml#L31" target="_blank">zpages extension in the collector's configuration yaml</a>. You can read more about the UI and the available routes, in the collector's <a href="https://github.com/open-telemetry/opentelemetry-collector/blob/main/extension/zpagesextension/README.md" target="_blank">source repo</a>.

---

## 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 -

<Image src="https://res.cloudinary.com/railway/image/upload/v1709927450/docs/tutorials/otel/CleanShot_2024-03-08_at_13.47.12_2x_iuhawv.png"
alt="Screenshot of Project Canvas"
layout="responsive"
width={1177} height={823} quality={100} />

Be sure to familiarize yourself with the Otel Collector's <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack/blob/main/otel-collector-config.yaml" target="_blank">configuration file</a>. The documentation on the format and structure of the file can be found <a href="https://opentelemetry.io/docs/collector/configuration/" target="_blank">here in Otel's official docs</a>.

---

## 3. Build and instrument an Express app

Now that the collector stack is up, build and instrument an application!

_Note: The full source code for the <a href="https://github.com/railwayapp-templates/opentelemetry-collector-stack/tree/main/exampleApp" target="_blank">express app</a> that you will build is available in the Open Telemetry Collector repository that you forked in the previous steps._

### Create and initialize the project

From your local machine -

- Create a folder for your project called `otel-example-app`
- Use `npm` (or your preferred package manager) to install the required dependencies -

  ```npm
  npm i express @opentelemetry/api @opentelemetry/auto-instrumentations-node @opentelemetry/exporter-metrics-otlp-proto @opentelemetry/exporter-trace-otlp-proto @opentelemetry/resources @opentelemetry/sdk-metrics @opentelemetry/sdk-node @opentelemetry/semantic-conventions
  ```

### Build the app

- In the `otel-example-app` folder, create an `app.js` file and add the following code -

  ```javascript
  // app.js //
  const express = require("express");
  const { rollTheDice } = require("./dice.js");

  const PORT = parseInt(process.env.PORT || "8080");
  const app = express();

  app.get("/rolldice", (req, res) => {
    const rolls = req.query.rolls ? parseInt(req.query.rolls.toString()) : NaN;
    if (isNaN(rolls)) {
      res
        .status(400)
        .send("Request parameter 'rolls' is missing or not a number.");
      return;
    }
    res.send(JSON.stringify(rollTheDice(rolls, 1, 6)));
  });

  app.listen(PORT, () => {
    console.log(`Listening for requests on http://localhost:${PORT}`);
  });
  ```

- Create the `dice.js` file in the project folder and add the following code -

  ```javascript
  // Otel Docs Reference - https://opentelemetry.io/docs/languages/js/instrumentation/
  const { trace } = require("@opentelemetry/api");

  // obtain a trace
  const tracer = trace.getTracer("dice-lib");

  function rollOnce(i, min, max) {
    // start a span
    return tracer.startActiveSpan(`rollOnce:${i}`, span => {
      const result = Math.floor(Math.random() * (max - min) + min);

      // Add an attribute to the span
      span.setAttribute("dicelib.rolled", result.toString());

      // end the span
      span.end();
      return result;
    });
  }

  function rollTheDice(rolls, min, max) {
    // Create a span. A span must be closed.
    return tracer.startActiveSpan("rollTheDice", parentSpan => {
      const result = [];
      for (let i = 0; i < rolls; i++) {
        result.push(rollOnce(i, min, max));
      }
      // Be sure to end the span!
      parentSpan.end();
      return result;
    });
  }

  module.exports = { rollTheDice };
  ```

  Refer to the OpenTelemetry documentation to gain a richer understanding of this code. The code you see above can be found <a href="https://opentelemetry.io/docs/languages/js/instrumentation/" target="_blank">here</a>.

### Build the instrumentation sdk

- In the `otel-example-app` folder, create an `instrumentation.js` file and add the following code -

  ```javascript
  // Otel Docs Reference - https://opentelemetry.io/docs/languages/js/instrumentation
  const { NodeSDK } = require("@opentelemetry/sdk-node");
  const {
    getNodeAutoInstrumentations,
  } = require("@opentelemetry/auto-instrumentations-node");
  const {
    OTLPTraceExporter,
  } = require("@opentelemetry/exporter-trace-otlp-proto");
  const { Resource } = require("@opentelemetry/resources");
  const {
    SEMRESATTRS_SERVICE_NAME,
    SEMRESATTRS_SERVICE_VERSION,
  } = require("@opentelemetry/semantic-conventions");
  const {
    OTLPMetricExporter,
  } = require("@opentelemetry/exporter-metrics-otlp-proto");
  const {
    PeriodicExportingMetricReader,
  } = require("@opentelemetry/sdk-metrics");

  const sdk = new NodeSDK({
    resource: new Resource({
      [SEMRESATTRS_SERVICE_NAME]: "dice-server",
      [SEMRESATTRS_SERVICE_VERSION]: "0.1.0",
    }),
    traceExporter: new OTLPTraceExporter({
      url: `http://${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/traces`,
    }),
    metricReader: new PeriodicExportingMetricReader({
      exporter: new OTLPMetricExporter({
        url: `http://${process.env.OTEL_EXPORTER_OTLP_ENDPOINT}/v1/metrics`,
      }),
    }),
    instrumentations: [getNodeAutoInstrumentations()],
  });

  sdk.start();
  ```

  This code will wrap your application code and capture the telemetry data. In the steps that follow, you will see how to start your application in Railway with a custom start command that utilizes this SDK.

  Refer to the OpenTelemetry documentation to gain a richer understanding of this code. The code you see above can be found <a href="https://opentelemetry.io/docs/languages/js/instrumentation/" target="_blank">here</a>.

## 4. Deploy the Express app

### Create an empty service and configure the environment

In the same Railway project -

- Add a New service by clicking `+ New`
- Select `Empty Service`
- Add the following variable to the service
  ```plaintext
  OTEL_EXPORTER_OTLP_ENDPOINT=${{OpenTelemetry Collector.RAILWAY_PRIVATE_DOMAIN}}:4318
  ```
  _This is used by the Express app to connect to the OpenTelemetry Collector_
- In the service Settings, add the following [Custom Start Command](/deployments/start-command):
  ```plaintext
  node --require ./instrumentation.js app.js
  ```
  _This wraps the Express app on startup with the instrumentation SDK you created above._
- In the service Settings, rename the service to `Express App`
- Click `Deploy` to apply and create the empty service
- In the Settings tab, under Networking, click `Generate Domain`

### Deploy from the Railway CLI

_This step assumes you have the latest version of the [Railway CLI](/cli#installing-the-cli) installed._

On your local machine -

- Open your terminal and change directory to the `otel-example-app` folder
- Link to the Railway project and service by running the following command -

  ```plaintext
  railway link
  ```

  Follow the prompts selecting the correct project name and environment (click <a href="https://res.cloudinary.com/railway/image/upload/v1709917423/docs/tutorials/otel/CleanShot_2024-03-08_at_10.58.55_2x_kacssj.png" target="_blank">here</a> for a reference), and choose the `Express App` service.

- Deploy the Express App by running the following command -
  ```plaintext
  railway up -d
  ```

## 5. Test and confirm

Test that everything is working by generating some traffic to your Express App. There is a single route, `/rolldice`, that takes a `rolls` query string -

- `<YOUR_SERVICE_DOMAIN>/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.

<div style={{ display: 'flex', flexDirection: 'row', gap: '5px', fontSize: '0.9em', alignItems: 'stretch' }}>
    <div style={{ flex: '1 1 50%', overflow: 'auto', minWidth: '200px', maxWidth: '350px' }}>
        <Image src="https://res.cloudinary.com/railway/image/upload/v1709927026/docs/tutorials/otel/CleanShot_2024-03-08_at_13.42.44_2x_ym2ojg.png"
        alt="Screenshot of Jaeger UI"
        layout="responsive"
        width={1177} height={823} quality={100} />
        <p style={{ marginTop: '-0.2em', fontSize: '1em'}}>Jaeger</p>
    </div>
    <div style={{ flex: '1 1 50%', overflow: 'auto', minWidth: '200px', maxWidth: '350px' }}>
        <Image src="https://res.cloudinary.com/railway/image/upload/v1709926920/docs/tutorials/otel/CleanShot_2024-03-08_at_13.39.53_2x_zd69mq.png"
        alt="Screenshot of Zipkin Ui"
        layout="responsive"
        width={1177} height={823} quality={100} />
        <p style={{ marginTop: '-0.2em', fontSize: '1em'}}>Zipkin</p>
    </div>
</div>

## Bonus - nextjs

This tutorial was born out of an exploration into instrumenting some of Railway's applications with <a href="https://nextjs.org/docs/pages/building-your-application/optimizing/open-telemetry#custom-exporters" target="_blank">NextJS's Otel library</a>. This means that you can use this Otel collector stack to capture telemetry data from your NextJS app!

### Send telemetry data from nextjs

Assuming you've followed the docs mentioned above to instrument your NextJS app, you can configure it to send requests to your collector in Railway by setting the required environment variable in the NextJS application.

_If your Next App is deployed in the **same Railway project as the collector**, you can use the private network -_

```plaintext
OTEL_EXPORTER_OTLP_ENDPOINT=http://${{otel-collector.RAILWAY_PRIVATE_DOMAIN}}:4318
```

_If your Next App is deployed in **another Railway project, or outside of Railway entirely**, you can use the public network -_

```plaintext
OTEL_EXPORTER_OTLP_ENDPOINT=https://<PUBLIC DOMAIN OF THE COLLECTOR IN RAILWAY>
```

- Note: If you use the public domain, you will need to update the PORT environment variable in your Otel Collector service to `PORT=4318`

#### Debugging in nextjs

Another helpful environment variable, specific to Node, is the debug directive -

```plaintext
OTEL_LOG_LEVEL=debug
```

## Helpful resources

The OpenTelemetry Documentation is complete and easy to follow. Spend time getting familiar with the docs. Here are some sections that are especially helpful -

- [OpenTelemetry Components](https://opentelemetry.io/docs/concepts/components/)
- [OTLP Spec](https://opentelemetry.io/docs/specs/otlp/)
- [Collector Docs](https://opentelemetry.io/docs/collector/)
- [Collector Configuration Tool OTelBin](https://www.otelbin.io)
- [Supported Languages](https://opentelemetry.io/docs/languages/)
- [Vendors with Native OTLP Support](https://opentelemetry.io/ecosystem/vendors/) (explore this list for different backend options)

## Conclusion

Congratulations! You have deployed an OpenTelemetry Collector and a Node Express app that sends data to the collector which then sends it to Jaeger, Prometheus, and Zipkin.

This is a _very_ basic implementation, and you should refer to the <a href="https://opentelemetry.io/docs/" target="_blank">OpenTelemetry documentation</a> for information on how to customize your implementation.

Monitor and trace your applications by deploying an OpenTelemetry Collector and backend on Railway.

Deploy an OpenTelemetry Collector and Backend on Railway

In this guide, you'll learn how to deploy a [Node.js](https://nodejs.org/) and [Express.js](https://expressjs.com/) API to production using Railway. You'll build and deploy an API with automatic scaling, environment secrets management, and preview environments.

## What is Railway?

Railway is a modern deployment platform that enables you to deploy applications without managing servers, configuring load balancers, or learning Kubernetes. It provides automatic scaling, zero-downtime deployments, and built-in CI/CD.

Learn more about Railway's [core components and foundations](/overview/the-basics).

## Prerequisites

This is a beginner-friendly guide. However, it assumes basic knowledge of [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) or [TypeScript](https://www.typescriptlang.org/) (preferred). You'll also need to have Node.js installed on your machine.

To successfully complete this guide, you'll need:

- A Railway account
- A [GitHub](https://github.com/) account with [git](https://git-scm.com/) configured
- Node.js installed locally - you can use [nvm](https://github.com/nvm-sh/nvm) to manage your Node.js versions

You can find the final code on [GitHub](https://github.com/railway/nodejs-express-tutorial).

## Project setup

Let's create a new Node.js project from scratch with TypeScript support. First, create a new directory and initialize the project:

```bash
mkdir my-express-api
cd my-express-api
npm init -y
```

### Install TypeScript and dependencies

Install TypeScript, Express, and the necessary type definitions:

```bash
npm install express dotenv
npm install -D typescript @types/node @types/express tsx
```

- [Express](https://expressjs.com/) - Web framework for Node.js
- [dotenv](https://www.npmjs.com/package/dotenv) - Loads environment variables from `.env` files
- [TypeScript](https://www.typescriptlang.org/) - Typed superset of JavaScript
- [tsx](https://tsx.is/) - TypeScript execution engine

### Configure TypeScript

Create a `tsconfig.json` file in your project root. Learn more about [TypeScript configuration options](https://www.typescriptlang.org/tsconfig):

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}
```

### Create the project structure

Create a `src` directory and the main application file:

```bash
mkdir src
```

Create `src/app.ts` with the following code:

```typescript
import express from 'express';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

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

// Middleware
app.use(express.json());

// Routes
app.get('/', (req, res) => {
  res.json({ 
    message: 'Express API is running!',
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV || 'development',
    appName: process.env.APP_NAME || 'My Express API'
  });
});

app.get('/api/users', (req, res) => {
  res.json([
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
  ]);
});

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

### Set up environment variables

Create a `.env` file in your project root to store environment variables:

```bash
# .Env
APP_NAME=My Express API
NODE_ENV=development
PORT=3000
```

**Important**: Create a `.gitignore` file in your project root and add the following entries to keep sensitive data and dependencies out of version control:

```gitignore
# Environment variables
.env

# Dependencies
node_modules/

# Build output
dist/

# Logs
*.log
```

This ensures that sensitive environment variables, installed dependencies, and build artifacts are not committed to your repository.

Learn more about [`.gitignore` patterns](https://git-scm.com/docs/gitignore) and [environment variable security best practices](https://12factor.net/config).

Learn more about [managing variables](/variables) in Railway.

### Update package.json scripts

Update your `package.json` to include the necessary scripts. Learn more about [npm scripts](https://docs.npmjs.com/cli/v8/using-npm/scripts):

```json
{
  "scripts": {
    "dev": "tsx src/app.ts",
    "build": "tsc",
    "start": "node dist/app.js"
  }
}
```

### Run the development server

Now you can run your TypeScript application using [tsx](https://tsx.is/), which provides seamless TypeScript execution without worrying about configuration:

```bash
npm run dev
```

If you open your browser and navigate to `http://localhost:3000`, you'll see your Express API running with TypeScript support.

Learn more about [customizing builds](/builds) and [build configuration](/builds/build-configuration) in Railway.


## Deploy to Railway from GitHub

Now let's deploy this API to Railway. First, create a Railway account by going to [railway.com/new](https://railway.com/new) and signing up with your [GitHub](https://github.com/) account.


1. **Create a GitHub repository**:
   - Go to [GitHub](https://github.com/) and click "New repository"
   - Name it `my-express-api` (or any name you prefer)
   - Make it public or private
   - Don't initialize with README, .gitignore, or license (you already have these)
   - Click "Create repository"

2. **Push your code to GitHub**:
   ```bash
   git init
   git add .
   git commit -m "Initial Express API"
   git remote add origin https://github.com/yourusername/my-express-api.git
   git push -u origin main
   ```
   
   Learn more about [Git basics](https://git-scm.com/book/en/v2/Git-Basics-Getting-a-Git-Repository) if you're new to version control.

3. **Deploy from Railway**:
   - In Railway, click "Deploy from GitHub repo"
   - Select your repository
   - Railway automatically detects it's a Node.js app

4. **Configure environment variables**:
   - Click on your deployed service
   - Go to the "Variables" tab
   - Add the following variables:
     - `NODE_ENV=production`
     - `APP_NAME=My Production API`
   - Apply the changes and deploy

5. **Generate a public URL**:
   - Go to "Settings" → "Networking"
   - Click "Generate Domain"
   - Your API is now live at `https://your-app.up.railway.app`. When you visit this URL, you should see your Express API running.

Learn more about [deploying applications](/templates/deploy), [public networking](/networking/public-networking), and [staged changes](/deployments/staged-changes) in Railway.


## Scaling and pricing

Railway automatically manages your application's scaling without any configuration needed. Here's how it works:

### Vertical scaling (automatic)

Railway automatically scales your service vertically by increasing CPU and memory allocation as traffic grows. This happens seamlessly up to your plan's limits

Check out the Railway [pricing page](https://railway.com/pricing) for more details about the different plans and their limits.




### Horizontal scaling (one-click)

For high-traffic applications, you can scale horizontally by deploying multiple replicas:

1. In your Railway project, click on your service
2. Go to the "Settings" tab
3. Under "Scaling", increase the instance count
4. Railway automatically distributes traffic across all replicas

![Horizontal scaling](https://res.cloudinary.com/railway/image/upload/v1758247839/docs/horizontal_scaling_xil1q0.png)

Each replica runs with the full resource limits of your plan. So if you're on the Pro plan and deploy 3 replicas, you get a combined capacity of 72 vCPU and 72 GB RAM.

```bash
Total resources = number of replicas × maximum compute allocation per replica
```

### Multi-region deployment

Railway also supports multi-region deployments for global applications:

1. Deploy replicas in different geographical regions
2. Railway automatically routes traffic to the nearest region
3. Traffic is then distributed randomly across available replicas within that region

![Multi-region deployment](https://res.cloudinary.com/railway/image/upload/v1758247839/docs/multi-region_deployment_h5fxqz.png)

This gives you both high availability and low latency for users worldwide, all with just a few clicks.

Learn more about [scaling applications](/deployments/scaling) and [optimizing performance](/deployments/optimize-performance) in Railway.


### Usage-based pricing

Railway follows a usage-based pricing model that depends on how long your service runs and the amount of resources it consumes. You only pay for activce CPU and memory, not for idle time.

```
Active compute time x compute size (memory and CPU)
```

![railway usage-based pricing](https://res.cloudinary.com/railway/image/upload/v1753470546/docs/comparison-docs/railway-usage-based-pricing_efrrjn.png)

Pricing plans start at $5/month. You can check out the [pricing page](https://railway.com/pricing) for more details.


## Add healthcheck for zero-downtime deployments

To ensure zero-downtime deployments, you'll need to add a healthcheck endpoint that Railway can use to verify your application is running properly. Learn more about [health check patterns](https://microservices.io/patterns/observability/health-check-api.html) and [zero-downtime deployment strategies](https://martinfowler.com/bliki/BlueGreenDeployment.html).

### Add the healthcheck endpoint

Update your `src/app.ts` file to include a healthcheck endpoint:

```typescript
// Add this route before app.listen()
app.get('/health', (req, res) => {
  res.status(200).json({ 
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: process.uptime()
  });
});
```

Your complete `src/app.ts` should now look like this:

```typescript
import express from 'express';
import dotenv from 'dotenv';

// Load environment variables
dotenv.config();

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

// Middleware
app.use(express.json());

// Routes
app.get('/', (req, res) => {
  res.json({ 
    message: 'Express API is running!',
    timestamp: new Date().toISOString(),
    environment: process.env.NODE_ENV || 'development',
    appName: process.env.APP_NAME || 'My Express API'
  });
});

app.get('/api/users', (req, res) => {
  res.json([
    { id: 1, name: 'John Doe', email: 'john@example.com' },
    { id: 2, name: 'Jane Smith', email: 'jane@example.com' }
  ]);
});

app.get('/health', (req, res) => {
  res.status(200).json({ 
    status: 'healthy',
    timestamp: new Date().toISOString(),
    uptime: process.uptime(),
    appName: process.env.APP_NAME || 'My Express API'
  });
});

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

### Deploy the healthcheck

Push your changes to GitHub:

```bash
git add .
git commit -m "Add healthcheck endpoint"
git push origin main
```

### Configure healthcheck in Railway

1. **Go to your service settings**:
   - In your Railway project, click on your deployed service
   - Navigate to the "Settings" tab

2. **Configure the healthcheck**:
   - Scroll down to the "Healthcheck" section
   - Set the **Healthcheck Path** to `/health`

![Healthchecks](https://res.cloudinary.com/railway/image/upload/v1758247840/docs/healthchecks_dx1ipr.png)

With the healthcheck configured, Railway will:
- Check your application's health before routing traffic to new deployments
- Automatically rollback if the healthcheck fails
- Ensure zero-downtime deployments by only switching traffic when the new version is healthy

Learn more about [configuring healthchecks](/deployments/healthchecks) in Railway.


## Set up preview environments

Railway can spin up temporary environments for every pull request. First, you need to enable PR environments. Learn more about [GitHub Pull Requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests):

1. Go to your Project Settings → Environments tab
2. Enable "PR Environments" 
3. Optionally enable "Bot PR Environments" for automated PRs from [Dependabot](https://docs.github.com/en/code-security/dependabot) or [Renovatebot](https://renovatebot.com/)

![PR Environments](https://res.cloudinary.com/railway/image/upload/v1758274258/docs/PR_environmetns_q4z0yy.png)

Once enabled, create a feature branch to test this:

```bash
git checkout -b feature/new-endpoint
```

Add a new endpoint to your TypeScript application by updating `src/app.ts`:

```typescript
// Add this route before app.listen()
app.get('/api/status', (req, res) => {
  res.json({
    status: 'Preview environment is working!',
    timestamp: new Date().toISOString(),
    appName: process.env.APP_NAME || 'My Express API',
    environment: process.env.NODE_ENV || 'development',
    version: '1.0.0-preview'
  });
});
```

Push the changes and create a pull request:

```bash
git add .
git commit -m "Add GET /api/status endpoint"
git push origin feature/new-endpoint
```

Railway will automatically create a temporary environment for your pull request, giving you a unique URL to test your changes. The environment is automatically deleted when the PR is merged or closed.

**Note**: Railway will only deploy PR branches from team members or users invited to your project. For automatic domain provisioning, ensure your base environment services use Railway-provided domains.

Learn more about [using environments](/environments) and [PR environments](/environments#enable-pr-environments) in the Railway documentation.

## Deploy multiple services

Railway makes it easy to deploy multiple lightweight Node.js microservices without learning [Kubernetes](https://kubernetes.io/) or [Docker](https://www.docker.com/) orchestration. You can deploy several services within a single project to achieve a [microservice architecture](https://microservices.io/).

To add more microservices to your project:

1. In your Railway project, click the "+" button
2. Choose "Deploy from GitHub repo"
3. Select another repository containing a different Node.js service
4. Railway automatically detects and deploys each service independently

![Deploy multiple services](https://res.cloudinary.com/railway/image/upload/v1758274862/microservice_cpul8g.png)

Each service runs in its own container with its own resources, but they can communicate with each other through Railway's [private networking](/networking/private-networking).

### Shared variables between services

Railway supports shared variables across all services in a project, making it easy to share configuration like database URLs, API keys, and other common settings. Learn more about [configuration management patterns](https://12factor.net/config):

1. Go to your project's "Settings" → "Shared Variables"
2. Add variables that all services need (e.g., `DATABASE_URL`, `API_KEY`)
3. Each service can reference these shared variables using Railway's template syntax

For example, if you have a shared `DATABASE_URL` variable, any service can reference it with:
```bash
DATABASE_URL=${{shared.DATABASE_URL}}
```

This eliminates duplication and makes it easy to manage configuration across your entire microservice architecture.

Learn more about [managing services](/services), [shared variables](/variables#shared-variables), and [service communication](/services) in the Railway documentation.

## Conclusion

In this guide, you learned how to deploy Node.js and Express applications to production using Railway's zero-configuration deployment platform. You built:

- A production-ready Express REST API with automatic scaling
- A TypeScript application with automated builds
- Preview environments for every pull request

Railway makes Node.js deployment simple by providing:

- **Zero configuration**: Deploy from GitHub without Dockerfiles or complex setup
- **Automatic scaling**: Handle traffic spikes without manual intervention
- **Built-in CI/CD**: Preview environments and zero-downtime deployments
- **Usage-based pricing**: Pay only for what you use. Check out the Railway [pricing page](https://railway.com/pricing) for more details.

## Next steps

Now that you've deployed your Node.js applications, explore these resources:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your application](/observability)
- [View logs and metrics](/observability/logs) and [metrics](/observability/metrics)
- [Set up custom domains](/networking/public-networking)
- [Configure environment variables](/variables)
- [Deploy with Docker](/builds/dockerfiles)
- [Customize builds](/builds)
- [Manage deployments](/integrations/api/manage-deployments)

## Need help?

If you have any questions or run into issues, you can reach out in the [Railway Discord](http://discord.gg/railway) community or on [Central Station](https://station.railway.com/).

Learn how to deploy Node.js and Express applications with automatic scaling, environment secrets, zero-downtime updates, and preview environments, all without managing servers or learning Kubernetes/container orchestration.

Deploy Node.js & Express API with Autoscaling, Secrets, and Zero Downtime

## What is a monorepo?

A monorepo is a project directory structure in which multiple, co-dependent codebases (such as a frontend and a backend) are maintained within the same repository, and in some cases, share common packages.

## About this tutorial

Deploying a monorepo in Railway requires some extra configuration to get the applications up and running.

This tutorial aims to provide a simple step-by-step on how to deploy a frontend and backend from an isolated monorepo, one of the most commonly deployed types of monorepo.

The procedure outlined in this tutorial can easily be adapted to deploy different apps that are contained within a isolated monorepo as well.

For more information on deploying a shared monorepo check out the <a href="/guides/monorepo#deploying-a-shared-monorepo" target="_blank">guide</a> that explains some of the specific configurations you would need. If you are importing a JS monorepo, check out the <a href="/guides/monorepo#automatic-import-for-javascript-monorepos" target="_blank">guide</a> for automatic import.

**Objectives**

In this tutorial, you will learn how to -

- Create an empty project.
- Rename a project.
- Create empty services.
- Rename services.
- Generate domains for services.
- Set variables on a service.
- Connect a GitHub repo to a service.

**Prerequisites**

For the sake of this tutorial, there is a simple [example monorepo](https://github.com/railwayapp-templates/monorepo-example) with a frontend and a backend service. In practice, your monorepo is probably a lot more complicated, but the principles here will enable you to wire up each of your applications in your monorepo to a service and network those services together.

The frontend is built with [React](https://react.dev/) and [Vite](https://vitejs.dev/), and the static files are served with [Caddy](https://caddyserver.com/).

The backend, built with [Go](https://go.dev/), will stream quotes that will be displayed on the frontend.

Before you start:

1. Fork the repo: https://github.com/railwayapp-templates/monorepo-example
2. [Connect your GitHub to Railway.](https://docs.railway.com/quick-start#deploying-your-project---from-github) This will enable you to deploy any of your repositories to Railway in the future as well!

**Let's get started!**

## 1. Create a new empty project

- From [your dashboard](https://railway.com/dashboard) click `+ New Project` or `⌘ k`

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269034/docs/tutorials/monorepo/dashboard_zojmjg.png"
alt="Screenshot of dashboard"
layout="responsive"
width={1280} height={511} quality={100} />

- Choose `Empty project`

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269027/docs/tutorials/monorepo/new_project_hxiif2.png"
alt="Screenshot of new project page"
layout="responsive"
width={345.5} height={388} quality={100} />

**Note:** An empty project is chosen instead of deploying from a GitHub repo since you want to set up the project before deploying.

## 2. Project setup

- You'll notice Railway automatically named the project, but you want something more recognizable. Open the Settings tab to `Update` the name of your project. You'll also notice the Danger tab here, when you want to delete your project after you're done with the tutorial.

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269026/docs/tutorials/monorepo/project_settings_ym1vul.png"
alt="Screenshot of project settings"
layout="responsive"
width={1381} height={731} quality={100} />

- Click `Update`

## 3. Service creation

- Add **two** new **empty** services from the `+ Create` button in the top right of the project canvas.

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269020/docs/tutorials/monorepo/create_menu_gtpxtb.png"
alt="Screenshot of create menu"
layout="responsive"
width={735} height={510} quality={100} />

**Note:** An empty service is chosen instead of deploying from a GitHub repo since you want to configure the service before deploying.

The result will look like this -

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269019/docs/tutorials/monorepo/two_services_unamed_nmwimm.png"
alt="Screenshot of project canvas with two empty services"
layout="responsive"
width={766} height={450} quality={100} />

- Give them both applicable names.

  **Note:** This can be done easiest via the right-click context menu.

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269022/docs/tutorials/monorepo/naming_a_service_qy7sg5.png"
alt="Screenshot of naming a service"
layout="responsive"
width={766} height={450} quality={100} />

In the case of this tutorial, they will be named `Frontend` and `Backend`

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269024/docs/tutorials/monorepo/deploy_button_gmnqf8.png"
alt="Screenshot showing the deploy button"
layout="responsive"
width={766} height={450} quality={100} />

- Click the `Deploy` button or `⇧ Enter` to create these two services.

## 4. Directory setup

Both apps deploy from subdirectories of the monorepo, so you need to tell Railway where they are located.

- Open the Frontend service to its service settings and you will see a **Root Directory** option, in this case, set it to `/frontend`

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269052/docs/tutorials/monorepo/frontend_root_dir_e52vkz.png"
alt="Screenshot showing the frontend root directory"
layout="responsive"
width={1386} height={760} quality={100} />

- Open the Backend service settings and set its root directory to `/backend`

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269046/docs/tutorials/monorepo/backend_root_dir_misneo.png"
alt="Screenshot showing the backend root directory"
layout="responsive"
width={1386} height={760} quality={100} />

- Click the `Deploy` button or `⇧ Enter` to save these changes.

## 5. Connecting the repo

Now configure the source of the service where the code is deployed.

- Open the service settings for each service and connect your monorepo.

Frontend

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269039/docs/tutorials/monorepo/frontend_repo_connect_llgsmf.png"
alt="Screenshot showing the frontend repo connected"
layout="responsive"
width={1386} height={760} quality={100} />

Backend

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269044/docs/tutorials/monorepo/backend_repo_connect_evt8v3.png"
alt="Screenshot showing the backend repo connected"
layout="responsive"
width={1386} height={760} quality={100} />

- Click the `Deploy` button or `⇧ Enter` to deploy your applications

**Your services will now build and deploy.**

## 6. Domain setup

Even though the services are now running, the frontend and backend aren't networked together yet. So let's setup domains for each service.

Both the Vite Frontend and the Go Backend are already configured so that Railway will ✨automagically detect the port they're running on. Railway does this by detecting the `env.$PORT` variable that the service is binding. For simplicity's sake, these two services will be connected over their public domain so you can get a handle on the basics. In practice, you may need to configure your networking a bit differently. You can [read more about networking in the docs](https://docs.railway.com/guides/public-networking).

Let's add public domains to both services.

- Click on the service and then open the Settings tab.

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269032/docs/tutorials/monorepo/service_settings_networking_ckrss1.png"
alt="Screenshot showing the service settings"
layout="responsive"
width={1381} height={760} quality={100} />

- Click on `Generate Domain`. Railway will ✨automagically assign the port based on the deployed service.

- Do these steps for both services, so that they both have public domains.

**Notes:**

- **Setting a Custom `$PORT`:** Adding the domain after the service is deployed allows Railway to detect the bound `env.$PORT`. You could instead decide to manually set the `$PORT` variable on the Variables tab, and set the Domain to use that custom port instead.

## 7. Variable setup

For the example monorepo the Frontend service needs a `VITE_BACKEND_HOST` variable, and the backend needs an `ALLOWED_ORIGINS` variable.

Let's add the Frontend variable first.

- Click on Frontend service, then the `Variables` tab

- Add the required variable -

      ```plaintext
      VITE_BACKEND_HOST=${{Backend.RAILWAY_PUBLIC_DOMAIN}}
      ```

  It should look like this once added:

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269049/docs/tutorials/monorepo/adding_frontend_variables_jqn4rf.png"
alt="Screenshot showing the frontend service variables"
layout="responsive"
width={1386} height={760} quality={100} />

Now let's add the Backend variable.

- Click on the Backend service, then the `Variables` tab

- Add the required variable -

  ```plaintext
  ALLOWED_ORIGINS=${{Frontend.RAILWAY_PUBLIC_DOMAIN}}
  ```

It should look like this once added:

<Image src="https://res.cloudinary.com/railway/image/upload/v1721269042/docs/tutorials/monorepo/adding_backend_variables_aplgej.png"
alt="Screenshot showing the backend service variables"
layout="responsive"
width={1386} height={760} quality={100} />

- Click the `Deploy` button or `⇧ Enter` to save these changes.

- Your services should be deployed and available now! Click on your frontend service on the Deployment tab and you can click your domain to see the webapp.

**Notes:**

- The variables used here are reference variables, learn more about them [here](https://docs.railway.com/guides/variables#referencing-another-services-variable).

- Both the Frontend and Backend variables reference each other's public domains. The `RAILWAY_PUBLIC_DOMAIN` variable will be automatically updated whenever you deploy or re-deploy a service.

- See a list of additional variables [here](https://docs.railway.com/reference/variables#railway-provided-variables).

## Conclusion

Congratulations! You have setup a project, setup services, added variables and deployed your monorepo project to Railway. The Frontend service should be accessible on its public domain to access the deployed website.

Learn how to deploy a monorepo to Railway.

Deploying a Monorepo to Railway

[Django](https://www.djangoproject.com) is a powerful Python web framework that simplifies web development by providing ready-to-use tools for rapid development and clean design.

It’s free, open-source, and comes with a range of features to streamline tasks like authentication, routing, and database management, so developers can focus on building their applications without handling everything from scratch.

## Create a Django app

**Note:** If you already have a Django app locally or on GitHub, you can skip this step and go straight to the [Deploy Django App on Railway](#deploy-django-app-on-railway).

To create a new Django app, ensure that you have [Python](https://www.python.org/downloads/) and [Django](https://docs.djangoproject.com/en/5.1/intro/install/) installed on your machine.

Follow the steps below to set up the project in a directory.

Create a virtual environment

```bash
python -m venv env
```

Activate the virtual environment

```bash
source env/bin/activate
```

**Note:** For windows developers, run it as `env\Scripts\activate` in your terminal.

Install Django

```bash
python -m pip install django
```

Once everything is set up, run the following command in your terminal to provision a new Django project:

```bash
django-admin startproject liftoff
```

This command will create a new Django project named `liftoff`.

Next, `cd` into the directory and run `python manage.py runserver` to start your project.

Open your browser and go to `http://127.0.0.1:8000` to see the project. You'll see the Django welcome page with a "The install worked successfully! Congratulations!" paragraph.

**Note:** You'll see a red notice about unapplied migration(s). You can ignore them for now. You'll run them when you deploy the project.

Now that your app is running locally, let’s move on to make some changes and install some dependencies before deployment.

## Configure database, static files & dependencies

1. Install the following packages within the `liftoff` directory, where you can see the `manage.py` file.

```bash
python -m pip install gunicorn whitenoise psycopg[binary,pool]
```

[whitenoise](https://whitenoise.readthedocs.io/en/stable/index.html) is a Python package for serving static files directly from your web app. It serves compressed content and sets far-future cache headers on content that won't change.

[gunicorn](https://gunicorn.org) is a production ready web server.

[pyscog](https://www.psycopg.org/psycopg3/docs) is python package that allows Django work with Postgresql.

2. Import the `os` module:

Open the `liftoff/settings.py` file located in the inner `liftoff` directory (the one containing the main project settings).

At the top of the file, add the following line to import the `os` module, placing it just before the `Path` import:

```python
import os
from pathlib import Path
```

3. Configure the database and run migrations:

A fresh Django project uses SQLite by default, but you need to switch to PostgreSQL.

Create a database named `liftoff_dev` in your local Postgres instance.

Open the `liftoff/settings.py` file. In the Database section, replace the existing configuration with:

```python

# Database
# https://docs.djangoproject.com/en/5.1/ref/settings/#databases

# Set default values for the environment variables if they’re not already set
os.environ.setdefault("PGDATABASE", "liftoff_dev")
os.environ.setdefault("PGUSER", "username")
os.environ.setdefault("PGPASSWORD", "")
os.environ.setdefault("PGHOST", "localhost")
os.environ.setdefault("PGPORT", "5432")

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': os.environ["PGDATABASE"],
        'USER': os.environ["PGUSER"],
        'PASSWORD': os.environ["PGPASSWORD"],
        'HOST': os.environ["PGHOST"],
        'PORT': os.environ["PGPORT"],
    }
}
```

Replace the values of `PGUSER`, `PGPASSWORD` with your local credentials.

Run `python manage.py migrate` in your terminal to apply the database migrations. Once it completes successfully, check your database. You should see the auth and other Django tables created.

4. Static files configuration:

Configure Django to serve static files using [WhiteNoise](https://whitenoise.readthedocs.io/en/stable/index.html).

Open `liftoff/settings.py` and configure the static files settings:

```python
STATIC_URL = 'static/'

STATIC_ROOT = os.path.join(BASE_DIR, "staticfiles")
STATICFILES_DIRS = [os.path.join(BASE_DIR, "static")]
```

Add the WhiteNoise middleware in the **MIDDLEWARE** section, just below the [security middleware](https://docs.djangoproject.com/en/5.1/ref/middleware/#module-django.middleware.security):

```python
MIDDLEWARE = [
    'django.middleware.security.SecurityMiddleware',
    'whitenoise.middleware.WhiteNoiseMiddleware',
    'django.contrib.sessions.middleware.SessionMiddleware',
    'django.middleware.common.CommonMiddleware',
    'django.middleware.csrf.CsrfViewMiddleware',
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    'django.contrib.messages.middleware.MessageMiddleware',
    'django.middleware.clickjacking.XFrameOptionsMiddleware',
]
```

5. Update `ALLOWED_HOSTS` settings:

```python
ALLOWED_HOSTS = ["*"]
```

This setting represents the list of all the host/domain names your Django project can serve.

6. Create a **static** folder:

Inside your `liftoff` directory, create a static folder where all static assets will reside.

7. Create a `requirements.txt` file:

To track all the dependencies for deployment, create a `requirements.txt` file:

```bash
pip freeze > requirements.txt
```

**Note:** It's only safe to run the command above in a virtual environment, else it will freeze all python packages installed on your system.

With these changes, your Django app is now ready to be deployed to Railway!

## Deploy Django app on Railway

Railway offers multiple ways to deploy your Django app, depending on your setup and preference. Choose any of the following methods:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).

## One-click deploy from a template

If you’re looking for the fastest way to get started, the one-click deploy option is ideal. It sets up a Django app along with a Postgres database.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/GB6Eki)

After deploying, it is recommended that you [eject from the template](/templates/deploy#eject-from-template-repository) to create a copy of the repository under your own GitHub account. This will give you full control over the source code and project.

## Deploy from the CLI

To deploy the Django app using the Railway CLI, please follow the steps:

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Django app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.

   **Note:** You'll encounter an error about the PGDATABASE environment not set. Don't worry, you'll fix that in the next steps.

4. **Add a Database Service**:
   - Run `railway add`.
   - Select `PostgreSQL` by pressing space and hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
5. **Configure Environment Variables**:
   - Go to your app service <a href="/overview/the-basics#service-variables">**Variables**</a> section and add the following:
     - `PGDATABASE`: Set the value to `${{Postgres.PGDATABASE}}` (this references the Postgres database name). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `PGUSER`: Set the value to `${{Postgres.PGUSER}}`
     - `PGPASSWORD`: Set the value to `${{Postgres.PGPASSWORD}}`
     - `PGHOST`: Set the value to `${{Postgres.PGHOST}}`
     - `PGPORT`: Set the value to `${{Postgres.PGPORT}}`
   - Use the **Raw Editor** to add any other required environment variables in one go.
6. **Redeploy the App Service**:
   - Click **Deploy** on the app service on the Railway dashboard to apply your changes.
7. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
8. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/v1729121823/docs/quick-start/django_app.png"
alt="screenshot of the deployed Django project"
layout="responsive"
width={2783} height={2135} quality={100} />

## Deploy from a GitHub repo

To deploy the Django app to Railway, start by pushing the app to a GitHub repo. Once that’s set up, follow the steps below to complete the deployment process.

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables**:

   - Click **Add Variables** and configure all the necessary environment variables for your app.
     - `PGDATABASE`: Set the value to `${{Postgres.PGDATABASE}}` (this references the Postgres database name). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `PGUSER`: Set the value to `${{Postgres.PGUSER}}`
     - `PGPASSWORD`: Set the value to `${{Postgres.PGPASSWORD}}`
     - `PGHOST`: Set the value to `${{Postgres.PGHOST}}`
     - `PGPORT`: Set the value to `${{Postgres.PGPORT}}`

   **Note:** The Postgres Database service isn't set up yet. You'll add that soon.

4. **Add a Database Service**:
   - Right-click on the Railway project canvas or click the **Create** button.
   - Select **Database**.
   - Select **Add PostgreSQL** from the available databases.
     - This will create and deploy a new Postgres database service for your project.
5. **Deploy the App**:
   - Click **Deploy** to start the deployment process and apply all changes.
   - Once deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
6. **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 Django app](https://nixpacks.com/docs/providers/python).

7. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Django apps effortlessly!

**Note:** The next step shows how to configure and run your Django app along with Celery and Celery beat.

## Set up database, migrations, celery beat and celery

This setup deploys your Django app on Railway, ensuring that your database, scheduled tasks (crons)--Celery Beat, and queue workers (Celery) are all fully operational.

The deployment structure follows a "majestic monolith" architecture, where the entire Django app is managed as a single codebase but split into four separate services on Railway:

- **App Service**: Handles HTTP requests and user interactions.
- **Cron Service**: Manages scheduled tasks (e.g., sending emails or running reports) using Celery Beat.
- **Worker Service**: Processes background jobs from the queue using Celery.
- **Database Service**: Stores and retrieves your application's data.

<Image src="https://res.cloudinary.com/railway/image/upload/v1731604331/docs/quick-start/deployed_django_app_architecture.png"
alt="screenshot of the deploy architecture of the Django app"
layout="responsive"
width={3237} height={1951} quality={100} />
_My Monolith Django app_

**Note:** This guide follows the assumption that you have installed Celery and Celery Beat in your app, the broker uses Redis and you already have a Postgres database service provisioned for your app as shown earlier.

Please follow these steps to get it setup on Railway:

1. Create a Redis Database service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a> by clicking the **Create** button. Then select **Database** and choose **Add Redis**.
   - Click on **Deploy**.
2. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a> by clicking the **Create** button. Then select **Empty service**.
   - Name the service **App Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a> to configure it.
     - **Note:** If you followed the guide from the beginning, simply rename the existing service to **App Service**.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Go to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables required for the Django app especially the ones listed below.
     - `REDIS_URL`: Set the value to `${{Postgres.REDIS_URL}}`
     - `PGUSER`: Set the value to `${{Postgres.PGUSER}}`
     - `PGPASSWORD`: Set the value to `${{Postgres.PGPASSWORD}}`
     - `PGHOST`: Set the value to `${{Postgres.PGHOST}}`
     - `PGPORT`: Set the value to `${{Postgres.PGPORT}}`
     - `PGDATABASE`: Set the value to `${{Postgres.PGDATABASE}}` (this references the Postgres database name). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
   - Click **Deploy**.
3. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a> by clicking the **Create** button. Then select **Empty service**.
   - Name the service **Cron Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Add `celery -A liftoff beat -l info --concurrency=3` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.
     - _Note:_ `liftoff` is the name of the app. You can find the app name in your Django project’s main folder, typically in the directory containing `settings.py`.
     - The `--concurrency=3` option here means it can process up to 3 tasks in parallel. You can adjust the [concurrency level](https://docs.celeryq.dev/en/latest/userguide/workers.html#concurrency) based on your system resources. The higher the level, the more memory and resources it consumes.
   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables especially those highlighted already in step 2.
   - Click **Deploy**.
4. Create a new service again on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a>.
   - Name the service **Worker Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Add `celery -A liftoff worker -l info --concurrency=3` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.
     - _Note:_ `liftoff` is the name of the app. You can find the app name in your Django project’s main folder, typically in the directory containing `settings.py`.
     - The `--concurrency=3` option here means it can process up to 3 tasks in parallel. You can adjust the [concurrency level](https://docs.celeryq.dev/en/latest/userguide/workers.html#concurrency) based on your system resources. The higher the level, the more memory and resources it consumes.
   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables especially those highlighted already in step 2.
   - Click **Deploy**.

At this point, you should have all services deployed and connected to the Postgres and Redis Database service:

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731604331/docs/quick-start/deployed_django_app_architecture.png"
alt="screenshot of the deploy architecture of the Django app"
layout="responsive"
width={3237} height={1951} quality={100} />

- **Cron Service**: This service should run Celery Beat Scheduler to manage scheduled tasks.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731605926/docs/quick-start/django_cron_service.png"
alt="screenshot of the cron service of the Django app"
layout="responsive"
width={2766} height={2056} quality={100} />

- **Worker Service**: This service should be running Celery and ready to process jobs from the queue.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731605981/docs/quick-start/django_worker_service.png"
alt="screenshot of the worker service of the Django app"
layout="responsive"

width={2752} height={2094} quality={100} />

- **App Service**: This service should be running and is the only one that should have a public domain, allowing users to access your application.

**Note:** There is a [community template](https://railway.com/template/yZDfUu) available that demonstrates this deployment approach. You can easily deploy this template and then connect it to your own GitHub repository for your application.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Python Django app to Railway with this step-by-step guide. It covers quick setup, database integration, private networking, Celery, one-click deploys and other deployment strategies.

Deploy a Django App

[Express](https://expressjs.com) is a fast and flexible web application framework for Node.js that provides a simple and minimalistic approach to building web servers and APIs. It is known for its speed and unopinionated nature, allowing developers to structure their applications as they see fit while offering powerful features.

This guide covers how to deploy an Express app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create an Express app!

## Create an Express app

**Note:** If you already have an Express app locally or on GitHub, you can skip this step and go straight to the [Deploy Express App to Railway](#deploy-the-express-app-to-railway).

To create a new Express app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Create a directory, `helloworld`, and `cd` into it.

Run the following command in your terminal to create a new Express app within the `helloworld` directory:

```bash
npx express-generator --view=pug
```

A new Express app will be provisioned for you in the `helloworld` directory using [pug](https://pugjs.org/api/getting-started.html) as the view engine.

### Run the Express app locally

Run `npm install` to install all the dependencies.

Next, start the app by running the following command:

```bash
npm start
```

Launch your browser and navigate to `http://localhost:3000` to view the app.

If you'd prefer to run the app on a different port, simply use the command `PORT=8080 npm start` in the terminal.

Afterward, you can access the app at `http://localhost:8080`.

### Add and configure database

**Note:** This app uses Postgres. If you don’t have it installed locally, you can either [install it](https://www.postgresql.org/download) or use a different Node.js database package of your choice.

1. Create a database named `expresshelloworld_dev`.

2. Install the [pg-promise](https://www.npmjs.com/package/pg-promise) package:

```bash
npm i pg-promise
```

3. Open the `routes/index.js` file and modify the content to the code below:

```js
const express = require("express");
const pgp = require("pg-promise")();
const db = pgp(
  "postgres://username:password@127.0.0.1:5432/expresshelloworld_dev",
);
const router = express.Router();

/* GET home page. */
router.get("/", function (req, res, next) {
  db.one("SELECT NOW()")
    .then(function (data) {
      // Render the page only after receiving the data
      res.render("index", {
        title: "Hello World, Railway!",
        timeFromDB: data.now,
      });
    })
    .catch(function (error) {
      console.error("ERROR:", error);
      // If there’s an error, send a 500 response and do not call res.render
      res.status(500).send("Error querying the database");
    });
});

module.exports = router;
```

The code above sets up a simple Express app with a route handler for the home page. It uses the `pg-promise` library to connect to a Postgres database and runs a query to fetch the current time from the database using `SELECT NOW()`. Upon receiving the data, it renders the index view with the fetched time, sending it to the client along with a title.

If an error occurs during the database query, the code catches the error, logs it, and sends a 500 status response to the client, indicating that there was an issue querying the database.

The page is only rendered after successfully receiving the database response to ensure proper handling of the data.

4. Open the `views/index.pug` file, and update it to display the `timeFromDB` value on the page.

```pug
extends layout 

block content 
  h1= title 
  p Welcome to #{title} 
  p This is the time retrieved from the database: 
  p #{timeFromDB}
```

5. Run the app again to see your changes in action!

### Prepare Express app for deployment

In the `routes/index.js` file, replace the hardcoded Postgres database URL with an environment variable:

```js
...
const db = pgp(process.env.DATABASE_URL);
...
```

This allows the app to dynamically pull the correct database configuration from Railway during deployment.

## Deploy the Express app to Railway

Railway offers multiple ways to deploy your Express app, depending on your setup and preference.

### One-click deploy from a template

If you’re looking for the fastest way to get started with Express, Pug and connected to a Postgres database, the one-click deploy option is ideal.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/BC51z6)

For Express API, here's another template you can begin with:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/Y6zLKF)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=express" target="_blank">variety of Express app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Express app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:

   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter `DATABASE_URL=${{Postgres.DATABASE_URL}}`.
     - The value, `${{Postgres.DATABASE_URL}}`, references the URL of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.

5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731505753/express_on_railway.png"
alt="screenshot of the deployed Express service"
layout="responsive"
width={2194} height={1652} quality={100} />

### Deploy from a GitHub repo

To deploy an Express app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it's a Node.js app via Railpack](https://railpack.com/languages/node).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the Express app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node official image
   # https://hub.docker.com/_/node
   FROM node:lts

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image
   COPY . ./

   # Install packages
   RUN npm ci

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Express apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy an Express app to Railway with one-click templates, GitHub, CLI, or Dockerfile. This guide covers setup, private networking, database integration, and deployment strategies.

Deploy an Express App

FastAPI is a modern, fast (high-performance), web framework for building APIs with Python based on standard Python type hints.

This guide covers how to deploy a FastAPI app on Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/-NvLj4)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=fastapi" target="_blank">variety of FastAPI app templates</a> created by the community.

## Deploy from a GitHub repo

To deploy a FastAPI app on Railway directly from GitHub, follow the steps below:

1. Fork the basic <a href="https://github.com/railwayapp-templates/fastapi" target="_blank">FastAPI GitHub repo</a>.
   - If you already have a GitHub repo you want to deploy, you can skip this step.
2. Create a <a href="https://railway.com/new" target="_blank">New Project.</a>
3. Click **Deploy from GitHub repo**.
4. Select the `fastapi` or your own GitHub repo.
   - Railway requires a valid GitHub account to be linked. If your Railway account isn't associated with one, you will be prompted to link it.
5. Click **Deploy Now**.

Once the deployment is successful, a Railway [service](/services) will be created for you. By default, this service will not be publicly accessible.

To set up a publicly accessible URL for the service, navigate to the **Networking** section in the [Settings](/overview/the-basics#service-settings) tab of your new service and click on [Generate Domain](/networking/public-networking#railway-provided-domain).

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727418781/docs/languages-and-frameworks/CleanShot_2024-09-27_at_07.31.37_2x_m3zaxx.png"
alt="screenshot of the deployed fastapi service showing a hello world API response on a browser"
layout="responsive"
width={2435} height={919} quality={100} />

The FastAPI app is run via a <a href="https://hypercorn.readthedocs.io/en/latest/" target="_blank">Hypercorn server</a> as defined by the `startCommand` in the <a href="https://github.com/railwayapp-templates/fastapi/blob/main/railway.json" target="_blank">railway.json</a> file in the GitHub repository.

Railway makes it easy to define deployment configurations for your services directly in your project using a <a href="/guides/config-as-code" target="_blank">railway.toml or railway.json file</a>, alongside your code.

## Deploy from the CLI

1. <a href="/guides/cli#installing-the-cli" target="_blank">Install</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate with the CLI.</a>
2. Clone the forked <a href="https://github.com/railwayapp-templates/fastapi" target="_blank">fastapi GitHub repo</a> and `cd` into the directory.
   - You can skip this step if you already have an app directory or repo on your machine that you want to deploy.
3. Run `railway init` within the app directory to create a new project.
4. Run `railway up` to deploy.
   - The CLI will now scan, compress and upload your fastapi app files to Railway's backend for deployment.

## Use a Dockerfile

**Note:** If you already have an app directory or repo on your machine that you want to deploy, you can skip the first two steps.

1. Clone the forked `fastapi` repo and `cd` into the directory.
2. Delete the `railway.json` file.
3. Create a `Dockerfile` in the `fastapi` or app's root directory.
4. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Python 3 alpine official image
   # https://hub.docker.com/_/python
   FROM python:3-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . .

   # Install project dependencies
   RUN pip install --no-cache-dir -r requirements.txt

   # Run the web service on container startup.
   CMD ["hypercorn", "main:app", "--bind", "::"]
   ```

5. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)
- [Running a Cron Job](/cron-jobs)

Learn how to deploy a FastAPI app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a FastAPI App

Fastify is a high-performance, low-overhead web framework for Node.js, designed to deliver an exceptional developer experience.

This guide covers how to deploy a Fastify app on Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/ZZ50Bj)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=fastify" target="_blank">variety of Fastify app templates</a> created by the community.

## Deploy from a GitHub repo

To deploy a Fastify app on Railway directly from GitHub, follow the steps below:

1. Fork the basic <a href="https://github.com/railwayapp-templates/fastify" target="_blank">fastify GitHub repo</a>.
   - If you already have a GitHub repo you want to deploy, you can skip this step.
2. Create a <a href="https://railway.com/new" target="_blank">New Project.</a>
3. Click **Deploy from GitHub repo**.
4. Select the `fastify` repo or your own GitHub repo.
   - Railway requires a valid GitHub account to be linked. If your Railway account isn't associated with one, you will be prompted to link it.
5. Click **Deploy Now**.

Once the deployment is successful, a Railway [service](/services) will be created for you. By default, this service will not be publicly accessible.

To set up a publicly accessible URL for the service, navigate to the **Networking** section in the [Settings](/overview/the-basics#service-settings) tab of your new service and click on [Generate Domain](/networking/public-networking#railway-provided-domain).

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727377689/docs/languages-and-frameworks/fastifyhelloworld_xbkrry.png"
alt="screenshot of new project menu with deploy from github selected"
layout="responsive"
width={2447} height={1029} quality={100} />

**Note:** Railway requires that Fastify's `.listen` method for the `host` be set to `::`. This allows the app to be available over the <a href="/guides/public-networking" target="_blank">public</a> and <a href="/guides/private-networking" target="_blank">private network</a>.
You can find this in the <a href="https://github.com/railwayapp-templates/fastify/blob/main/src/app.ts" target="_blank">sample Fastify GitHub repo</a>.

If you don’t set it correctly, you may encounter a 502 error page.

## Deploy from the CLI

1. <a href="/guides/cli#installing-the-cli" target="_blank">Install</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate with the CLI.</a>
2. Clone the forked <a href="https://github.com/railwayapp-templates/fastify" target="_blank">fastify GitHub repo</a> and `cd` into the directory.
   - You can skip this step if you already have an app directory or repo on your machine that you want to deploy.
3. Run `railway init` within the app directory to create a new project.
4. Run `railway up` to deploy.
   - The CLI will now scan, compress and upload your fastify app files to Railway's backend for deployment.

## Use a Dockerfile

1. Clone the forked `fastify` repo and `cd` into the directory.
   - You can skip this step if you already have an app directory or repo on your machine that you want to deploy.
2. Create a `Dockerfile` in the `fastify` or app's root directory.
3. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node.js 18 alpine official image
   # https://hub.docker.com/_/node
   FROM node:18-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . .

   # Install project dependencies
   RUN npm ci

   # Run the web service on container startup.
   CMD ["npm", "start"]
   ```

4. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a CDN using Amazon CloudFront to your Fastify app](/guides/add-a-cdn-using-cloudfront)
- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Fastify app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Fastify App

[Flask](https://flask.palletsprojects.com/en/stable) is a Python micro framework for building web applications.

This guide covers how to deploy a Flask app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Flask app!

## Create a Flask app

**Note:** If you already have a Flask app locally or on GitHub, you can skip this step and go straight to the [Deploy Flask App to Railway](#deploy-flask-app-to-railway).

To create a new Flask app, ensure that you have [Python](https://www.python.org/downloads) and [Flask](https://flask.palletsprojects.com/en/stable/installation/#install-flask) installed on your machine.

Follow the steps blow to set up the project in a directory.

Create a project directory and `cd` into it.

```bash
mkdir flaskproject
cd flaskproject
```

Create a virtual environment

```bash
python -m venv env
```

Activate the virtual environment

```bash
source env/bin/activate
```

**Note:** For windows developers, run it as `env\Scripts\activate` in your terminal.

Install Flask

```bash
python -m pip install flask
```

Now create a new file, `helloworld.py` in the `flaskproject` directory. Add the following content to it:

```python
import os
from flask import Flask

app = Flask(__name__)


@app.route('/')
def hello():
    return 'Hello world, welcome to Railway!'
```

1. `from flask import Flask`:
   - This line imports the Flask class from the Flask framework, which is used to create and manage a web application.
2. `app = Flask(__name__)`:
   - This line creates an instance of the Flask class and assigns it to the app variable.
   - The `__name__` argument helps Flask identify the location of the application. It's useful for determining resource paths and error reporting.
3. `@app.route('/')`:
   - The `@app.route('/')` decorator sets up a URL route for the app. When the root URL `(/)` is accessed, Flask will execute the function immediately below this decorator.
4. `def hello():`
   - The `hello` function returns a plain text message, _"Hello world, welcome to Railway!"_, which is displayed in the browser when the root URL of the app is accessed.

### Run the Flask app locally

To run the application, use the `flask` command.

```bash
flask --app helloworld run
```

Open your browser and go to `http://127.0.0.1:5000` to see the app running with a local development server.

### Prepare the Flask app for deployment

1. Run the following command to install a production web server, [gunicorn](https://gunicorn.org):

```bash
pip install gunicorn
```

Next, run the following command to serve the app with gunicorn:

```bash
gunicorn main:app
```

2. Open your browser and go to `http://127.0.0.1:8000` to see the app running with a production server.

Create a `requirements.txt` file to store the dependencies of the packages needed to run the app.

```bash
pip freeze > requirements.txt
```

**Note:** It's only safe to run the command above in a virtual environment, else it will freeze all python packages installed on your system.

3. Finally, create a `nixpacks.toml` file in the root directory of the app. Add the following content to it:

```toml
# nixpacks.toml

[start]
cmd = "gunicorn main:app"
```

This setup instructs Railway to use Gunicorn as the server to start the application.

**Note:** The [nixpacks.toml file](https://nixpacks.com/docs/configuration/file) is a configuration file used by Nixpacks, a build system developed and used by Railway, to set up and deploy applications.

In this file, you can specify the instructions for various build and deployment phases, along with environment variables and package dependencies.

With these changes, your Flask app is now ready to be deployed to Railway!

## Deploy Flask app to Railway

Railway offers multiple ways to deploy your Flask app, depending on your setup and preference. Choose any of the following methods:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/zUcpux)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=flask" target="_blank">variety of Flask app templates</a> created by the community.

## Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Flask app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - 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**](/observability/logs#build--deploy-panel) to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1730473731/docs/quick-start/flask_app_on_railway.png"
alt="screenshot of the deployed Flask service"
layout="responsive"
width={2164} height={1814} quality={100} />

## Deploy from a GitHub repo

To deploy a Flask app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
4. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it's a Python app via Railpack](https://railpack.com/languages/python).

5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

## Use a Dockerfile

1. Create a `Dockerfile` in the app's root directory.
2. Add the content below to the `Dockerfile`:

   ```docker
   # Use the Python 3 official image
   # https://hub.docker.com/_/python
   FROM python:3

   # Run in unbuffered mode
   ENV PYTHONUNBUFFERED=1

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . ./

   # Install project dependencies
   RUN pip install --no-cache-dir -r requirements.txt

   # Run the web service on container startup.
   CMD ["gunicorn", "main:app"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)
- [Running a Cron Job](/cron-jobs)

Learn how to deploy a Flask app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Flask App

The Railway Team and community provide content, like tutorials and blogs, on how to make the most out of Railway.

Explore the pages in this section to learn or get inspired!

Also checkout the [Quick Start Tutorial](/quick-start) to deploy an app in minutes.

### Contributing

Pull requests are welcome. If you make a quality tutorial for other Railway users, we would really love to include it!

If there is a tutorial you hope to see, please create a post in <a href="https://station.railway.com/" target="_blank">Forums</a>!

Discover tutorials to help you get the most out of Railway.

Welcome to Railway Tutorials!

[Gin](https://gin-gonic.com) is a high-performance web framework for Go (Golang) that provides a martini-like API while being significantly faster (up to 40 times) due to its use of `httprouter`. It's designed for developers seeking both speed and productivity.

This guide covers how to deploy a Gin app on Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/dTvvSf)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=gin" target="_blank">variety of Gin app templates</a> created by the community.

## Deploy from a GitHub repo

To deploy a Gin app on Railway directly from GitHub, follow the steps below:

1. Fork the basic <a href="https://github.com/railwayapp-templates/gin" target="_blank">Gin GitHub repo</a>.
   - If you already have a GitHub repo you want to deploy, you can skip this step.
2. Create a <a href="https://railway.com/new" target="_blank">New Project.</a>
3. Click **Deploy from GitHub repo**.
4. Select the `gin` or your own GitHub repo.
   - Railway requires a valid GitHub account to be linked. If your Railway account isn't associated with one, you will be prompted to link it.
5. Click **Deploy Now**.

Once the deployment is successful, a Railway [service](/services) will be created for you. By default, this service will not be publicly accessible.

To set up a publicly accessible URL for the service, navigate to the **Networking** section in the [Settings](/overview/the-basics#service-settings) tab of your new service and click on [Generate Domain](/networking/public-networking#railway-provided-domain).

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727691646/docs/languages-and-frameworks/gin-production_nvsmvf.png"
alt="screenshot of the deployed gin service showing a hello world API response on a browser"
layout="responsive"
width={2661} height={1019} quality={100} />

## Deploy from the CLI

1. <a href="/guides/cli#installing-the-cli" target="_blank">Install</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate with the CLI.</a>
2. Clone the forked <a href="https://github.com/railwayapp-templates/gin" target="_blank">gin GitHub repo</a> and `cd` into the directory.
   - You can skip this step if you already have an app directory or repo on your machine that you want to deploy.
3. Run `railway init` within the app directory to create a new project.
4. Run `railway up` to deploy.
   - The CLI will now scan, compress and upload your gin app files to Railway's backend for deployment.

## Use a Dockerfile

1. Clone the forked `gin` repo and `cd` into the directory.
   - You can skip this step if you already have an app directory or repo on your machine that you want to deploy.
2. Create a `Dockerfile` in the `gin` or app's root directory.
3. Add the content below to the `Dockerfile`:

   ```docker
   # Use the Go 1.23 alpine official image
   # https://hub.docker.com/_/golang
   FROM golang:1.23-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy go mod and sum files
   COPY go.mod go.sum ./

   # Copy local code to the container image.
   COPY . ./

   # Install project dependencies
   RUN go mod download

   # Build the app
   RUN go build -o app

   # Run the service on container startup.
   ENTRYPOINT ["./app"]
   ```

4. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)
- [Running a Cron Job](/cron-jobs)

Learn how to deploy a Gin app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Gin App

[Github Actions](https://github.com/features/actions) come with a pretty neat set of features to automate your workflows. This post talks about using Github Actions to run post-deploy actions.

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 the Railway [Discord](https://discord.gg/railway) and [Slack](/platform/support#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, you'll be using the `deployment_status` event to trigger your action. This event is triggered when a deployment status changes, and you'll be using the `success` state to trigger your action.

Make a new file in your repository called `.github/workflows/post-deploy.yml` and add the following -

```yaml
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"
```

Check out the contents of `github.event` to build your own conditions.

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](https://discord.gg/railway), [Slack](/platform/support#slack) or the [Central Station](https://station.railway.com). Happy coding!

Learn how to use GitHub Actions to run post-deployment commands.

GitHub Actions Post-Deploy

[Github Actions](https://github.com/features/actions) come with a pretty neat set of features to automate your workflows. This post talks about using Github Actions alongside the [Railway CLI](https://github.com/railwayapp/cli) to create specific environments for any PR that is created, alongside closing it whenever it is closed/merged.

This can be useful if you need to create a branch on a [Neon](https://neon.tech) 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 -

```yaml
# 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
  # WORKSPACE_ID: "" if you are linking to a project in a workspace, 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 }} # --workspace ${{ env.WORKSPACE_ID }} # uncomment this if you are linking to a workspace 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 }}" --service-config ${{ env.SERVICE_ID }} "source.branch" "${{ github.head_ref }}"

  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 }} # --workspace ${{ env.WORKSPACE_ID }} # uncomment this if you are linking to a workspace project
      - name: Delete Railway Environment for PR
        run: railway environment delete pr-${{ github.event.pull_request.number }} || true
```

**Note:** If you are using a project in a workspace, you need to ensure that the token specified is scoped to your account, not just the 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](https://discord.gg/railway), [Slack](/platform/support#slack) or the [Central Station](https://station.railway.com). Happy coding!

Learn how to use the CLI in a GitHub Action to create environments for PRs

GitHub Actions PR Environment

<Image src="https://res.cloudinary.com/railway/image/upload/v1746477484/docs/github-actions/j7y3ibttsmfepak5ohcb.png
"
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](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on Railway is an excellent way to run your own CI infrastructure because you only [pay for what you use](/pricing/plans). 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](/deployments/scaling#horizontal-scaling-with-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](/deployments/scaling#horizontal-scaling-with-replicas) to serve bigger Actions workloads.
1. Best Practices for configuring your self-hosted runners on Railway.

**Quickstart:** [Deploy your self-hosted Runners with the Railway template](https://railway.com/new/template/pXId5Q?teamId=d546a817-7743-4892-b03a-f5a75df596f9).

## Deploy a GitHub self-hosted runner on Railway

1. Navigate to the [GitHub Actions self-hosted Runner Template](https://railway.com/new/template/pXId5Q?teamId=d546a817-7743-4892-b03a-f5a75df596f9). You'll notice the template requires an `ACCESS_TOKEN`. This token, along with your `RUNNER_SCOPE` will determine _where_ your 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`. This sets up your self-hosted runners to register with a GitHub Organization, so any repositories within your 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](https://github.com/myoung34/docker-github-actions-runner?tab=readme-ov-file#environment-variables).

## Setup a GitHub access_token

For this guide, you will create a new [GitHub Fine-Grained Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#fine-grained-personal-access-tokens). These are modern personal access tokens that obey the [principle of least privilege](https://en.wikipedia.org/wiki/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`.

<Image src="https://res.cloudinary.com/railway/image/upload/v1746477254/docs/github-actions/g9uzz9dksi80zsazlohk.png
"
alt="screenshot of a GitHub Fine Grained Access Token"
layout="responsive"
width={1131} height={702} quality={100} />

1. Create a new fine-grained personal access token. [Navigate to your Settings -> Developer Settings -> Personal Access Token -> Fine-grained tokens -> Generate New Token](https://github.com/settings/personal-access-tokens)
1. Set the Resource owner as your Organization. Alternatively, if you are using a `ent` `RUNNER_SCOPE`, select your Enterprise.
1. Set Expiration
1. Under Permissions, Select Organization Permissions -> Self Hosted Runners -> Read and Write (If Enterprise, select Enterprise instead).
1. Click Generate. Save your `ACCESS_TOKEN` in a safe place! You won't see it again. (Save it in a Password Vault as an API Key!)
1. DONE. You don't need any other permissions!

## Scaling up your Railway self hosted runners

<Image src="https://res.cloudinary.com/railway/image/upload/v1746476747/docs/github-actions/edwass7m7pn35zx8xqw9.png
"
alt="screenshot of scaling up your Railway self hosted Runners with Railway Replicas"
layout="responsive"
width={1328} height={690} quality={100} />

1. Navigate to the Settings tab of your Service to the Region area.
1. Change the number next to your region from `1` to your desired number of replicas.
1. Click Deploy.
1. Done! Your new replicas will automatically spin up and register themselves with GitHub.

## View your registered self hosted runners

<Image src="https://res.cloudinary.com/railway/image/upload/v1746477028/docs/github-actions/g0twzm5fhqrgjhtltrec.png
"
alt="screenshot of viewing your Registered self hosted runners"
layout="responsive"
width={1271} height={776} quality={100} />

You can view all your runners by navigating to your organization's Actions -> Runners page at https://github.com/organizations/(your-organization-name)/settings/actions/runners?page=1

## Routing actions jobs

You can route jobs by simply changing the `LABELS` variable. By default, we include the `railway` label on runners you make through the [Template](https://railway.com/new/template/pXId5Q?teamId=d546a817-7743-4892-b03a-f5a75df596f9). `LABELS` is a comma (no spaces) delimited list of all the labels you want to appear on that runner. This enables you to [route jobs](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow#using-custom-labels-to-route-jobs) with the specificity that your workflows need, while still allowing you to make runners available for your entire Organization.

## Setting up GitHub actions workflows for pull requests

GitHub Actions uses workflow files located in `.github/workflows/<workflow>.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/<workflow>.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.

```yml
name: eslint check

on:
  pull_request:
    branches:
      - main

permissions:
  contents: read

jobs:
  build:
    name: Check
    runs-on: [self-hosted, railway]

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Install bun
        uses: oven-sh/setup-bun@v2

      - name: Set up Node
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Cache Files
        uses: actions/cache@v4
        with:
          path: |
            ~/.bun/install/cache
            path: ${{ github.workspace }}/**/node_modules
            path: ${{ github.workspace }}/**/.nuxt
          key: ${{ runner.os }}-bun-${{ hashFiles('**/bun.lock', 'nuxt.config.ts', 'app.config.ts', 'app.vue') }}

      - name: Install packages
        run: bun install --prefer-offline

      - name: Lint
        run: bun run lint
```

## 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](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) will make your runners robust and prevent any concerns about your build infrastructure. GitHub's [detailed guide](https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions) can help you secure secrets, authentication, auditing, and managing your runners. Similarly [dduzgun-security](https://github.com/dduzgun-security/github-self-hosted-runners) and [Wiz](https://www.wiz.io/blog/github-actions-security-guide) 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](https://github.com/super-linter/super-linter) 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](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/communicating-with-self-hosted-runners) your self-hosted runner needs to communicate with. If you are operating in a [GitHub Allow List](https://docs.github.com/en/enterprise-cloud@latest/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/managing-allowed-ip-addresses-for-your-organization) 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](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-a-proxy-server-with-self-hosted-runners), 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](/pricing/plans), so you'll find your GitHub workflows are significantly cheaper. For this guide, over ~2,300 1-minute builds were tested on Railway self-hosted runners and the usage costs were `$1.80` compared to [GitHub's Estimated Hosted Runner](https://github.com/pricing/calculator?feature=actions) cost of `$18.40` for the same workload. Even better? With 10x Railway replicas with 32 vCPU and 32GB RAM for this test, the 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.

<Image src="https://res.cloudinary.com/railway/image/upload/v1746386242/docs/github-actions/urc6rirvsb3folwoqoml.png"
alt="screenshot of Railway's Observability dashboard demonstrating burstable usage of Memory"
layout="responsive"
width={1604} height={800} quality={100} />

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.

GitHub Actions Self Hosted Runners

[Laravel](https://laravel.com) is a PHP framework designed for web artisans who value simplicity and elegance in their code. It stands out for its clean and expressive syntax, and offers built-in tools to handle many common tasks found in modern web applications, making development smoother and more enjoyable.

This guide covers how to deploy a Laravel app on Railway in three ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/fWEWWf)

This template sets up a basic Laravel application along with a Postgres database on Railway. You can also choose from a <a href="https://railway.com/templates?q=laravel" target="_blank">variety of Laravel app templates</a> created by the community.

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

## Deploy from a GitHub repo

To deploy a Laravel app on GitHub to Railway, follow the steps below:

1. Create a <a href="https://railway.com/new" target="_blank">New Project.</a>

2. Click **Deploy from GitHub repo**.

3. Select your GitHub repo.

   - Railway requires a valid GitHub account to be linked. If your Railway account isn't associated with one, you will be prompted to link it.

4. Click **Add Variables**.

   - Add all your app environment variables.

5. Click **Deploy**.

Once the deployment is successful, a Railway [service](/services) will be created for you. By default, this service will not be publicly accessible.

**Note:** Railway will automatically detect that it's a Laravel app during [deploy and run your app via php-fpm and nginx](https://nixpacks.com/docs/providers/php).

To set up a publicly accessible URL for the service, navigate to the **Networking** section in the [Settings](/overview/the-basics#service-settings) tab of your new service and click on [Generate Domain](/networking/public-networking#railway-provided-domain).

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727885952/docs/quick-start/CleanShot_2024-10-02_at_17.18.04_2x_nn78ga.png"
alt="screenshot of the deployed Laravel service showing the Laravel home page"
layout="responsive"
width={2855} height={2109} quality={100} />

**Note**: [Jump to the **Set Up Database, Migrations, Crons and Workers** section](#deploy-via-custom-scripts) to learn how to run your Laravel app along with a Postgres(or MySQL) database, cron jobs, and workers.

## Deploy from the CLI

If you have your Laravel app locally, you can follow these steps:

1. <a href="/guides/cli#installing-the-cli" target="_blank">Install</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate with the Railway CLI.</a>

2. Run `railway init` within your Laravel app root directory to create a new project on Railway.

   - Follow the steps in the prompt to give your project a name.

3. Run `railway up` to deploy.

   - The CLI will now scan, compress and upload your Laravel app files to Railway's backend for deployment.

   - Your terminal will display real-time logs as your app is being deployed on Railway.

4. Once the deployment is successful, click on **View logs** on the recent deployment on the dashboard.

   - You'll see that the server is running. However you'll also see logs prompting you to add your env variables.

5. Click on the <a href="/overview/the-basics#service-variables">**Variables**</a> section of your service on the Railway dashboard.

6. Click on **Raw Editor** and add all your app environment variables.

7. Click on **Deploy** to redeploy your app.

To set up a publicly accessible URL for the service, navigate to the **Networking** section in the [Settings](/overview/the-basics#service-settings) tab of your new service and click on [Generate Domain](/networking/public-networking#railway-provided-domain).

**Note:** The next step shows how to run your Laravel app along with a database, migrations, cron jobs, and workers.

## Set up database, migrations, crons and workers

This setup deploys your Laravel app on Railway, ensuring that your database, scheduled tasks (crons), and queue workers are all fully operational.

The deployment structure follows a "majestic monolith" architecture, where the entire Laravel app is managed as a single codebase but split into four separate services on Railway:

- **App Service**: Handles HTTP requests and user interactions.

- **Cron Service**: Manages scheduled tasks (e.g., sending emails or running reports).

- **Worker Service**: Processes background jobs from the queue.

- **Database Service**: Stores and retrieves your application's data.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727910244/docs/quick-start/deploy%20architecture.png"
alt="screenshot of the deploy architecture of the Laravel app"
layout="responsive"
width={3118} height={1776} quality={100} />
_My Majestic Monolith Laravel app_

Please follow these steps to get started:

1. Create four bash scripts in the `railway` directory of your Laravel app: `init-app.sh`, `run-worker.sh`, and `run-cron.sh`.

   These scripts will contain the commands needed to deploy and run the app, worker, and cron services for your Laravel app on Railway.

   - Add the content below to the `railway/init-app.sh` file:

     **Note:** You can add any additional commands to the script that you want to run each time your app service is built.

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x railway/init-app.sh`

     # Exit the script if any command fails
     set -e

     # Run migrations
     php artisan migrate --force

     # Clear cache
     php artisan optimize:clear

     # Cache the various components of the Laravel application
     php artisan config:cache
     php artisan event:cache
     php artisan route:cache
     php artisan view:cache
     ```

   - Add the content below to the `railway/run-worker.sh` file:

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x railway/run-worker.sh`

     # This command runs the queue worker.
     # An alternative is to use the php artisan queue:listen command
     php artisan queue:work
     ```

   - Add the content below to the `railway/run-cron.sh` file:

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x railway/run-cron.sh`

     # This block of code runs the Laravel scheduler every minute
     while [ true ]
         do
             echo "Running the scheduler..."
             php artisan schedule:run --verbose --no-interaction &
             sleep 60
         done
     ```

2. Create a Postgres Database service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas.</a>

   - Click on **Deploy**.

3. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas.</a>

   - Name the service **App service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a> to configure it.

   - Connect your GitHub repo to the **Source Repo** in the **Source** section.

   - Add `npm run build` to the **Custom Build Command** in the <a href="/guides/build-configuration#customize-the-build-command">**Build**</a> section.

   - Add `chmod +x ./railway/init-app.sh && sh ./railway/init-app.sh` to the <a href="/guides/pre-deploy-command">**Pre-Deploy Command**</a> in the **Deploy** section.

   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.

   - Add all the necessary environment variables required for the Laravel app especially the ones listed below.

     - `APP_KEY`: Set the value to what you get from the `php artisan key:generate` command.

     - `DB_CONNECTION`: Set the value to `pgsql`.

     - `QUEUE_CONNECTION`: Set the value to `database`.

     - `DB_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   - Click **Deploy**.

4. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a>.

   - Name the service **cron service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.

   - Connect your GitHub repo to the **Source Repo** in the **Source** section.

   - Add `chmod +x ./railway/run-cron.sh && sh ./railway/run-cron.sh` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.

   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.

   - Add all the necessary environment variables especially those highlighted already in step 3.

   - Click **Deploy**.

5. Create a new service again on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a>.

   - Name the service **worker service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.

   - Connect your GitHub repo to the **Source Repo** in the **Source** section.

   - Add `chmod +x ./railway/run-worker.sh && sh ./railway/run-worker.sh` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.

   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.

   - Add all the necessary environment variables especially those highlighted already in step 3.

   - Click **Deploy**.

At this point, you should have all three services deployed and connected to the Postgres Database service:

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727910244/docs/quick-start/deploy%20architecture.png"
alt="screenshot of the deploy architecture of the Laravel app"
layout="responsive"
width={3118} height={1776} quality={100} />

- **Cron Service**: This service should run the Laravel Scheduler to manage scheduled tasks.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727912479/docs/quick-start/CleanShot_2024-10-03_at_00.40.40_2x_cwgazh.png"
alt="screenshot of the cron service of the Laravel app"
layout="responsive"
width={2165} height={1873} quality={100} />

- **Worker Service**: This service should be running and ready to process jobs from the queue.

- **App Service**: This service should be running and is the only one that should have a public domain, allowing users to access your application.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1727885952/docs/quick-start/CleanShot_2024-10-02_at_17.18.04_2x_nn78ga.png"
alt="screenshot of the deployed Laravel service showing the Laravel home page"
layout="responsive"
width={2855} height={2109} quality={100} />
_App service_

**Note:** There is a [community template](https://railway.com/template/Gkzn4k) available that demonstrates this deployment approach. You can easily deploy this template and then connect it to your own GitHub repository for your application.

## Logging

Laravel, by default, writes logs to a directory on disk. However, on Railway’s ephemeral filesystem, this setup won’t persist logs.

To ensure logs and errors appear in Railway’s console or with `railway logs`, update the following environment variables:

- `LOG_CHANNEL`: Set the value to `stderr`.

- `LOG_STDERR_FORMATTER`: Set the value to `\Monolog\Formatter\JsonFormatter` in order to have [Structured logs](https://docs.railway.com/guides/logs#structured-logs).

You can set variables via the Railway dashboard or CLI as shown:
```bash
railway variables --set "LOG_CHANNEL=stderr" --set "LOG_STDERR_FORMATTER=\Monolog\Formatter\JsonFormatter"
```

## Can I deploy with Laravel sail?

You may be thinking about using [Laravel Sail](https://laravel.com/docs/11.x/sail), which is the standard approach for deploying Laravel applications with Docker. At its core, Sail relies on a `docker-compose.yml` file to manage the environment.

However, it's important to note that Railway currently does not support Docker Compose.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Laravel app to Railway with this step-by-step guide. It covers quick setup, private networking, database integration, one-click deploys and other deployment strategies.

Deploy a Laravel App

[Lovable](https://lovable.dev) is an AI-powered development platform that generates full-stack web applications from natural language prompts. The platform produces code that can be exported to GitHub and deployed to hosting platforms.

Lovable handles the code generation and iteration cycle within its environment. When connected to GitHub, changes made through Lovable's prompt interface automatically sync to a repository, enabling deployment pipelines to external platforms.

This guide covers how to deploy a Lovable-generated app to Railway:

1. [Generate and connect to GitHub](#generate-app-and-connect-to-github).
2. [Deploy from GitHub repository](#deploy-from-github-repo).
3. [Enable continuous deployment](#enable-continuous-deployment).
4. [Iterate on your application](#iterate-on-your-application).

## Generate app and connect to GitHub

Lovable generates code within its platform. To deploy on Railway, the code must first be exported to GitHub.

### Create a project in Lovable

If you already have a Lovable project connected to GitHub, skip to [Deploy from GitHub Repo](#deploy-from-github-repo).

1. Sign in to [Lovable](https://lovable.dev) and create a new project.
2. Use prompts to generate your application. Lovable produces a full-stack application with frontend and backend components as needed.
3. Test the application within Lovable's environment to verify functionality.

### Connect to GitHub

The GitHub integration establishes a two-way sync between Lovable and a repository. Changes in Lovable appear in GitHub automatically, and commits to the default branch sync back to Lovable.

**Prerequisites:**
- GitHub account (create one at [github.com](https://github.com))
- Admin or owner access to your Lovable workspace

**Connection steps:**

1. In Lovable, navigate to **Settings → Integrations → GitHub**.
2. Click **Connect GitHub** and authorize Lovable to access your GitHub account.
3. Install the Lovable GitHub App on your personal account or organization.
   - Choose whether to grant access to all repositories or selected ones.
   - Click **Install & Authorize**.
4. Connect your specific project:
   - Click **Connect project** in the GitHub settings.
   - Select the GitHub account or organization where the repository should be created.
   - Confirm the transfer to establish two-way sync.

Lovable creates a new repository containing your application code. All subsequent changes made through Lovable's interface push to this repository automatically.

**Important constraints:**

- The repository name, location, and owner must remain unchanged. Renaming or moving the repository breaks the sync.
- Only the default branch (typically `main`) syncs with Lovable.
- Each Lovable project connects to exactly one repository.

## Deploy from GitHub repo

Once your Lovable project is connected to GitHub, deploy it to Railway by importing the repository.

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose the repository created by Lovable.
     - If your Railway account isn't linked to GitHub yet, you'll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Railway detects the build configuration from your Lovable-generated code and provisions the necessary resources.
   - Once deployed, a Railway [service](/services) will be created for your app, but it won't be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
   - Review any build or runtime errors in the deployment logs.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

Your Lovable-generated application is now live on Railway.

### Environment variables

Lovable-generated applications may require environment variables for API keys, database connections, or other configuration.

**Add environment variables in Railway:**

1. Navigate to your service in Railway.
2. Go to the **Variables** tab.
3. Add the required variables as key-value pairs.
4. Railway automatically redeploys with the new configuration.

See the [Variables guide](/variables) for detailed information on managing environment variables.

## Iterate on your application

The Lovable-Railway workflow enables prompt-driven development with automatic deployment.

**Development workflow:**

1. Open your Lovable project.
2. Describe changes or new features using natural language prompts.
3. Lovable generates the code changes and updates the GitHub repository.
4. Railway detects the commit and begins redeployment automatically.
5. Monitor the deployment in Railway's logs to verify the changes deployed successfully.

**Development cycle timing:**

- Lovable to GitHub sync occurs within seconds of completing changes.
- Railway deployment time depends on build complexity, typically a few minutes.

**Handling deployment failures:**

If a deployment fails after a Lovable change:

1. Check Railway's build and deployment logs for errors.
2. Review the changes in GitHub to identify problematic code.
3. Use Lovable's prompt interface to request fixes or adjustments.
4. Lovable will push corrections to GitHub, triggering a new deployment attempt.

**Working with branches:**

By default, Lovable syncs only with the default branch (usually `main`). Railway deploys from this same branch.

Lovable offers experimental branch switching in **Settings → Account → Labs**. When enabled, you can develop features on separate branches before merging to the main branch, which then deploys to Railway.


## Railway templates marketplace

The Railway templates marketplace provides pre-configured services that can be deployed alongside your Lovable application. Templates include databases, caching systems, message queues, and other infrastructure components commonly needed by web applications.

**Adding templates to your project:**

1. Navigate to your Railway project containing your Lovable application.
2. Click the **+ New** button to add a service.
3. Select **Template** to browse the marketplace.
4. Search for the service you need (PostgreSQL, Redis, MongoDB, etc.).
5. Click **Deploy** to add the template to your project.

The template service deploys in the same project as your Lovable application. Services within a project can communicate through [private networking](/networking/private-networking), and connection details are available as environment variables.

After deploying a template, configure your Lovable application to use the service by adding the connection variables to your Railway service's environment variables.

Browse available templates at the <a href="https://railway.com/deploy" target="_blank">Railway Templates marketplace</a>.


## Troubleshooting

**Deployment fails after Lovable changes:**

- Check Railway logs for build or runtime errors.
- Verify that environment variables are configured correctly.
- Ensure the repository connection remains intact (not renamed or moved).

**Changes in Lovable don't trigger Railway deployments:**

- Verify GitHub autodeploys are enabled in Railway's service settings.
- Check that the Lovable-GitHub connection is active in Lovable's integration settings.
- Confirm changes were committed to the default branch (`main`).

**Repository connection broken:**

- Lovable's GitHub sync breaks if the repository is renamed, moved, or deleted.
- Restore the repository to its original name and location.
- If deleted, [restore the repository on GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/restoring-a-deleted-repository).


## Next steps

Explore these resources to enhance your Lovable application on Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)
- [Configure environment variables](/variables)
- [Set up custom domains](/networking/public-networking)

Learn how to deploy applications generated by Lovable.dev to Railway. This guide covers the workflow from prompt-based generation to continuous deployment.

Deploy a Lovable App on Railway

[Luminus](https://luminusweb.com) is a Clojure micro-framework based on a set of lightweight libraries. It aims to provide a robust, scalable, and easy to use platform. With Luminus you can focus on developing your app the way you want without any distractions.

This guide covers how to deploy a Luminus app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Luminus app!

## Create a Luminus app

**Note:** If you already have a Luminus app locally or on GitHub, you can skip this step and go straight to the [Deploy Luminus App to Railway](#deploy-luminus-app-to-railway).

To create a new Luminus app, ensure that you have [JDK](https://www.oracle.com/java/technologies/downloads/) and [Leiningen](https://leiningen.org/#install) installed on your machine.

Run the following command in your terminal to create a new Luminus app with Postgres and a production ready server:

```bash
lein new luminus helloworld +postgres +immutant
```

A new Luminus app will be provisioned for you in the `helloworld` directory with support for PostgreSQL as the database and configures [Immutant](https://github.com/immutant/immutant) as the web server, which is production-ready and optimized for Clojure applications.

**Note:** If you use MySQL or another database, you can pass it as an option when trying to create a new app.

### Run the Luminus app locally

Open `dev-config.edn` and add your Postgres database URL like so:

```clojure
 :database-url "postgresql://username:password@127.0.0.1:5432/helloworld_dev"
```

- `username:password` is your database user and password.
- `helloworld_dev` is the database you have created locally.

Next, run `lein run migrate` to run the database migrations.

Finally, run `lein run` to launch your app!

Open your browser and go to `http://localhost:3000` to see the app.

### Prepare Clojure Luminus app for deployment

1. Add the `cheshire` library to your dependencies. `cheshire` is a popular JSON encoding/decoding library in Clojure.

Open your `project.clj` file and ensure you have the following under `:dependencies`:

```clojure
...
[cheshire "5.10.0"]
```

Run the command below in your terminal to ensure it is installed:

```bash
lein deps
```

2. Create a `nixpacks.toml` file in the root directory of the app.

The [nixpacks.toml file](https://nixpacks.com/docs/configuration/file) is a configuration file used by Nixpacks, a build system developed and used by Railway, to set up and deploy applications.

In this file, you can specify the instructions for various build and deployment phases, along with environment variables and package dependencies.

Add the following content to the file:

```toml
# nixpacks.toml

[start]
cmd = "java -jar $(find ./target -name '*.jar' ! -name '*SNAPSHOT*') migrate && java -jar $(find ./target -name '*.jar' ! -name '*SNAPSHOT*')"

```

Here, Nixpacks is being specifically instructed to use the following command to start the app.

The command searches for all `.jar` files in the `target` directory (where the standalone JAR file is located after the build), excludes any file with "SNAPSHOT" in its name, and passes the selected file to `java -jar` to run.

It starts by running the JAR file with the `migrate` option to apply database migrations. Once migrations are complete, it reruns the JAR file to launch the application.

## Deploy the Luminus app to Railway

Railway offers multiple ways to deploy your Clojure 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/DsDYI2)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=clojure" target="_blank">variety of Clojure app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Luminus app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:

   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter `DATABASE_URL=${{Postgres.DATABASE_URL}}`.
     - The value, `${{Postgres.DATABASE_URL}}`, references the URL of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.

5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/v1730897279/docs/quick-start/clojure_luminus_on_railway.png"
alt="screenshot of the deployed Clojure service"
layout="responsive"
width={2325} height={2187} quality={100} />

### Deploy from a GitHub repo

To deploy a Clojure Luminus app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s a Clojure app](https://nixpacks.com/docs/providers/clojure).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the Luminus app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Clojure official image
   # https://hub.docker.com/_/clojure
   FROM clojure:temurin-23-lein-bookworm

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN lein uberjar

   # Run the app by dynamically finding the standalone JAR file in the target/uberjar directory
   CMD ["sh", "-c", "java -jar $(find target/uberjar -name '*.jar' ! -name '*SNAPSHOT*')"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Clojure apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy your Clojure Luminus app to Railway with this step-by-step guide. It covers quick setup, database integration, one-click deploys and other deployment strategies.

Deploy a Clojure Luminus App

Here are examples to help you manage domains using the Public API.

## List domains for a service

Get all domains (both Railway-provided and custom) for a service:

<GraphQLCodeTabs query={`query domains($projectId: String!, $environmentId: String!, $serviceId: String!) {
  domains(
    projectId: $projectId
    environmentId: $environmentId
    serviceId: $serviceId
  ) {
    serviceDomains {
      id
      domain
      suffix
      targetPort
    }
    customDomains {
      id
      domain
      status {
        dnsRecords {
          hostlabel
          requiredValue
          currentValue
          status
        }
      }
    }
  }
}`} variables={{ projectId: "project-id", environmentId: "environment-id", serviceId: "service-id" }} />

## Service domains (*.railway.app)

### Create a service domain

Generate a Railway-provided domain:

<GraphQLCodeTabs query={`mutation serviceDomainCreate($input: ServiceDomainCreateInput!) {
  serviceDomainCreate(input: $input) {
    id
    domain
  }
}`} variables={{ input: { serviceId: "service-id", environmentId: "environment-id" } }}
optionalFields={[
  { name: "input.targetPort", type: "Int", description: "Route traffic to this port" },
]} />

### Delete a service domain

<GraphQLCodeTabs query={`mutation serviceDomainDelete($id: String!) {
  serviceDomainDelete(id: $id)
}`} variables={{ id: "service-domain-id" }} />

## Custom domains

### Check domain availability

Check if a custom domain can be added:

<GraphQLCodeTabs query={`query customDomainAvailable($domain: String!) {
  customDomainAvailable(domain: $domain) {
    available
    message
  }
}`} variables={{ domain: "api.example.com" }} />

### Add a custom domain

<GraphQLCodeTabs query={`mutation customDomainCreate($input: CustomDomainCreateInput!) {
  customDomainCreate(input: $input) {
    id
    domain
    status {
      dnsRecords {
        hostlabel
        requiredValue
        status
      }
    }
  }
}`} variables={{ input: { projectId: "project-id", environmentId: "environment-id", serviceId: "service-id", domain: "api.example.com" } }}
optionalFields={[
  { name: "input.targetPort", type: "Int", description: "Route traffic to this port" },
]} />

### Get custom domain status

Check DNS configuration status:

<GraphQLCodeTabs query={`query customDomain($id: String!, $projectId: String!) {
  customDomain(id: $id, projectId: $projectId) {
    id
    domain
    status {
      dnsRecords {
        hostlabel
        requiredValue
        currentValue
        status
      }
      certificateStatus
    }
  }
}`} variables={{ id: "custom-domain-id", projectId: "project-id" }} />

### Update a custom domain

<GraphQLCodeTabs query={`mutation customDomainUpdate($id: String!, $environmentId: String!, $targetPort: Int) {
  customDomainUpdate(id: $id, environmentId: $environmentId, targetPort: $targetPort)
}`} variables={{ id: "custom-domain-id", environmentId: "environment-id", targetPort: 8080 }} />

### Delete a custom domain

<GraphQLCodeTabs query={`mutation customDomainDelete($id: String!) {
  customDomainDelete(id: $id)
}`} variables={{ id: "custom-domain-id" }} />

## DNS configuration

After adding a custom domain, you need to configure DNS records. The required records are returned in the `status.dnsRecords` field.

### For root domains (example.com)

Add an A record or ALIAS record pointing to the Railway IP.

### For subdomains (api.example.com)

Add a CNAME record pointing to your Railway service domain.

### DNS record statuses

| Status | Description |
|--------|-------------|
| `PENDING` | DNS record not yet configured |
| `VALID` | DNS record is correctly configured |
| `INVALID` | DNS record is configured incorrectly |

### Certificate statuses

| Status | Description |
|--------|-------------|
| `PENDING` | Certificate is being issued |
| `ISSUED` | Certificate is active |
| `FAILED` | Certificate issuance failed |

Learn how to manage domains via the public GraphQL API.

Manage Domains with the Public API

Here are examples to help you manage your environments using the Public API.

## List environments

Get all environments for a project:

<GraphQLCodeTabs query={`query environments($projectId: String!) {
  environments(projectId: $projectId) {
    edges {
      node {
        id
        name
        createdAt
      }
    }
  }
}`} variables={{ projectId: "project-id" }} />

### Exclude ephemeral environments

Filter out PR/preview environments:

<GraphQLCodeTabs query={`query environments($projectId: String!, $isEphemeral: Boolean) {
  environments(projectId: $projectId, isEphemeral: $isEphemeral) {
    edges {
      node {
        id
        name
        createdAt
      }
    }
  }
}`} variables={{ projectId: "project-id", isEphemeral: false }} />

## Get a single environment

Fetch an environment by ID with its service instances:

<GraphQLCodeTabs query={`query environment($id: String!) {
  environment(id: $id) {
    id
    name
    createdAt
    serviceInstances {
      edges {
        node {
          id
          serviceName
          latestDeployment {
            id
            status
          }
        }
      }
    }
  }
}`} variables={{ id: "environment-id" }} />

## Create an environment

Create a new environment:

<GraphQLCodeTabs query={`mutation environmentCreate($input: EnvironmentCreateInput!) {
  environmentCreate(input: $input) {
    id
    name
  }
}`} variables={{ input: { projectId: "project-id", name: "staging" } }}
optionalFields={[
  { name: "input.sourceEnvironmentId", type: "String", description: "Clone variables and settings from this environment" },
  { name: "input.ephemeral", type: "Boolean", description: "Create as ephemeral (for PR previews)", apiDefault: "false" },
  { name: "input.skipInitialDeploys", type: "Boolean", description: "Don't trigger deployments on creation", apiDefault: "false" },
  { name: "input.stageInitialChanges", type: "Boolean", description: "Stage changes instead of applying immediately", apiDefault: "false" },
]} />

## Rename an environment

<GraphQLCodeTabs query={`mutation environmentRename($id: String!, $input: EnvironmentRenameInput!) {
  environmentRename(id: $id, input: $input)
}`} variables={{ id: "environment-id", input: { name: "new-name" } }} />

## Delete an environment

<Banner variant="danger">This will delete the environment and all its deployments.</Banner>

<GraphQLCodeTabs query={`mutation environmentDelete($id: String!) {
  environmentDelete(id: $id)
}`} variables={{ id: "environment-id" }} />

## Get environment logs

Fetch logs from all services in an environment:

<GraphQLCodeTabs query={`query environmentLogs($environmentId: String!, $filter: String) {
  environmentLogs(environmentId: $environmentId, filter: $filter) {
    timestamp
    message
    severity
    tags {
      serviceId
      deploymentId
    }
  }
}`} variables={{ environmentId: "environment-id" }}
optionalFields={[
  { name: "filter", type: "String", description: "Filter logs by text (e.g., 'error')" },
]} />

## Staged changes

Railway supports staging variable changes before deploying them.

### Get staged changes

<GraphQLCodeTabs query={`query environmentStagedChanges($environmentId: String!) {
  environmentStagedChanges(environmentId: $environmentId)
}`} variables={{ environmentId: "environment-id" }} />

### Commit staged changes

<GraphQLCodeTabs query={`mutation environmentPatchCommitStaged($environmentId: String!) {
  environmentPatchCommitStaged(environmentId: $environmentId)
}`} variables={{ environmentId: "environment-id" }} />

Learn how to manage environments via the public GraphQL API.

Manage Environments with the Public API

Here are examples to help you manage persistent volumes using the Public API.

## Get project volumes

List all volumes in a project:

<GraphQLCodeTabs query={`query project($id: String!) {
  project(id: $id) {
    volumes {
      edges {
        node {
          id
          name
          createdAt
        }
      }
    }
  }
}`} variables={{ id: "project-id" }} />

## Get volume instance details

Get details about a volume instance (volume in a specific environment):

<GraphQLCodeTabs query={`query volumeInstance($id: String!) {
  volumeInstance(id: $id) {
    id
    mountPath
    currentSizeMB
    state
    volume {
      id
      name
    }
    serviceInstance {
      serviceName
    }
  }
}`} variables={{ id: "volume-instance-id" }} />

## Create a volume

Create a new persistent volume attached to a service:

<GraphQLCodeTabs query={`mutation volumeCreate($input: VolumeCreateInput!) {
  volumeCreate(input: $input) {
    id
    name
  }
}`} variables={{ input: { projectId: "project-id", serviceId: "service-id", mountPath: "/data" } }}
optionalFields={[
  { name: "input.environmentId", type: "String", description: "Create in a specific environment" },
  { name: "input.region", type: "String", description: "Volume region (e.g., us-west1)" },
]} />

## Update a volume

Rename a volume:

<GraphQLCodeTabs query={`mutation volumeUpdate($volumeId: String!, $input: VolumeUpdateInput!) {
  volumeUpdate(volumeId: $volumeId, input: $input) {
    id
    name
  }
}`} variables={{ volumeId: "volume-id", input: { name: "database-storage" } }} />

## Update volume instance

Update the mount path for a volume instance:

<GraphQLCodeTabs query={`mutation volumeInstanceUpdate($volumeId: String!, $input: VolumeInstanceUpdateInput!) {
  volumeInstanceUpdate(volumeId: $volumeId, input: $input)
}`} variables={{ volumeId: "volume-id", input: { mountPath: "/new/path" } }} />

## Delete a volume

<Banner variant="danger">This will permanently delete the volume and all its data.</Banner>

<GraphQLCodeTabs query={`mutation volumeDelete($volumeId: String!) {
  volumeDelete(volumeId: $volumeId)
}`} variables={{ volumeId: "volume-id" }} />

## Volume backups

### List backups

Get all backups for a volume instance:

<GraphQLCodeTabs query={`query volumeInstanceBackupList($volumeInstanceId: String!) {
  volumeInstanceBackupList(volumeInstanceId: $volumeInstanceId) {
    id
    name
    createdAt
    expiresAt
    usedMB
    referencedMB
  }
}`} variables={{ volumeInstanceId: "volume-instance-id" }} />

### Create a backup

<GraphQLCodeTabs query={`mutation volumeInstanceBackupCreate($volumeInstanceId: String!) {
  volumeInstanceBackupCreate(volumeInstanceId: $volumeInstanceId)
}`} variables={{ volumeInstanceId: "volume-instance-id" }} />

### Restore from backup

<GraphQLCodeTabs query={`mutation volumeInstanceBackupRestore($volumeInstanceBackupId: String!, $volumeInstanceId: String!) {
  volumeInstanceBackupRestore(volumeInstanceBackupId: $volumeInstanceBackupId, volumeInstanceId: $volumeInstanceId)
}`} variables={{ volumeInstanceBackupId: "backup-id", volumeInstanceId: "volume-instance-id" }} />

### Lock a backup (prevent expiration)

<GraphQLCodeTabs query={`mutation volumeInstanceBackupLock($volumeInstanceBackupId: String!, $volumeInstanceId: String!) {
  volumeInstanceBackupLock(volumeInstanceBackupId: $volumeInstanceBackupId, volumeInstanceId: $volumeInstanceId)
}`} variables={{ volumeInstanceBackupId: "backup-id", volumeInstanceId: "volume-instance-id" }} />

### Delete a backup

<GraphQLCodeTabs query={`mutation volumeInstanceBackupDelete($volumeInstanceBackupId: String!, $volumeInstanceId: String!) {
  volumeInstanceBackupDelete(volumeInstanceBackupId: $volumeInstanceBackupId, volumeInstanceId: $volumeInstanceId)
}`} variables={{ volumeInstanceBackupId: "backup-id", volumeInstanceId: "volume-instance-id" }} />

## Backup schedules

### List backup schedules

<GraphQLCodeTabs query={`query volumeInstanceBackupScheduleList($volumeInstanceId: String!) {
  volumeInstanceBackupScheduleList(volumeInstanceId: $volumeInstanceId) {
    id
    name
    cron
    kind
    retentionSeconds
    createdAt
  }
}`} variables={{ volumeInstanceId: "volume-instance-id" }} />

## Common mount paths

| Use Case | Recommended Mount Path |
|----------|------------------------|
| PostgreSQL | `/var/lib/postgresql/data` |
| MySQL | `/var/lib/mysql` |
| MongoDB | `/data/db` |
| Redis | `/data` |
| General Storage | `/data` or `/app/data` |

Learn how to manage persistent volumes via the public GraphQL API.

Manage Volumes with the Public API

[Nest](https://nestjs.com) is a modern Node.js framework designed to create efficient, reliable, and scalable server-side applications. Built on top of powerful HTTP server frameworks, it uses Express as the default but also offers seamless support for Fastify for enhanced performance and flexibility.

This guide covers how to deploy a Nest app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's go ahead and create a Nest app!

## Create a Nest app

**Note:** If you already have a Nest app locally or on GitHub, you can skip this step and go straight to the [Deploy Nest App to Railway](#deploy-the-nest-app-to-railway).

To create a new Nest app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) and [NestJS](https://docs.nestjs.com/#installation) installed on your machine.

Run the following command in your terminal to create a new Nest app:

```bash
nest new helloworld
```

A new Nest app will be provisioned for you in the `helloworld` directory.

### Run the Nest app locally

Next, start the app locally by running the following command:

```bash
npm run start
```

Launch your browser and navigate to `http://localhost:3000` to view the app.

If you'd prefer to run the app on a different port, simply use the command `PORT=8080 npm run start` in the terminal.

Afterward, you can access the app at `http://localhost:8080`.

### Add and configure database

**Note:** This app uses Postgres. If you don’t have it installed locally, you can either [install it](https://www.postgresql.org/download) or use a different Node.js database package of your choice.

1. Create a database named `nestjshelloworld_dev`.

2. Install the following packages:

```bash
npm i @nestjs/typeorm typeorm pg
```

- typeorm is an ORM library for Typescript and JavaScript.
- pg is for communicating with Postgres database.

3. Open the `src/app.module.ts` file and modify the content to the code below:

```js
import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { TypeOrmModule } from "@nestjs/typeorm";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      host: "localhost",
      port: 5432,
      username: "username",
      password: "password",
      database: "nestjshelloworld_dev",
      entities: [],
      synchronize: true,
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

Start the app using the command, `npm run start:dev`. The code above tries to connect to the database once the app is started. If any of the credentials are wrong, you will see a warning stating that the app can't connect to the database.

4. Open `src/app.service.ts` file and modify the content to return `Hello World, Welcome to Railway!`.

```js
import { Injectable } from "@nestjs/common";

@Injectable()
export class AppService {
  getHello(): string {
    return "Hello World, Welcome to Railway!";
  }
}
```

5. Run the app again to see your changes in action!

### Prepare NestJS app for deployment

In the `src/app.module.ts` file, replace the hardcoded Postgres database credentials with environment variables:

```js
import { Module } from "@nestjs/common";
import { AppController } from "./app.controller";
import { AppService } from "./app.service";
import { TypeOrmModule } from "@nestjs/typeorm";

@Module({
  imports: [
    TypeOrmModule.forRoot({
      type: "postgres",
      host: process.env.DB_HOST,
      port: 5432,
      username: process.env.DB_USERNAME,
      password: process.env.DB_PASSWORD,
      database: process.env.DB_DATABASE,
      entities: [],
      synchronize: true,
    }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

This allows the app to dynamically pull the correct database configuration from Railway during deployment.

## Deploy the Nest app to Railway

Railway offers multiple ways to deploy your Nest app, depending on your setup and preference.

### One-click deploy from a template

If you’re looking for the fastest way to get started with Nest connected to a Postgres database, the one-click deploy option is ideal.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/template/nvnuEH)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=nest" target="_blank">variety of Nest app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Nest app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:

   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter
     - `DB_DATABASE=${{Postgres.PGDATABASE}}`.
     - `DB_USERNAME=${{Postgres.PGUSER}}`
     - `DB_PASSWORD=${{Postgres.PGPASSWORD}}`
     - `DB_HOST=${{Postgres.PGHOST}}`
     - The Postgres values references the credentials of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.

5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1732547945/docs/quick-start/nest_on_railway.png"
alt="screenshot of the deployed Nest service"
layout="responsive"
width={2069} height={2017} quality={100} />

### Deploy from a GitHub repo

To deploy a Nest app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DB_DATABASE=${{Postgres.PGDATABASE}}`.
     - `DB_USERNAME=${{Postgres.PGUSER}}`
     - `DB_PASSWORD=${{Postgres.PGPASSWORD}}`
     - `DB_HOST=${{Postgres.PGHOST}}`
     - The Postgres values references the credentials of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s a Node.js app via Nixpacks](https://nixpacks.com/docs/providers/node).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the Nest app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node official image
   # https://hub.docker.com/_/node
   FROM node:lts

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image
   COPY . ./

   # Install packages
   RUN npm ci

   # Serve the app
   CMD ["npm", "run", "start:prod"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Nest apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a NestJS app to Railway with this step-by-step guide. It covers quick setup, database integration, one-click deploys and other deployment strategies.

Deploy a NestJS App

[Nuxt](https://nuxt.com) is a Vue.js framework that makes web development intuitive and powerful. You can create performant and production-grade full-stack web apps and websites with confidence.

Nuxt is known as **The Intuitive Vue Framework** because it simplifies building Vue.js applications with features like server-side rendering and easy routing.

This guide covers how to deploy a Nuxt app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Nuxt app!

## Create a Nuxt app

**Note:** If you already have a Nuxt app locally or on GitHub, you can skip this step and go straight to the [Deploy Nuxt App on Railway](#deploy-the-nuxt-app-to-railway).

To create a new Nuxt app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new Nuxt app:

```bash
npx nuxi@latest init helloworld
```

A new Nuxt app will be provisioned for you in the `helloworld` directory.

### Run the Nuxt app locally

Next, `cd` into the directory and start the development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:3000` to see your app.

## Deploy the Nuxt app to Railway

Railway offers multiple ways to deploy your Nuxt 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/lQQgLR)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=nuxt" target="_blank">variety of Nuxt app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Vue app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Modify Package.json Config**:

   - By default, Nuxt doesn't add a start script in the `package.json` file. You'll need to add that to instruct Railway on how to run your app.

   - Add `"start":"node .output/server/index.mjs"` to the `package.json` file.

   **package.json**

   ```bash
   {
       "name": "nuxt-app",
       "private": true,
       "type": "module",
       "scripts": {
           "build": "nuxt build",
           "dev": "nuxt dev",
           "start": "node .output/server/index.mjs",
           "generate": "nuxt generate",
           "preview": "nuxt preview",
           "postinstall": "nuxt prepare"
       },
       "dependencies": {
           "nuxt": "^3.13.0",
           "vue": "latest",
           "vue-router": "latest"
       }
   }
   ```

   **Note:** Railway uses [Nixpacks](/builds/nixpacks) to build and deploy your code with zero configuration. The Nixpack Node provider will pick up the start script in the `package.json` file and use it to serve the app.

4. **Deploy the Application**:
   - Use the command below to deploy your app:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729262446/docs/quick-start/nuxt_app.png"
alt="screenshot of the deployed Nuxt service"
layout="responsive"
width={2383} height={2003} quality={100} />

### Deploy from a GitHub repo

To deploy a Nuxt app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Modify Package.json Config**:
   - Follow [step 3 mentioned in the CLI guide](#deploy-from-the-cli)
3. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
4. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
5. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Nuxt app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine AS build

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Copy files to the container image.
   COPY --from=build /app ./

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Nuxt apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Nuxt app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Nuxt App

[Phoenix](https://phoenixframework.org) is popular Elixir framework designed for building scalable, maintainable, and high-performance web applications. It is known for its ability to handle real-time features efficiently, like WebSockets, while leveraging Elixir's concurrency model, which is built on the Erlang Virtual Machine (BEAM).

In this guide, you'll learn how to deploy Phoenix apps with [Distillery](https://hexdocs.pm/distillery/home.html) to Railway.

## Create a Phoenix app with Distillery

**Note:** If you already have a Phoenix app locally or on GitHub, you can skip this step and go straight to the [Deploy Phoenix App with Distillery to Railway](#deploy-phoenix-app-on-railway).

To create a new Phoenix app, ensure that you have [Elixir](https://elixir-lang.org/install.html) and [Hex package manager](https://hexdocs.pm/phoenix/installation.html) installed on your machine. Once everything is set up, run the following command in your terminal to install the Phoenix application generator:

```bash
mix archive.install hex phx_new
```

Next, run the following command:

```bash
mix phx.new helloworld_distillery
```

Select `Y` to install all dependencies.

This command will create a new Phoenix app named `helloworld_distillery` with some optional dependencies such as:

- [Ecto](https://hexdocs.pm/phoenix/ecto.html) for communicating with a database such as PostgreSQL, MySQL etc
- [Phoenix live view](https://hexdocs.pm/phoenix_live_view) for building realtime & interactive web apps.
- [Phoenix HTML and Tailwind CSS](https://hexdocs.pm/phoenix_html/Phoenix.HTML.html) for HTML apps.

### Configure database

Next, navigate into the `helloworld` directory using the `cd` command.

Open up the `config/dev.exs` file. You'll notice that a new Phoenix app is already set up with PostgreSQL settings. It assumes the database has a `postgres` user with the right permissions and a default password of `postgres`. Update the username and password to match your local PostgreSQL account credentials.

**Note**: If you prefer using a different database, like MySQL, you can easily switch the database adapter in the `mix.exs` file. Simply remove the `Postgrex` dependency and add `MyXQL` instead. For detailed instructions, check out this [guide on using other databases](https://hexdocs.pm/phoenix/ecto.html#using-other-databases) in Phoenix.

The default database name is set to `helloworld_dev`, but feel free to change it to whatever you'd prefer.

Next, create the database for your app by running the following command:

```bash
mix ecto.create
```

A database will be created for your app.

### Add and configure Distillery

1. Open up the `mix.exs` file and add Distillery to the deps function:

```elixir
  defp deps do
    [ ...,
     {:distillery, "~> 2.1"},
      ...,
    ]
  end
```

Now, run `mix deps.get` to update your dependencies.

2. Open up `config/prod.exs` file and update the endpoint section to the following:

```elixir
config :helloworld_distillery, HelloworldDistilleryWeb.Endpoint,
  cache_static_manifest: "priv/static/cache_manifest.json",
  server: true,
  root: ".",
  version: Application.spec(:phoenix_distillery, :vsn)
```

`server` configures the endpoint to boot the Cowboy application http endpoint on start.
`root` configures the application root for serving static files
`version` ensures that the asset cache will be busted on versioned application upgrades.

3. Initialize your Distillery release by running the following command:

```bash
mix distillery.init
```

This will create the `rel/config.exs` and `rel/vm.args` files. A `rel/plugins` directory will be created too.

4. Create a Mix config file at `rel/config/config.exs`. Here, a mix config provider is being created. Add the following to it:

```elixir
import Config

port = String.to_integer(System.get_env("PORT") || "4000")
default_secret_key_base = :crypto.strong_rand_bytes(43) |> Base.encode64

config :helloworld_distillery, HelloworldDistilleryWeb.Endpoint,
  http: [port: port],
  url: [host: "localhost", port: port],
  secret_key_base: System.get_env("SECRET_KEY_BASE") || default_secret_key_base
```

Now, update the `rel/config.exs` file to use your new provider. In the `environment :prod` part of the file, replace with the following:

```elixir
environment :prod do
  set include_erts: true
  set include_src: false
  set cookie: :"Jo2*~U0C1x!*E}!o}W*(mx=pzd[XWG[bW)T~_Kjy3eJuEJ;M&!eqj7AUR1*9Vw]!"
  set config_providers: [
    {Distillery.Releases.Config.Providers.Elixir, ["${RELEASE_ROOT_DIR}/etc/config.exs"]}
  ]
  set overlays: [
    {:copy, "rel/config/config.exs", "etc/config.exs"}
  ]
end
```

5. Finally, let's configure Ecto to fetch the database credentials from the runtime environment variables.

Open the `lib/helloworld_distillery/repo.ex` file and modify it to this:

```elixir
defmodule HelloworldDistillery.Repo do
  use Ecto.Repo,
    otp_app: :helloworld_distillery,
    adapter: Ecto.Adapters.Postgres,
    pool_size: 10
  def init(_type, config) do
    {:ok, Keyword.put(config, :url, System.get_env("DATABASE_URL"))}
  end
end
```

### Build the release with Distillery

To build the release, run the following command:

```bash
npm run deploy --prefix assets && MIX_ENV=prod mix do phx.digest, distillery.release --env=prod
```

#### Handling errors

If you encounter the following error after running the command:

```bash
==> Invalid application `:sasl`! The file sasl.app does not exist or cannot be loaded.
```

You need to modify your `mix.exs` file to include `:sasl`. Open the file and add `:sasl` to the `extra_applications` list in the `application` function:

```elixir
def application do
    [
      mod: {HelloworldDistillery.Application, []},
      extra_applications: [:logger, :runtime_tools, :sasl]
    ]
  end
```

After saving your changes, try running the command again as a super user to prevent access errors:

```bash
sudo npm run deploy --prefix assets && MIX_ENV=prod mix do phx.digest, distillery.release --env=prod
```

**Additional Errors**

If you encounter this error:

```bash
Failed to archive release: _build/prod/rel/helloworld_distillery/releases/RELEASES: no such file or directory
```

You’ll need to create the `RELEASES` directory manually. Once created, run the command again.

#### Successful build

Upon a successful build, you should see output similar to the following:

```bash
...
==> Packaging release..
Release successfully built!
To start the release you have built, you can use one of the following tasks:

    # start a shell, like 'iex -S mix'
    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery console

    # start in the foreground, like 'mix run --no-halt'
    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery foreground

    # start in the background, must be stopped with the 'stop' command
    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery start

If you started a release elsewhere, and wish to connect to it:

    # connects a local shell to the running node
    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery remote_console

    # connects directly to the running node's console
    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery attach

For a complete listing of commands and their use:

    > _build/prod/rel/helloworld_distillery/bin/helloworld_distillery help
```

### Test the release with Distillery locally

Now, test your release locally. First, create your database by running the following command:

```bash
mix ecto.create
```

Next, export the necessary environment variables by running:

```bash
export DATABASE_URL=postgresql://username:password@127.0.0.1:5432/helloworld_distillery
export SECRET_KEY_BASE=<your-secret-key-base>
```

With the environment set up, you can start the release with:

```bash
_build/prod/rel/helloworld_distillery/bin/helloworld_distillery foreground
```

Once your app is running, open your browser and visit `http://localhost:4000` to see it in action.

With your app up and running locally, let's move on to deploying the release to Railway!

### Prepare app for deployment

Create a `nixpacks.toml` file in the root of your app directory and add the following content:

```toml
# nixpacks.toml
[variables]
MIX_ENV = 'prod'

[phases.setup]
nixPkgs = ['...', 'erlang']

[phases.install]
cmds = [
  'mix local.hex --force',
  'mix local.rebar --force',
  'mix deps.get --only prod'
]

[phases.build]
cmds = [
  'mix compile',
  'mkdir -p _build/prod/rel/helloworld_distillery/releases/RELEASES',
  'mix do phx.digest, distillery.release --env=prod',
]

[start]
cmd = "mix ecto.setup && _build/prod/rel/helloworld_distillery/bin/helloworld_distillery foreground"
```

This [`nixpacks.toml` file](/config-as-code/reference#nixpacks-config-path) instructs Railway to execute specific commands during the setup, install, build, and start phases of the deployment. It ensures your app is compiled, assets are digested, and the release is created correctly using Distillery.

## Deploy Phoenix app to Railway

Railway offers multiple ways to deploy your Phoenix app, depending on your setup and preference. Choose any of the following methods:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).

## One-click deploy from a template

If you’re looking for the fastest way to get started, the one-click deploy option is ideal. It sets up a Phoenix app with Distillery along with a Postgres database.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/_qWFnI)

After deploying, it is recommended that you [eject from the template](/templates/deploy#eject-from-template-repository) to create a copy of the repository under your own GitHub account. This will give you full control over the source code and project.

## Deploy from the CLI

To deploy the Phoenix app using the Railway CLI, please follow the steps:

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Phoenix app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.

   **Note:** You might encounter an error––`warning: the VM is running with native name encoding of latin1 which` `may cause Elixir to malfunction as it expects utf8....`. Don’t worry, you’ll address this in the next step.

4. **Add a Database Service**:
   - Run `railway add`.
   - Select `PostgreSQL` by pressing space and hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
5. **Configure Environment Variables**:
   - Go to your app service <a href="/overview/the-basics#service-variables">**Variables**</a> section and add the following:
     - `SECRET_KEY_BASE` : Set the value to the your app's secret key. You can run `mix phx.gen.secret` locally to generate one.
     - `LANG`and `LC_CTYPE`: Set both values to `en_US.UTF-8`. This sets your app's locale and gets rid of the _native name encoding of latin1_ warning.
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `ECTO_IPV6`: Set the value to `true` to enable your Phoenix app to connect to the database through the [IPv6 private network](/networking/private-networking#listen-on-ipv6).
   - Use the **Raw Editor** to add any other required environment variables in one go.
6. **Redeploy the Service**:
   - Click **Deploy** on the Railway Project Canvas to apply your changes.
7. **Verify the Deployment**:
   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.
8. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1730309171/docs/quick-start/phoenix_distillery.png"
alt="screenshot of the deployed Phoenix with Distillery service"
layout="responsive"
width={2667} height={2177} quality={100} />

## Deploy from a GitHub repo

To deploy the Phoenix app to Railway, start by pushing the app to a GitHub repo. Once that’s set up, follow the steps below to complete the deployment process.

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**. This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `SECRET_KEY_BASE` : Set the value to the your app's secret key. You can run `mix phx.gen.secret` locally to generate one.
     - `LANG`and `LC_CTYPE`: Set both values to `en_US.UTF-8` to ensure proper locale settings and avoid the _native name encoding of latin1 warning_.
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `ECTO_IPV6`: Set the value to `true` to enable your Phoenix app to connect to the database through the [IPv6 private network](/networking/private-networking#listen-on-ipv6).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s an Elixir app](https://nixpacks.com/docs/providers/elixir).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Phoenix apps with Distillery effortlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Phoneix app with Distillery to Railway with this step-by-step guide. It covers quick setup, ecto setup, database integration, one-click deploys and other deployment strategies.

Deploy a Phoenix App with Distillery

[Phoenix](https://phoenixframework.org) is popular Elixir framework designed for building scalable, maintainable, and high-performance web applications. It is known for its ability to handle real-time features efficiently, like WebSockets, while leveraging Elixir's concurrency model, which is built on the Erlang Virtual Machine (BEAM).

## Create a Phoenix app

**Note:** If you already have a Phoenix app locally or on GitHub, you can skip this step and go straight to the [Deploy Phoenix App on Railway](#deploy-phoenix-app-on-railway).

To create a new Phoenix app, ensure that you have [Elixir](https://elixir-lang.org/install.html) and [Hex package manager](https://hexdocs.pm/phoenix/installation.html) installed on your machine. Once everything is set up, run the following command in your terminal to install the Phoenix application generator:

```bash
mix archive.install hex phx_new
```

Next, run the following command:

```bash
mix phx.new helloworld
```

Select `Y` to install all dependencies.

This command will create a new Phoenix app named `helloworld` with some optional dependencies such as:

- [Ecto](https://hexdocs.pm/phoenix/ecto.html) for communicating with a database such as PostgreSQL, MySQL etc
- [Phoenix live view](https://hexdocs.pm/phoenix_live_view) for building realtime & interactive web apps.
- [Phoenix HTML and Tailwind CSS](https://hexdocs.pm/phoenix_html/Phoenix.HTML.html) for HTML apps.

### Configure database

Next, navigate into the `helloworld` directory using the `cd` command.

Open up the `config/dev.exs` file. You'll notice that a new Phoenix app is already set up with PostgreSQL settings. It assumes the database has a `postgres` user with the right permissions and a default password of `postgres`. Update the username and password to match your local PostgreSQL account credentials.

**Note**: If you prefer using a different database, like MySQL, you can easily switch the database adapter in the `mix.exs` file. Simply remove the `Postgrex` dependency and add `MyXQL` instead. For detailed instructions, check out this [guide on using other databases](https://hexdocs.pm/phoenix/ecto.html#using-other-databases) in Phoenix.

The default database name is set to `helloworld_dev`, but feel free to change it to whatever you'd prefer.

Next, create the database for your app by running the following command:

```bash
mix ecto.create
```

A database will be created for your app.

### Run the Phoenix app locally

Start the app by running the following command:

```bash
mix phx.server
```

By default, Phoenix accepts requests on port `4000`.

Open your browser and go to `http://localhost:4000` to see your app.

Now that your app is running locally, let’s move on to deploying it to Railway!

### Prepare your Phoenix app for deployment

Go ahead and create a `nixpacks.toml` file in the root directory of your Phoenix app.

The [nixpacks.toml file](https://nixpacks.com/docs/configuration/file) is a configuration file used by Nixpacks, a build system developed and used by Railway, to set up and deploy applications.

In this file, you can specify the instructions for various build and deployment phases, along with environment variables and package dependencies.

Add the following content to the file:

```toml
# nixpacks.toml
[variables]
MIX_ENV = 'prod'

[phases.setup]
nixPkgs = ['...', 'erlang']

[phases.install]
cmds = [
  'mix local.hex --force',
  'mix local.rebar --force',
  'mix deps.get --only prod'
]

[phases.build]
cmds = [
  'mix compile',
  'mix assets.deploy'
]

[start]
cmd = "mix ecto.setup && mix phx.server"
```

1. `[variables]` This section contains the list of env variables you want to set for the app.
   - `MIX_ENV = 'prod'`: It sets the Elixir environment to prod.
2. `[phases.setup]`: This defines a list of Nix packages to be installed during the setup phase. The placeholder `'...'` should be replaced with any additional packages needed for your application. The inclusion of erlang indicates that the Erlang runtime is required for the Elixir application.
3. `[phases.install]`: This section contains a list of commands to run during the installation phase.
   - `mix local.hex --force`: Installs the Hex package manager for Elixir, which is necessary for managing dependencies.
   - `mix local.rebar --force`: Installs Rebar, a build tool for Erlang.
   - `mix deps.get --only prod`: Fetches only the production dependencies defined in the `mix.exs` file.
4. `[phases.build]`: This section contains commands to run during the build phase.
   - `mix compile`: Compiles the Elixir application.
   - `mix assets.deploy`: This is a command to handle the deployment of static assets (e.g., JavaScript, CSS) for your app.
5. `[start]`: This section contains commands to run when starting the application.
   - `mix ecto.setup`: This command is used to set up the database by running migrations and seeding it. It prepares the database for the application to connect.
   - `mix phx.server`: This starts the Phoenix server, allowing the application to begin accepting requests.

Now you're ready to deploy!

## Deploy Phoenix app to Railway

Railway offers multiple ways to deploy your Phoenix app, depending on your setup and preference. Choose any of the following methods:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).

## One-click deploy from a template

If you’re looking for the fastest way to get started, the one-click deploy option is ideal. It sets up a Phoenix app along with a Postgres database.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/0LSBzw)

After deploying, it is recommended that you [eject from the template](/templates/deploy#eject-from-template-repository) to create a copy of the repository under your own GitHub account. This will give you full control over the source code and project.

## Deploy from the CLI

To deploy the Phoenix app using the Railway CLI, please follow the steps:

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Phoenix app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.

   **Note:** You might encounter an error––`warning: the VM is running with native name encoding of latin1 which` `may cause Elixir to malfunction as it expects utf8....`. Don’t worry, you’ll address this in the next step.

4. **Add a Database Service**:
   - Run `railway add`.
   - Select `PostgreSQL` by pressing space and hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
5. **Configure Environment Variables**:
   - Go to your app service <a href="/overview/the-basics#service-variables">**Variables**</a> section and add the following:
     - `SECRET_KEY_BASE` : Set the value to the your app's secret key. You can run `mix phx.gen.secret` locally to generate one.
     - `LANG`and `LC_CTYPE`: Set both values to `en_US.UTF-8`. This sets your app's locale and gets rid of the _native name encoding of latin1_ warning.
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `ECTO_IPV6`: Set the value to `true` to enable your Phoenix app to connect to the database through the [IPv6 private network](/networking/private-networking#listen-on-ipv6).
   - Use the **Raw Editor** to add any other required environment variables in one go.
6. **Redeploy the Service**:
   - Click **Deploy** on the Railway Project Canvas to apply your changes.
7. **Verify the Deployment**:
   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.
8. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1730139857/docs/quick-start/phoenix_elixir_app.png"
alt="screenshot of the deployed Phoenix service showing the welcome page"
layout="responsive"
width={2757} height={2111} quality={100} />

## Deploy from a GitHub repo

To deploy the Phoenix app to Railway, start by pushing the app to a GitHub repo. Once that’s set up, follow the steps below to complete the deployment process.

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**. This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `SECRET_KEY_BASE` : Set the value to the your app's secret key. You can run `mix phx.gen.secret` locally to generate one.
     - `LANG`and `LC_CTYPE`: Set both values to `en_US.UTF-8` to ensure proper locale settings and avoid the _native name encoding of latin1 warning_.
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `ECTO_IPV6`: Set the value to `true` to enable your Phoenix app to connect to the database through the [IPv6 private network](/networking/private-networking#listen-on-ipv6).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s an Elixir app](https://nixpacks.com/docs/providers/elixir).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Phoenix apps effortlessly!

## Want to deploy livebook?

[Livebook](https://livebook.dev), an interactive notebook tool built specifically for Elixir, provides a powerful and intuitive environment for exploring data, running code, and documenting insights, all in one place. It’s perfect for experimenting with Elixir code, prototyping, and sharing live documentation.

Click the button below to deploy an instance of Livebook quickly.

[![Deploy Livebook on Railway](https://railway.com/button.svg)](https://railway.com/new/template/4uLt1s)

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Deploy Phoenix with Distillery](/guides/phoenix-distillery)
- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Phoenix app to Railway with this step-by-step guide. It covers quick setup, ecto setup, database integration, one-click deploys and other deployment strategies.

Deploy a Phoenix App

[Play](https://www.playframework.com) is a high velocity and productive web framework for Java and Scala. It is based on a lightweight, stateless, web-friendly architecture and features predictable and minimal resource consumption (CPU, memory, threads) for highly-scalable applications thanks to its reactive model, based on Pekko Streams.

This guide covers how to deploy a Scala Play app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Play app!

## Create a Play app

**Note:** If you already have a Play app locally or on GitHub, you can skip this step and go straight to the [Deploy Play App to Railway](#deploy-the-play-app-to-railway).

To create a new Scala Play app, ensure that you have [JDK](https://www.oracle.com/java/technologies/downloads/) and [sbt](https://www.scala-sbt.org/download/) installed on your machine.

Run the following command in your terminal to create a new Play app:

```bash
sbt new
```

A list of templates will be shown to select from. Select the `playframework/play-scala-seed.g8` template.

- Give it a name, `helloworld`.
- Give it an organization name, `com.railwayguide`
- Hit Enter for the rest to use the latest versions of play, scala and sbt scaffold.

A new Scala Play app will be provisioned in the `helloworld` directory.

### Modify Scala Play views and set up database config

_Step 1_ : Modify the Index File

Open the project in your editor. Head over to the `app/views/index.scala.html` file.

Modify it to the following:

```scala
@()

@main("Welcome to Play") {
  <h1>Welcome to Play!</h1>
  <h1>Hello World, Railway!</h1>
}
```

This change adds a new heading, which you'll see when you run the app locally.

_Step 2_ : Run the App Locally

- Now, let’s run the app locally to verify your changes. You should see the new headers appear in the browser.

_Step 3_ : Add PostgreSQL Driver as a Dependency

Play doesn’t provide built-in database drivers, so you need to add the PostgreSQL JDBC driver manually to your project.

In your `build.sbt`, add the following dependency:

```scala
libraryDependencies += "org.postgresql" % "postgresql" % "42.7.4" // Always use the latest stable version
```

_Step 4_ : Configure PostgreSQL in application.conf

Next, configure the PostgreSQL database connection in `conf/application.conf`:

```scala
# 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
```

Make sure to replace `username` and `password` with your PostgreSQL credentials.

_Step 5_ : Update Project Dependencies

To download the PostgreSQL driver and any updated dependencies, run the following:

```bash
sbt update
```

_Step 6_ : Add Database Migration Tool (Flyway)

Play doesn’t include built-in support for database migrations, so Flyway will be used.

1. Install Flyway Plugin: Open your `project/plugin.sbt` and add the Flyway plugin:

```scala
addSbtPlugin("io.github.davidmweber" % "flyway-sbt" % "7.4.0")
```

2. Configure Flyway in `build.sbt`: Enable Flyway and configure the database connection in your `build.sbt`:

```scala
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=<username>"  # Replace with correct credentials
flywayLocations := Seq("filesystem:src/main/resources/db/migration")
```

Replace `username` with your database username.

_Step 7_ : Create the Migration Files

1. **Create Migration Folder**: Create the folder structure for your migration files:

```bash
src/main/resources/db/migration
```

2. **Create Migration SQL File**: In `src/main/resources/db/migration`, create a schema migration file called `V1_0__create_employees_table.sql` with the following content:

```sql
CREATE TABLE employee (
  id VARCHAR(20) PRIMARY KEY,
  first_name VARCHAR(30),
  last_name VARCHAR(30),
  email VARCHAR(30),
  admin BOOLEAN
);
```

_Step 8_ : Run Database Migrations

Once your migration file is in place, run the Flyway migration with the following command:

```bash
sbt flywayMigrate
```

This will apply the migration and create the employee table in your PostgreSQL database.

Check your database to confirm that the employee table has been successfully created. You can use a database tool like psql or any PostgreSQL client to view the table.

### Run the Play app locally

Next, run `sbt run` in the terminal to build the project, install all the dependencies and start the embedded [Pekko](https://pekko.apache.org) HTTP server.

Open your browser and go to `http://localhost:9000` to see the app.

### Prepare Scala Play app for deployment

1. **Set Application Secret**:
   - Open up the `application.conf` file and add the following to it to set the app's secret.
     ```scala
     play.http.secret.key=${?APPLICATION_SECRET}
     ```
2. **Set Database URL**:
   - Open up the `application.conf` file and add the following to it to ensure the `DATABASE_URL` is read from the environment variable.
     ```scala
     db.default.url="jdbc:${?DATABASE_URL}"
     ```
3. **Set Allowed Hosts**:
   - By default, Play ships with a list of [default Allowed Hosts filter](https://www.playframework.com/documentation/3.0.x/resources/confs/play-filters-helpers/reference.conf). This is the list of allowed valid hosts = ["localhost", ".local", "127.0.0.1"]. You need to add an option to allow Railway hosts, `[".up.railway.app"]`.
   - Add the following to the `application.conf` file:
     `scala
    play.filters.hosts.allowed=[".up.railway.app"]
    `
     **Note:** Railway provided domains end in `.up.railway.app`. Once you add your custom domain, please update the allowed hosts to the new URL.
4. **Add sbt-native-packager sbt plugin**:

   - Add the `sbt-native-packager` sbt plugin to `project/plugins.sbt`
     ```scala
     addSbtPlugin("com.github.sbt" % "sbt-native-packager" % "x.x.x")
     ```
   - Enable the `JavaAppPackaging` plugin in `build.sbt` and set the `executableScriptName` to `main`. Your `build.sbt` should be looking like this now:

     ```scala
     name := """helloworld"""
     organization := "com.railwayguide"

     version := "1.0-SNAPSHOT"

     executableScriptName := "main"

     lazy val root = (project in file(".")).enablePlugins(PlayScala).enablePlugins(JavaAppPackaging).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" // Always use the latest stable version

     flywayUrl := sys.env.getOrElse("DATABASE_URL", "jdbc:postgresql://127.0.0.1:5432/scala_play?user=username")

     flywayLocations := Seq("filesystem:src/main/resources/db/migration")
     ```

   - Run `sbt update` to install the `sbt-native-packager` and update the dependencies.

Now you're ready to deploy to Railway!

## Deploy the Play app to Railway

Railway offers multiple ways to deploy your Scala 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/my9q_q)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=scala" target="_blank">variety of Scala app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Luminus app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:

   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter `APPLICATION_SECRET=<generated-app-secret>` where `<generated-app-secret>` is the secret generated from running `playGenerateSecret` in your terminal.
   - In the `Enter a variable` prompt, enter `DATABASE_URL=${{Postgres.DATABASE_URL}}`.
     - The value, `${{Postgres.DATABASE_URL}}`, references the URL of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).

   **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.

5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731046089/docs/quick-start/scala_on_railway.png"
alt="screenshot of the deployed Scala service"
layout="responsive"
width={1676} height={1490} quality={100} />

### Deploy from a GitHub repo

To deploy a Scala Play app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `APPLICATION_SECRET`: Set the value to the generated app secret.
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s a Scala app](https://nixpacks.com/docs/providers/scala).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the Play app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Scala sbt official image
   # https://hub.docker.com/r/sbtscala/scala-sbt/tags
   FROM sbtscala/scala-sbt:eclipse-temurin-21.0.5_11_1.10.5_3.5.2

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN sbt stage

   # Run the app
   CMD ["./target/universal/stage/bin/main"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Scala apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Scala Play app to Railway with this step-by-step guide. It covers quick setup, database integration, one-click deploys and other deployment strategies.

Deploy a Scala Play App

Learn how to deploy a Rails app to Railway with this step-by-step guide. It covers quick setup, database integration, cron and sidekiq setups, one-click deploys and other deployment strategies.

Deploy a Ruby on Rails App

[React](https://react.dev), also known as React.js or ReactJS, is a popular JavaScript library developed by Meta for building user interfaces, especially for web and native applications.

React simplifies the process of creating interactive and dynamic UIs by breaking them down into reusable components.

This guide covers how to deploy a React app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a React app!

## Create a React app

**Note:** If you already have a React app locally or on GitHub, you can skip this step and go straight to the [Deploy React App on Railway](#deploy-the-react-app-to-railway).

To create a new React app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new React app using [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project):

```bash
npm create vite@latest helloworld -- --template react
```

A new React app will be provisioned for you in the `helloworld` directory.

### Run the React app locally

Next, `cd` into the directory and install the dependencies.

```bash
npm install
```

Start the Vite development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:5173` to see your app.

## Deploy the React app to Railway

Railway offers multiple ways to deploy your React 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. It sets up a React app with [Caddy](https://caddyserver.com) to serve the dist folder.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/NeiLty)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=react" target="_blank">variety of React app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your React app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729182225/docs/quick-start/vite_react_app.png"
alt="screenshot of the deployed React service"
layout="responsive"
width={2431} height={2051} quality={100} />

### Deploy from a GitHub repo

To deploy a React app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or React app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine AS build

   # Set config
   ENV NPM_CONFIG_UPDATE_NOTIFIER=false
   ENV NPM_CONFIG_FUND=false

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Use the Caddy image
   FROM caddy

   # Create and change to the app directory.
   WORKDIR /app

   # Copy Caddyfile to the container image.
   COPY Caddyfile ./

   # Copy local code to the container image.
   RUN caddy fmt Caddyfile --overwrite

   # Copy files to the container image.
   COPY --from=build /app/dist ./dist

   # Use Caddy to run/serve the app
   CMD ["caddy", "run", "--config", "Caddyfile", "--adapter", "caddyfile"]
   ```

   The `Dockerfile` will use Caddy to serve the React app.

3. Add a `Caddyfile` to the app's root directory:

   ```bash
   # global options
   {
       admin off # there's no need for the admin api in railway's environment
       persist_config off # storage isn't persistent anyway
       auto_https off # railway handles https for us, this would cause issues if left enabled
       # runtime logs
       log {
           format json # set runtime log format to json mode
       }
       # server options
       servers {
           trusted_proxies static private_ranges 100.0.0.0/8 # trust railway's proxy
       }
   }

   # site block, listens on the $PORT environment variable, automatically assigned by railway
   :{$PORT:3000} {
       # access logs
       log {
           format json # set access log format to json mode
       }

       # health check for railway
       rewrite /health /*

       # serve from the 'dist' folder (Vite builds into the 'dist' folder)
       root * dist

       # enable gzipping responses
       encode gzip

       # serve files from 'dist'
       file_server

       # if path doesn't exist, redirect it to 'index.html' for client side routing
       try_files {path} /index.html
   }
   ```

4. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your React apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a React app to Railway with this step-by-step guide. It covers quick setup, caddy server setup, one-click deploys and other deployment strategies.

Deploy a React App

[Remix](https://remix.run) is a full-stack web framework that empowers you to build fast, elegant, and resilient user experiences by focusing on the interface and working seamlessly with web standards. Your users will enjoy every moment spent with your product.

This guide covers how to deploy a Remix app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Remix app!

## Create a Remix app

**Note:** If you already have a Remix app locally or on GitHub, you can skip this step and go straight to the [Deploy Remix App on Railway](#deploy-the-remix-app-to-railway).

To create a new Remix app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new Remix app:

```bash
npx create-remix@latest
```

Follow the prompts by giving a directory name, like `helloworld`, where you want your app to be set up. When asked, select **Yes** to automatically install all the necessary dependencies.

A new Remix app will be provisioned for you in the `helloworld` directory.

### Run the Remix app locally

Start the Vite development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:5173` to see your app.

## Deploy the Remix app to Railway

Railway offers multiple ways to deploy your Remix 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/remix)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=remix" target="_blank">variety of Remix app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Vue app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729528294/remix_app_on_railway.png"
alt="screenshot of the deployed Remix service"
layout="responsive"
width={2266} height={2040} quality={100} />

### Deploy from a GitHub repo

To deploy a Remix app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Remix app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Remix apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Remix app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Remix App

[Rocket](https://rocket.rs) is a web framework for Rust that makes it simple to write fast, type-safe, secure web applications with incredible usability, productivity and performance.

This guide covers how to deploy a Rocket app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Rocket app! 🚀

## Create a Rocket app

**Note:** If you already have a Rocket app locally or on GitHub, you can skip this step and go straight to the [Deploy Rocket App to Railway](#deploy-the-rocket-app-to-railway).

To create a new Rocket app, ensure that you have [Rust](https://www.rust-lang.org/tools/install) installed on your machine.

Run the following command in your terminal to create a new Rust app:

```bash
cargo new helloworld --bin
```

The command creates a new binary-based Cargo project in a `helloworld` directory.

Next, `cd` into the directory and add Rocket as a dependency by running the following command:

```bash
cargo add rocket
```

This will add Rocket as a dependency, and you’ll see it listed in your `Cargo.toml` file.

### 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:

```rust
#[macro_use]
extern crate rocket;

#[get("/")]
fn index() -> &'static str {
    "Hello world, Rocket!"
}

#[launch]
fn rocket() -> _ {
    rocket::build().mount("/", routes![index])
}
```

The code above uses the Rocket framework to create a basic web server that responds to HTTP requests. It defines a simple route using the `#[get("/")]` macro, which tells Rocket to handle GET requests to the root URL `(/)`.

The `index()` function is the handler for this route and returns a static string, **"Hello world, Rocket!"**, which will be sent as the response when the root URL is accessed.

The `#[launch]` attribute on the `rocket()` function marks it as the entry point to launch the application. Inside `rocket()`, the server is built with `rocket::build()` and the index route is mounted to the root path `/` using `mount()`.

When the application runs, it listens for incoming requests and serves the "Hello world, Rocket!" response for requests made to the root URL, demonstrating a simple routing and response mechanism in Rocket.

### Run the Rocket app locally

Run the following command in the `helloworld` directory via the terminal:

```bash
cargo run
```

All the dependencies will be installed and your app will be launched.

Open your browser and go to `http://localhost:8000` to see your app.

## Deploy the Rocket app to Railway

Railway offers multiple ways to deploy your Rocket 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/FkW8oU)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=rocket" target="_blank">variety of Rocket templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Rocket app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
4. **Set Up a Public URL**:

   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

   **Note:** You'll come across a 502 error where your application doesn't respond. You'll fix that in the next step.

5. **Configure Rocket app to accept non-local connections**:
   - Rocket apps need to be configured to accept external connections by listening on the correct address, which is typically `0.0.0.0`. You can easily do this by setting the address through the environment variable.
     Run the following command to set the Rocket address to `0.0.0.0`:
     `bash
    railway variables --set "ROCKET_ADDRESS=0.0.0.0"
    `
6. **Redeploy the Service**:
   - Run `railway up` again to trigger a redeployment of the service.
7. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully. Access your public URL again and you should see your app working well.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729858389/docs/quick-start/rocket_app_service.png"
alt="screenshot of the deployed Rocket service"
layout="responsive"
width={2038} height={1698} quality={100} />

### Deploy from a GitHub repo

To deploy a Rocket app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables**:
   - Click **Add Variables**, then add `ROCKET_ADDRESS` with the value `0.0.0.0`. This allows your Rocket app to accept external connections by listening on `0.0.0.0`.
4. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
5. **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](https://nixpacks.com/docs/providers/rust).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Rocket app's root directory.
2. Add the content below to the `Dockerfile`:

   ```docker
   FROM lukemathwalker/cargo-chef:latest-rust-1 AS chef

   # Create and change to the app directory.
   WORKDIR /app

   FROM chef AS planner
   COPY . ./
   RUN cargo chef prepare --recipe-path recipe.json

   FROM chef AS builder
   COPY --from=planner /app/recipe.json recipe.json

   # Build dependencies - this is the caching Docker layer!
   RUN cargo chef cook --release --recipe-path recipe.json

   # Build application
   COPY . ./
   RUN cargo build --release

   CMD ["./target/release/helloworld"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Rocket apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Rust Rocket app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Rust Rocket App

[Sails](https://sailsjs.com) is a MVC framework for Node.js. It is designed to emulate the familiar MVC pattern of frameworks like Ruby on Rails, but with support for the requirements of modern apps: data-driven APIs with a scalable, service-oriented architecture.

Sails makes it easy to build custom, enterprise-grade Node.js apps.

## Create a Sails app

**Note:** If you already have a Sails app locally or on GitHub, you can skip this step and go straight to the [Deploy Sails App on Railway](#deploy-sails-app-on-railway).

To create a new Sails app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to install Sails:

```bash
npm install sails -g
```

Next, run the command below to create a new Sails app

```bash
sails new workapp
```

Select `Web App` as the template for your new Sails app. Once the dependencies have been installed, `cd` into the `workapp` directory and run `sails lift` to start your app.

Open your browser and go to `http://localhost:1337` to see your app.

Now, let's deploy to Railway!

## Deploy Sails app on Railway

Railway offers multiple ways to deploy your Sails app, depending on your setup and preference. Choose any of the following methods:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [Using the CLI](#deploy-from-the-cli).
3. [From a GitHub repository](#deploy-from-a-github-repo).

## One-click deploy from a template

If you’re looking for the fastest way to get started, the one-click deploy option is ideal. It sets up a Sails app along with a Postgres database and Redis.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/t3sAEH)

After deploying, it is recommended that you [eject from the template](/templates/deploy#eject-from-template-repository) to create a copy of the repository under your own GitHub account. This will give you full control over the source code and project.

## Deploy from the CLI

To deploy the Sails app using the Railway CLI, please follow the steps:

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Sails app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Modify Sails Config**:
   - Open up `config/env/production.js` file and make some changes:
     - Set `http.trustProxy` to `true` because your app will be behind a proxy.
     - Set `session.cookie.secure` to `true`
     - Add this function to the `socket` object just after the `onlyAllowOrigins` array:
       ```js
       beforeConnect: function(handshake, proceed) {
         // Send back `true` to allow the socket to connect.
         // (Or send back `false` to reject the attempt.)
         return proceed(undefined, false);
       },
       ```
       **Note:** This is only added because sockets aren't needed now. If you do need sockets, skip this step and add your public app URL to the `onlyAllowOrigins` array. The function simply rejects socket connection attempts.
4. **Deploy the Application**:
   - Use the command below to deploy your app:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.

- **Note:** You'll come across an error about how the default `sails-disk` adapter and `connect.session()` MemoryStore is not designed for use as a production database, don’t worry. You’ll fix this in the next step.

5. **Add PostgreSQL & Redis Database Services**:
   - Run `railway add`.
   - Select `PostgreSQL` by pressing space
   - Select `Redis` by also pressing space and hit **Enter** to add both database services to your project.
6. **Modify Sails Database Config**:
   - Open up the `config/env/production.js` file and make some changes to let your app know what database to connect to and where to save sessions:
     - In the `datastores:` section,
       - Add `adapter: 'sails-postgresql'`,
       - Add `url: process.env.DATABASE_URL`
     - In the `session:` section,
       - Add `adapter: '@sailshq/connect-redis'`,
       - Add `url: process.env.REDIS_URL`,
   - Run `npm install sails-postgresql --save` to add the new adapter to your app locally.
7. **Configure Environment Variables on Railway**:
   - Go to your app service <a href="/overview/the-basics#service-variables">**Variables**</a> section and add the following:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `REDIS_URL`: Set the value to `${{Redis.REDIS_URL}}` (this references the URL of your new Redis Database)
   - Use the **Raw Editor** to add any other required environment variables in one go.
8. **Redeploy the Service**:
   - Click **Deploy** on the Railway dashboard to apply your changes.
9. **Upload Local Changes**:
   - Run `railway up` to upload all the changes you made locally and redeploy your service.
10. **Verify the Deployment**:
    - Once the deployment completes, go to **View logs** to check if the server is running successfully.
11. **Set Up a Public URL**:
    - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
    - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1728580600/docs/quick-start/new_sails_service.png"
alt="screenshot of the deployed Sails service"
layout="responsive"
width={2986} height={2140} quality={100} />

## Deploy from a GitHub repo

To deploy the Sails app to Railway, start by pushing the app to a GitHub repo. Once that’s set up, follow the steps below to complete the deployment process.

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables**:
   - Click **Add Variables** and configure all the necessary environment variables for your app.
4. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
5. **Add a Database Service**:
   - Right-click on the Railway project canvas or click the **Create** button.
   - Select **Database**.
   - Select **Add PostgreSQL** from the available databases.
     - This will create and deploy a new Postgres database service for your project.
6. **Add a Redis Database Service**:
   - Right-click on the Railway project canvas or click the **Create** button.
   - Select **Database**.
   - Select **Add Redis** from the available databases.
     - This will create and deploy a new Redis database service for your project.
7. **Configure Environment Variables**:
   - Go to your app service <a href="/overview/the-basics#service-variables">**Variables**</a> section and add the following:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `REDIS_URL`: Set the value to `${{Redis.REDIS_URL}}` (this references the URL of your new Redis Database)
   - Use the **Raw Editor** to add any other required environment variables in one go.
8. **Modify Sails Config**:
   - Follow [steps 3 & 5 mentioned in the CLI guide](#deploy-from-the-cli).
9. **Redeploy the Service**:
   - Click **Deploy** on the Railway dashboard to apply your changes.
10. **Verify the Deployment**:
    - Once the deployment completes, go to **View logs** to check if the server is running successfully.
11. **Set Up a Public URL**:
    - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
    - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Sails apps effortlessly!

Here’s how your setup should look:

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1728580319/docs/quick-start/all_services_connected.png" alt="Diagram showing all sails services connected on Railway" layout="responsive" width={2985} height={1815} quality={100} />

By following these steps, you’ll have a fully functional Sails app. If you run into any issues or need to make adjustments, check the logs and revisit your environment variable configurations.

## The boring JavaScript stack Sails starter

If you're a fan of [The Boring JavaScript Stack](https://github.com/sailscastshq/boring-stack), there’s a one-click deploy option for you.

Simply click the button below to get started:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/ia84_3)

**Note:** After deploying, it is recommended to [eject from the template](/templates/deploy#eject-from-template-repository) to create your own GitHub repository. This will give you full control over the project and source code.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Sails app to Railway with this step-by-step guide. It covers quick setup, database integration, the Boring JavaScript stack, one-click deploys and other deployment strategies.

Deploy a Sails App

Datadog provides a centralized location for logs, metrics, and traces emitted from applications deployed in various locations.

While Railway has a native, [centralized logging mechanism](/observability/logs#log-explorer), you may have a need to ship this data to another location, to view it alongside data collected from systems outside of Railway.

**Objectives**

In this tutorial you will learn how to -

- Deploy a Datadog agent in Railway - listening for metrics, logs, and traces.
- Configure an application to send metrics, logs, and traces to the agent.

If you are looking for a quicker way to get started, you can also deploy this project from a <a href="https://railway.com/template/saGmYG" target="_blank">template</a>.

**Prerequisites**

To be successful, you should already have -

- Railway [CLI installed](/cli#installing-the-cli)
- Datadog API key and site value

**Caveats**

Keep in mind that the Datadog agent sends data to Datadog over the Internet, meaning you will see an increase in egress cost. If this is a concern, you may be interested in exploring self-hosted solutions, check out the [OpenTelemetry Tutorial](/guides/deploy-an-otel-collector-stack).

## 1. Create the project structure

First, create the project structure.

From your local machine -

- Create a folder for your project called `railway-project`.
- Create two folders inside of `railway-project` called `agent` and `expressapi`.

You project structure should look like this

```
railway-project/
├── agent/
└── expressapi/
```

## 2. Set up the Datadog agent

Now add files to the `agent` folder, which will build the Datadog Agent image.

- Inside of the `agent` folder, create three files -
  - `Dockerfile`
  - `syslog.yaml`
  - `datadog.yaml`

#### Define the Dockerfile

Define the Dockerfile.

- Within your Dockerfile, add the following contents.

  ```dockerfile
  FROM datadog/agent:7

  # Set environment variables
  ENV DD_LOGS_ENABLED=true
  ENV DD_APM_ENABLED=true
  ENV DD_LOGS_CONFIG_CONTAINER_COLLECT_ALL=true
  ENV DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true
  ENV DD_APM_NON_LOCAL_TRAFFIC=true
  ENV DD_BIND_HOST=::1

  # Reference Variables defined in Railway
  ARG DD_API_KEY
  ARG DD_HOSTNAME
  ARG DD_SITE

  # Copy datadog.yaml into the container
  COPY datadog.yaml /etc/datadog-agent/datadog.yaml

  # Copy syslog configuration file
  COPY syslog.yaml /etc/datadog-agent/conf.d/syslog.d/

  # DogStatsD port, APM port, and the syslog port
  EXPOSE 8125/udp
  EXPOSE 8126
  EXPOSE 514/udp
  ```

#### Define the syslog.yaml file

The `syslog.yaml` file is used to instruct the agent to listen for syslogs to be forwarded on the configured port.

- Within the `syslog.yaml` file, add the following contents -

  ```
  logs:
    - type: udp
      port: 514
      service: "node-app"
      source: syslog
  ```

#### Define the datadog.yaml file

The `datadog.yaml` file is used to instruct the agent to send logs to Datadog over `http` instead of the default `tcp`.

- Within the `datadog.yaml` file, add the following contents -

  ```
  logs_config:
    force_use_http: true
  ```

## 3. Set up the Node Express app

Now build a Node Express App that will send logs and metrics to the Datadog Agent over the [Private Network](/networking/private-networking).

- Create an `app.js` file inside of the `expressapi` folder you created in Step 1.
- Use `npm` (or your preferred package manager) to install the required dependencies -

  ```npm
  npm i express winston winston-syslog dd-trace
  ```

#### Define the app.js file

The `app.js` file defines your express server. This is where you will import the DataDog tracer and initialize the StatsD client and the Winston logger, which will send traces, metrics, and logs, respectively, to the Datadog agent.

- Within the `app.js` file, add the following contents -

  ```javascript
  // ** it is important to import the tracer before anything else **
  const tracer = require("dd-trace").init();

  const express = require("express");
  const app = express();

  const StatsD = require("hot-shots");
  const { createLogger, format, transports } = require("winston");
  require("winston-syslog").Syslog;
  const port = process.env.PORT || 3000;

  // Configure the StatsD client
  const statsdClient = new StatsD({
    host: process.env.DD_AGENT_HOST,
    port: process.env.DD_AGENT_STATSD_PORT,
    protocol: "udp",
    cacheDns: true,
    udpSocketOptions: {
      type: "udp6",
      reuseAddr: true,
      ipv6Only: true,
    },
  });

  // Configure Winston logger
  const logger = createLogger({
    level: "info",
    exitOnError: false,
    format: format.json(),
    transports: [
      new transports.Syslog({
        host: process.env.DD_AGENT_HOST,
        port: process.env.DD_AGENT_SYSLOG_PORT,
        protocol: "udp6",
        format: format.json(),
        app_name: "node-app",
      }),
    ],
  });

  app.get("/", (req, res) => {
    // Increment a counter for the root path
    statsdClient.increment("data_dog_example.homepage.hits");
    statsdClient.gauge("data_dog_example.homepage.hits", 124);

    // forward logs from root path
    logger.info("Root route was accessed");

    res.send("Hello World!");
  });

  app.get("/test", (req, res) => {
    // Increment a counter for the test path
    statsdClient.increment("data_dog_example.testpage.hits");

    // forward logs from test path
    logger.info("Test route was accessed");

    res.send("This is the test endpoint!");
  });

  app.listen(port, () => {
    console.log(`Example app listening at port ${port}`);
  });
  ```

#### Winston and hot-shots

In this example app, `Winston` is used as the logger and `hot-shots` as the StatsD client.

- `Winston` is configured using `winston-syslog` to transport **logs** to the Datadog agent via Syslog over `udp6`.
- `hot-shots` is configured to send **metrics** to the Datadog agent over `udp6`.

## 4. Set up the Railway project

Now create the project using the CLI, then create the services and variables from within the project in Railway.

You will need your **Datadog API key** and **Site** value in this step.

If you have not already done so, please [install the CLI](/cli#installing-the-cli) and [authenticate](/cli#authenticating-with-the-cli).

#### Create a project

- In your terminal, run the following command to create a new project -

  ```plaintext
  railway init
  ```

- Name your project `datadog-project` when prompted (you can change this later).

- Open your project in Railway by running the following -

  ```plaintext
  railway open
  ```

#### Create the services

- In Railway, create an Empty Service by clicking `+ New` button in the top right-hand corner and choosing `Empty Service` in the prompt.
- Right click on the service that is created, select `Update Info` and name it `datadog-agent`.
- Repeat the above steps to create a second service, but name the second service `expressapi`.

#### Add the variables

Each service requires unique variables listed below. For each service, follow the steps to add the variables required for the service.

`datadog-agent` Variables -

```plaintext
DD_API_KEY=<YOUR_API_KEY>
DD_HOSTNAME=${{RAILWAY_PRIVATE_DOMAIN}}
DD_SITE=<YOUR_DATADOG_SITE>
```

`expressapi` Variables -

```plaintext
DD_AGENT_HOST=${{datadog-agent.DD_HOSTNAME}}
DD_AGENT_STATSD_PORT=8125
DD_AGENT_SYSLOG_PORT=514
DD_TRACE_AGENT_PORT=8126
```

- Click on the service card
- Click on the `Variables` tab
- Click on `Raw Editor`
- Paste the required variables (be sure to update the Datadog API key and site with your own values)
- Click `Update Variables` and `Deploy`

## 5. Deploy to Railway

Now you're ready to deploy the services. Use the CLI to push code from your local machine to Railway.

#### Railway up

Follow these steps for each service -

- In your local terminal, change directory into the `agent` folder.
- Link to `datadog-project` by running the following command -
  ```plaintext
  railway link
  ```
- Follow the prompts, selecting the `datadog-project` and `production` environment.
- Link to the `datadog-agent` service by running the following command -
  ```plaintext
  railway service
  ```
- Follow the prompt, selecting the `datadog-agent` service.
- Deploy the agent by running the following command -
  ```plaintext
  railway up -d
  ```
- Change directory into your `expressapi` folder and repeat the steps above, but for the `expressapi` service.

#### Create a domain for the Express app

The express app will send logs and metrics to the Datadog agent upon navigation to either of its two routes. So let's give it a domain -

- Ensure that you are linked to the `datadog-project` and `expressapi` service (refer to the steps above)
- Assign the `expressapi` a domain by running the following command -
  ```plaintext
  railway domain
  ```

## 6. Test and confirm

Test that your Datadog Agent is receiving and forwarding data to Datadog by navigating to the routes in the Express app -

- `/`
- `/test`

Generate some traffic to these two routes and verify in your Datadog instance that the data is there.

_Note: it can take a few minutes to see the data in Datadog, check the Datadog Agent's logs in Railway_

## Bonus - add a Python service

Once you have your agent setup and working with a node app. It's easy to add more services and configure the agent to accept data from them. This bonus section quickly covers a Python implementation.

The following example uses the <a href="https://fastapi.tiangolo.com/" target="_blank">FastAPI Python framework</a>.

**In the `main.py` file, both metrics and logs are configured to be sent over StatsD and SysLog respectively -**

```python
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}

```

**Ensure that you configure all of the required variables in the Python service in Railway -**

- DD_AGENT_HOST - _should be the private domain of the DataDog agent_
- DD_API_KEY
- DD_AGENT_STATSD_PORT - _should be 8125_
- DD_AGENT_SYSLOG_PORT - _should be **515** to work with the configuration below_

**Update the DataDog agent's `syslog.yaml` file to accept data from the new source -**

```plaintext
logs:
  - type: udp
    port: 514
    service: "node-app"
    source: syslog
  - type: udp
    port: 515
    service: "python-app"
    source: syslog
```

## Conclusion

Congratulations! You have deployed a Datadog Agent and a Node Express app (and maybe a Python service) that sends logs and metrics to Datadog.

This is a _very_ basic implementation, and you should refer to the <a href="https://docs.datadoghq.com/" target="_blank">Datadog documentation</a> for information on how to customize the data you send.

Learn how to set up a Datadog agent in Railway.

Set Up a Datadog Agent in Railway

## What is a subnet router?

> A subnet router is a device within your tailnet that you use as a gateway that advertises routes for other devices that you want to connect to your tailnet without installing the Tailscale client.

_Source: <a href="https://tailscale.com/kb/1019/subnets" target="_blank">Subnet routers</a> Via Tailscale's Documentation_

In the context of Railway, The "other devices" are the services within a project.

## About this tutorial

This tutorial will help you connect to your database via the private network without you having to use public endpoints.

Since Railway doesn't currently offer a native way to access the <a href="https://docs.railway.com/reference/private-networking" target="_blank">private network</a> from your local environment, you can use a Tailscale Subnet Router to accomplish this.

Deploying Tailscale as a subnet router into your project means that you can access the `railway.internal` private domains from any device connected to your tailnet.

This tutorial aims to provide a simple step-by-step guide on setting up everything needed so that you can access the private domains of your services.

**Objectives**

In this tutorial, you'll learn how to do the following: -

- Generate an Auth Key.
- Set up split DNS.
- Deploy the Tailscale Subnet Router template.
- Approve the private network subnet.
- (Bonus) Connect to Postgres locally via the private domain.

**Prerequisites**

This guide assumes you are familiar with the concepts of Private Network, for a quick explainer check out the <a href="/guides/private-networking" target="_blank">guide</a> and <a href="/reference/private-networking" target="_blank">reference</a> page.

**In Railway -**

- Have all the services you plan on connecting to via the tailnet, listening on `::` (all interfaces).

  This is necessary because the Tailscale tunnel will communicate with your services over Railway's private network.

  All database services already do this but for information on configuring your service to listen on `::`, see [here](/networking/private-networking#service-configuration).

**In Tailscale -**

- Have an account.

  You can sign up <a href="https://login.tailscale.com/start" target="_blank">here</a> - For what this template achieves you do not need a paid plan.

- Have the Tailscale app installed on your computer.

  You can find the downloads for your OS <a href="https://tailscale.com/download" target="_blank">here</a>.

## 1. Getting an auth key

The Auth key will authenticate the Tailscale machine that you'll deploy into your Railway project in a later step.

- Head over to the [Keys](https://login.tailscale.com/admin/settings/keys) page located within the settings menu on the Tailscale dashboard.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349121/docs/tutorials/tailscale-subnet-router/keys_page_vohahp.png"
alt="screenshot of the tailscale settings page"
layout="intrinsic"
width={1261} height={772} quality={100} />

- Click **Generate auth key**.

  Put in a description and leave all other settings as the default.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349121/docs/tutorials/tailscale-subnet-router/generate_auth_key_oxqr8m.png"
alt="screenshot of the generate auth key modal in tailscale"
layout="intrinsic"
width={602} height={855} quality={100} />

- Click **Generate key**.

  Tailscale will now show you the newly generated auth key, **be sure to copy it down**.

- Click **Done**.

## 2. Configure split DNS

Properly configuring the nameserver in Tailscale is essential for enabling local DNS lookups for your private domains.

- Open the <a href="https://login.tailscale.com/admin/dns" target="_blank">DNS</a> page.

- Under the **Nameservers** Header, click **Add Nameserver** → Click **Custom**.

  This is where you'll tell Tailscale how to route the DNS lookups for your `railway.internal` domains.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349122/docs/tutorials/tailscale-subnet-router/tailscale_nameservers_en8oma.png"
alt="screenshot of the nameservers dropdown in tailscale"
layout="intrinsic"
width={813} height={683} quality={100} />

- Enter `fd12::10` as the Nameserver.

  This DNS nameserver is used across all private networks in every environment and will handle your DNS queries for private domains.

- Enable the **Restrict to domain** option, AKA Split DNS.

- Enter in `railway.internal` as the domain.

  This makes sure only DNS lookups for your private domain are forwarded to the private DNS resolver.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349120/docs/tutorials/tailscale-subnet-router/add_nameserver_mlkk5y.png"
alt="screenshot of the add nameserver modal in tailscale"
layout="intrinsic"
width={602} height={572} quality={100} />

- Click **Save**.

## 3. Deploy the Tailscale subnet router

This will be the gateway into your environment's private network.

- Open the project that contains the services you want to access privately.

  For this tutorial, you will deploy the Subnet Router into a project with a Postgres database service.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349122/docs/tutorials/tailscale-subnet-router/project_with_postgres_x19ggr.png"
alt="screenshot of a project canvas on railway showing a single postgres service"
layout="intrinsic"
width={1363} height={817} quality={100} />

- In the top right of the project canvas, click **Create** → Choose **Template**.

- Search for the <a href="https://railway.com/template/tailscale" target="_blank">Tailscale Subnet Router</a> template.

  Choose the result that is published by **Railway Templates**.

<Image src="https://res.cloudinary.com/railway/image/upload/v1743471191/docs/template-tailscale_ryph2o.png"
alt="screenshot of the choose a template modal showing the tailscale template within railway"
layout="intrinsic"
width={1200} height={634} quality={100} />

- A ghost service will appear, Paste in your Auth Key from earlier.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349120/docs/tutorials/tailscale-subnet-router/tailscale_subnet_router_ghost_jjyt2s.png"
alt="screenshot of the tailscale template asking for the auth key"
layout="intrinsic"
width={1363} height={817} quality={100} />

- Click **Deploy Template**

This template will start to deploy and once deployed it will register itself as a machine in your tailnet with the name automatically derived from the project's name and environment name.

## 4. Approve the subnet

Your subnet router will advertise the private network's CIDR range but you will need to manually approve it.

- Head back over to the [Machines dashboard](https://login.tailscale.com/admin/machines).

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349122/docs/tutorials/tailscale-subnet-router/tailscale_machines_d3qcey.png"
alt="screenshot of the machine's dashboard in tailscale that is showing a subnet needs approving"
layout="intrinsic"
width={1261} height={560} quality={100} />

You will see your newly deployed machine with its name that was previously derived from the project and environment.

<div style={{'display': "inline-flex", 'align-items': "center"}}>
    <span style={{ "marginRight": "8px" }}>Notice the</span><strong style={{ "marginRight": "3px" }}>Subnets</strong>
    <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.75" stroke-linecap="round" stroke-linejoin="round" class="ml-1"><circle cx="12" cy="12" r="10"></circle><line x1="12" y1="8" x2="12" y2="12"></line><line x1="12" y1="16" x2="12.01" y2="16"></line></svg>
    <span style={{ "marginLeft": "6px" }}>Info box under the machine name.</span>
</div>

- Click on the machine's 3-dot menu → **Edit route settings**.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349121/docs/tutorials/tailscale-subnet-router/machine_3_dot_menu_ygqktw.png"
alt="screenshot of the machines page in tailscale with the 3-dot menu open and edit route settings selected"
layout="intrinsic"
width={1320} height={593} quality={100} />

- Click the radio button on the `fd12::/16` to accept it.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349120/docs/tutorials/tailscale-subnet-router/edit_route_settings_tyna0n.png"
alt="screenshot of the edit route settings in tailscale showing the route being accepted"
layout="intrinsic"
width={602} height={526} quality={100} />

    This route covers the entire private networking range allowing you to access all services within the project.

- Click **Save**.

- Ensure that the **Use Tailscale subnets** option is enabled in your Tailscale client's Settings or Preferences menu.

**That is it for all the configurations needed, you can now call any service via its private domain and port just as if you were another service within the private network!**

## 5. Connecting to a service on the private network (bonus)

This tutorial has used Postgres as an example service, so let's finally connect to it via its private domain and port!

You can use any database GUI tool you prefer, or none at all, since your setup allows you to connect to the database over the private network using any software.

Example: Your `prisma migrate deploy` or `python manage.py migrate` commands will now work locally without the need to use the public host and port for the database.

<Image src="https://res.cloudinary.com/railway/image/upload/v1724349120/docs/tutorials/tailscale-subnet-router/dbgate_priv_net_mdjnlh.png"
alt="screenshot of dbgate showing a successful connection to the database"
layout="intrinsic"
width={1316} height={506} quality={100} />

_Note the use of the private domain and port in the database URL._

**Additional Resources**

This tutorial explains how to set up a Tailscale Subnet router on Railway but does not delve into all the terminology and settings related to Tailscale.

We recommend reviewing the following Tailscale documentation:

- [Subnet router](https://tailscale.com/kb/1019/subnets)
- [Auth keys](https://tailscale.com/kb/1085/auth-keys)
- [Machine names](https://tailscale.com/kb/1098/machine-names)
- [DNS](https://tailscale.com/kb/1054/dns?q=dns#use-dns-settings-in-the-admin-console)
- [Tailscale FAQ](https://tailscale.com/kb/1366/faq)

Learn how to access a private network on Railway by using a Tailscale Subnet Router.

Set up a Tailscale Subnet Router

[SolidJS](https://www.solidjs.com) is a modern JavaScript library for building responsive and high-performing user interfaces for web applications.

It uses fine-grained reactivity, meaning it updates only when the data your app actually depends on changes. This minimizes unnecessary work, leading to faster load times and a seamless user experience.

This guide covers how to deploy a Solid app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Solid app!

## Create a Solid app

**Note:** If you already have a Solid app locally or on GitHub, you can skip this step and go straight to the [Deploy Solid App on Railway](#deploy-the-solid-app-to-railway).

To create a new Solid app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new Solid app from a template:

```bash
npx degit solidjs/templates/js solidjsapp
```

A new Solid app will be provisioned for you in the `solidjsapp` directory.

### Run the Solid app locally

Next, `cd` into the directory and install the dependencies.

```bash
npm install
```

Start the Vite development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:3000` to see your app.

## Deploy the Solid app to Railway

Railway offers multiple ways to deploy your Solid 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/w5OSVq)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Solid app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/v1741198862/CleanShot_2025-03-05_at_18.19.11_2x_isjut5.png"
alt="screenshot of the deployed Solid service"
layout="responsive"
width={2610} height={2110} quality={100} />

### Deploy from a GitHub repo

To deploy a Solid app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `solidjsapp` or Solid app's root directory.
2. Add the content below to the `Dockerfile`:

   ```dockerfile
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine AS build

   # Set config
   ENV NPM_CONFIG_UPDATE_NOTIFIER=false
   ENV NPM_CONFIG_FUND=false

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Use the Caddy image
   FROM caddy

   # Create and change to the app directory.
   WORKDIR /app

   # Copy Caddyfile to the container image.
   COPY Caddyfile ./

   # Copy local code to the container image.
   RUN caddy fmt Caddyfile --overwrite

   # Copy files to the container image.
   COPY --from=build /app/dist ./dist

   # Use Caddy to run/serve the app
   CMD ["caddy", "run", "--config", "Caddyfile", "--adapter", "caddyfile"]
   ```

   The `Dockerfile` will use Caddy to serve the Solid app.

3. Add a `Caddyfile` to the app's root directory:

   ```bash
   {
       # global options
       admin off # there's no need for the admin api in railway's environment
       persist_config off # storage isn't persistent anyway
       auto_https off # railway handles https for us, this would cause issues if left enabled
       # runtime logs
       log {
           format json # set runtime log format to json mode
       }
       # server options
       servers {
           trusted_proxies static private_ranges 100.0.0.0/8 # trust railway's proxy
       }
   }

   # site block, listens on the $PORT environment variable, automatically assigned by railway
   :{$PORT:3000} {
       # access logs
       log {
           format json # set access log format to json mode
       }

       # health check for railway
       rewrite /health /*

       # serve from the 'dist' folder (Vite builds into the 'dist' folder)
       root * dist

       # enable gzipping responses
       encode gzip

       # serve files from 'dist'
       file_server

       # if path doesn't exist, redirect it to 'index.html' for client side routing
       try_files {path} /index.html
   }
   ```

4. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Solid apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a SolidJS app to Railway with this step-by-step guide. It covers quick setup, one-click deploys and other deployment strategies.

Deploy a SolidJS App

[Spring Boot](https://spring.io/projects/spring-boot) is a Java framework designed to simplify the creation of stand-alone, production-ready Spring applications that are easy to run right out of the box.

This guide covers how to deploy a Spring Boot app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Spring Boot app!

## Create a Spring Boot app

**Note:** If you already have a Spring Boot app locally or on GitHub, you can skip this step and go straight to the [Deploy Spring Boot App to Railway](#deploy-the-spring-boot-app-to-railway).

To create a new Spring Boot app, ensure that you have [JDK](https://www.oracle.com/java/technologies/downloads/) installed on your machine.

Go to [start.spring.io](https://start.spring.io) to initialize a new Spring Boot app. Select the options below to customize and generate your starter app.

- Project: Maven
- Language: Java
- Spring Boot: 3.3.4
- Project Metadata:
  - Group: com.railwayguide
  - Artifact: helloworld
  - Name: helloworld
  - Description: Demo project for Railway Guide
  - Package name: com.railwayguide.helloworld
  - Packaging: jar
  - Java: 17
- Dependencies:
  - Click the **Add Dependencies** button and search for **Spring Web**. Select it.

![Spring Boot App Initializer](https://res.cloudinary.com/railway/image/upload/v1729619101/springboot_app_on_railway.png)
_Config to initialize your new app_

Now, click on the **Generate** button, download the zipped file and unpack it into a folder on your machine.

### Modify the application file

Next, open the app in your IDE and navigate to the `src/main/java/com/railwayguide/helloworld/HelloWorldApplication.java` file.

Replace the content with the code below:

```java
package com.railwayguide.helloworld;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@SpringBootApplication
@RestController
public class HelloworldApplication {

	public static void main(String[] args) {
		SpringApplication.run(HelloworldApplication.class, args);
	}

	@GetMapping("/")
    public String hello() {
      return String.format("Hello world from Java Spring Boot!");
    }

}
```

A `hello()` method was added that returns the response: `Hello world from Java Spring Boot!`.

The `@RestController` annotation designates this class as a web controller, while `@GetMapping("/")` maps the `hello()` method to handle requests sent to the root URL, `/`.

### Run the Spring Boot app locally

Next, `cd` into the `helloworld` directory via the terminal and run the following Maven command:

```bash
./mvnw spring-boot:run
```

**Note:** This is a Maven wrapper for Linux and macOS, which uses a bundled version of Maven from **.mvn/wrapper/maven-wrapper.jar** instead of relying on the system-installed version.

Open your browser and go to `http://localhost:8080` to see your app.

## Deploy the Spring Boot app to Railway

Railway offers multiple ways to deploy your Spring Boot 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/-NFGrr)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=spring boot" target="_blank">variety of Spring Boot app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Spring Boot app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729621960/springboot_service_on_railway.png"
alt="screenshot of the deployed Spring Boot service"
layout="responsive"
width={2172} height={1590} quality={100} />

### Deploy from a GitHub repo

To deploy a Spring Boot app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
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 Java app](https://nixpacks.com/docs/providers/java).

5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Spring Boot app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Eclipse temurin alpine official image
   # https://hub.docker.com/_/eclipse-temurin
   FROM eclipse-temurin:21-jdk-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN ./mvnw -DoutputFile=target/mvn-dependency-list.log -B -DskipTests clean dependency:list install

   # Run the app by dynamically finding the JAR file in the target directory
   CMD ["sh", "-c", "java -jar target/*.jar"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Spring Boot apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Spring Boot app to Railway with this step-by-step guide. It covers quick setup, one-click deploys, Dockerfile and other deployment strategies.

Deploy a Spring Boot App

In this guide, you'll learn how to deploy static websites to Railway with automatic GitHub builds, SSL certificates, and custom domains. All with zero configuration required.

## What is Railway?

Railway is a modern deployment platform that lets you deploy static websites and applications without managing servers, configuring load balancers, or learning complex infrastructure. It provides automatic builds, zero-downtime deployments, and built-in CI/CD.

Learn more about Railway's [core components and foundations](/overview/the-basics).

## Why choose Railway for static hosting?

Railway offers several advantages for static site hosting:

- Zero configuration: Deploy from GitHub without build scripts or complex setup.
- Automatic builds: Every push triggers a new deployment automatically.
- Custom domains: Automatically provisioned SSL certificates and custom domain setup.
- Preview environments: Test changes with automatic PR previews.
- Usage-based pricing: Pay only for what you use, starting at $5/month.
- Private repositories: Deploy from private GitHub repos without additional cost.

## Prerequisites

This is a beginner-friendly guide. You'll need:

- A Railway account
- [Git](https://git-scm.com/) configured and a [GitHub](https://github.com/) account 

## Deploy a static site on Railway from your own GitHub repository

1. Go to [railway.com/new](https://railway.com/new)
2. Select "Deploy from GitHub repo"
3. Connect your GitHub account and choose your repository
4. Railway will automatically detect the build configuration and deploy your site

## Configure a custom domain

Custom domains can be added to any Railway service with automatic SSL certificate provisioning.

1. Navigate to your service settings:
   - In your Railway project, click on your deployed service
   - Go to the "Settings" tab
   - Scroll to the "Networking" section

2. Add your domain:
   - Click the "+ Custom Domain" button
   - Enter your domain (e.g., `example.com`) and specify the target port
   - Railway will provide you with a CNAME record to configure in your DNS provider

![Add a Custom Domain](https://res.cloudinary.com/railway/image/upload/v1758569589/CleanShot_2025-09-22_at_22.32.05_2x_io3eqe.png)

3. Configure DNS:
   - In your DNS provider (Cloudflare, Namecheap, etc.), create a CNAME record
   - Point your domain to the Railway-provided CNAME
   - Wait for verification (usually takes a few minutes but can take up to 72 hours)

4. SSL Certificate:
   - Railway automatically issues and renews SSL certificates
   - Your site will be available at `https://your-domain.com`

Learn more about [custom domains](/networking/public-networking#custom-domains) and [SSL configuration](/networking/public-networking#ssl-certificates) in Railway.

## Set up preview environments for every pull request for your static site

Railway can automatically create preview environments for every pull request, letting you test changes before merging.

1. Configure project settings:
   - Go to your Project Settings → Environments tab
   - Click "Enable PR Environments"

![PR Environments](https://res.cloudinary.com/railway/image/upload/v1758274258/docs/PR_environmetns_q4z0yy.png)

2. Create a feature branch:
   ```bash
   git checkout -b feature/new-page
   # Make your changes
   git add .
   git commit -m "Add new page"
   git push origin feature/new-page
   ```

3. Create a pull request:
   - Once you create a pull request, Railway will automatically deploy a preview environment with a unique URL where you can preview your changes.
   - When the PR is merged or closed, the PR environment is automatically deleted.

Learn more about [using environments](/environments) and [PR environments](/environments#enable-pr-environments).

## Deploy replicas in different regions for global performance

Railway enables you to deploy your static site across multiple regions for improved global performance and availability.

- Reduced latency: Serve content from the region closest to your users
- High availability: If one region experiences issues, traffic automatically routes to healthy regions
- Better performance: Faster loading times for users worldwide
- Automatic failover: Seamless traffic routing without manual intervention

To get started:

1. In your Railway project, click on your deployed service
2. Go to the "Settings" tab
3. Under "Deploy", go to the "Regions" section and click "+ Add Region"

Railway automatically distributes replicas across available regions and routes traffic to the nearest region.

![Multi-region deployment](https://res.cloudinary.com/railway/image/upload/v1758247839/docs/multi-region_deployment_h5fxqz.png)


Each replica runs with the full resource limits of your plan. So if you're on the Pro plan and deploy 3 replicas, you'll get a combined capacity of 72 vCPU and 72 GB RAM across all regions.

```
Total resources = number of replicas × maximum compute allocation per replica
```

Learn more about [scaling applications](/deployments/scaling) and [multi-region deployments](/platform/compare-to-vps#multi-region-deployment) in Railway.

Alternatively, you can integrate a CDN like Cloudflare for global content delivery and improved performance.

## Add Cloudflare as a CDN

While Railway doesn't currently provide a built-in CDN, you can easily integrate a CDN like [Cloudflare](https://www.cloudflare.com/) for global content delivery and improved performance.

1. Add your domain to Cloudflare:
   - Sign up for a free Cloudflare account
   - Add your Railway domain to Cloudflare
   - Update your nameservers as instructed

2. Configure DNS:
   - Create a CNAME record in Cloudflare
   - Point your domain to your Railway service URL
   - Enable "Proxy" (orange cloud) for CDN benefits

3. Verify setup:
   - Test your domain to ensure it's working correctly
   - Monitor performance improvements in Cloudflare's dashboard

## Add API endpoints with Railway functions

For static sites that need lightweight API endpoints, [Railway Functions](/functions) enable you to write and deploy code from the Railway canvas without managing infrastructure or creating a git repository.

Railway Functions are [Services](/services) that run a single file of TypeScript code using the [Bun](https://bun.com/) runtime. They're perfect for:

- Form submissions
- Simple API endpoints
- Webhook handlers
- Cron jobs

1. Add a new service:
   - In your Railway project, click the "+ Create" button
   - Choose "Function" as the service type
   - Deploy

2. Write your function:
   - Click on the "Source Code" tab
   - Write your function code

3. Deploy instantly:
   - Press `Cmd+S` (or `Ctrl+S`) to stage changes
   - Press `Shift+Enter` to deploy
   - Your function is live in seconds

Learn more about [Railway Functions](/functions).

For most static sites, the Hobby plan with included usage is sufficient. You only pay for resources you actually use.

Learn more about [Railway pricing](https://railway.com/pricing) and [usage optimization](/pricing/cost-control).

## Next steps

Now that you've deployed your static site, explore these resources:

- [Add a Database Service](/databases/build-a-database-service) for dynamic content
- [Monitor your application](/observability) with built-in metrics
- [Set up custom domains](/networking/public-networking) and SSL certificates
- [Configure environment variables](/variables) for different environments
- [Use Railway Functions](/functions) for API endpoints
- [Optimize performance](/deployments/optimize-performance) and [usage](/pricing/cost-control)

## Need help?

If you have any questions or run into issues, you can reach out in the [Railway Discord](http://discord.gg/railway) community or on [Central Station](https://station.railway.com/).

Learn how to deploy static websites to Railway with automatic GitHub builds, SSL certificates, custom domains, and integrate with a CDN. Perfect for marketing sites, blogs, and documentation.

Deploy Static Sites with Zero Configuration and Custom Domains

[SvelteKit](https://svelte.dev/docs/kit/introduction) is a framework for rapidly developing robust, performant web applications using Svelte.

This guide covers how to deploy a SvelteKit app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a SvelteKit app!

## Create a SvelteKit app

**Note:** If you already have a SvelteKit app locally or on GitHub, you can skip this step and go straight to the [Deploy SvelteKit App to Railway](#deploy-sveltekit-app-to-railway).

To create a new SvelteKit app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new SvelteKit app using [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project):

```bash
npx sv create svelteapp
```

Follow the prompts:

1. Select the `SvelteKit demo` template.
2. Add typechecking with Typescript.
3. Add prettier, eslint, and tailwindcss.
4. No tailwindcss plugins. Hit enter and move on.
5. Select `npm` as the package manager to install dependencies.

A new SvelteKit app will be provisioned for you in the `svelteapp` directory.

### Run the SvelteKit app locally

Next, `cd` into the directory and start the Vite development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:5173` to see the app. You can play the demo game by visiting the `/sverdle` route.

### Prepare SvelteKit app for deployment

First, enable the SvelteKit Node adapter.

[SvelteKit adapters](https://svelte.dev/docs/kit/adapters) are plugins that take the built app as input and generate output for deployment. These adapters are used to run your project on deployment platforms.

Let's add the Node adapter to the app. Run the command below in your terminal:

```bash
npm i -D @sveltejs/adapter-node
```

Once it is installed, add the adapter to the app's `svelte.config.js` file.

The `svelte.config.js` file should look like this:

```js
import adapter from "@sveltejs/adapter-node";
import { vitePreprocess } from "@sveltejs/vite-plugin-svelte";

/** @type {import('@sveltejs/kit').Config} */
const config = {
  // Consult https://svelte.dev/docs/kit/integrations
  // for more information about preprocessors
  preprocess: vitePreprocess(),

  kit: {
    // adapter-auto only supports some environments, see https://svelte.dev/docs/kit/adapter-auto for a list.
    // If your environment is not supported, or you settled on a specific environment, switch out the adapter.
    // See https://svelte.dev/docs/kit/adapters for more information about adapters.
    adapter: adapter(),
  },
};

export default config;
```

Next, add the start script to the `package.json` file.

Svelte builds your project into a `build` directory. The server starts when the server entry point is executed, which is by default located at `build/index.js`.

Open up the `package.json` file and add the start script. Set it to `node build/index.js` like so:

```js
{
	"name": "svelteapp",
	"version": "0.0.1",
	"type": "module",
	"scripts": {
		"dev": "vite dev",
		"build": "vite build",
		"start": "node build/index.js",
		"preview": "vite preview",
		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
		"format": "prettier --write .",
		"lint": "prettier --check . && eslint ."
	},
	"devDependencies": {
		"@fontsource/fira-mono": "^5.0.0",
		"@neoconfetti/svelte": "^2.0.0",
		"@sveltejs/adapter-auto": "^3.0.0",
		"@sveltejs/adapter-node": "^5.2.9",
		"@sveltejs/kit": "^2.0.0",
		"@sveltejs/vite-plugin-svelte": "^4.0.0",
		"@types/eslint": "^9.6.0",
		"autoprefixer": "^10.4.20",
		"eslint": "^9.7.0",
		"eslint-config-prettier": "^9.1.0",
		"eslint-plugin-svelte": "^2.36.0",
		"globals": "^15.0.0",
		"prettier": "^3.3.2",
		"prettier-plugin-svelte": "^3.2.6",
		"prettier-plugin-tailwindcss": "^0.6.5",
		"svelte": "^5.0.0",
		"svelte-check": "^4.0.0",
		"tailwindcss": "^3.4.9",
		"typescript": "^5.0.0",
		"typescript-eslint": "^8.0.0",
		"vite": "^5.0.3"
	}
}
```

_package.json_

Now you're ready to deploy!

## Deploy the SvelteKit app to Railway

Railway offers multiple ways to deploy your SvelteKit 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:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/svelte-kit)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=sveltekit" target="_blank">variety of Svelte app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your SvelteKit app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1730489695/docs/quick-start/sveltekit_on_railway.png"
alt="screenshot of the deployed SvelteKit service"
layout="responsive"
width={2695} height={2199} quality={100} />

### Deploy from a GitHub repo

To deploy a SvelteKit app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the SvelteKit app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Serve the app
   CMD ["npm", "run", "start"]
   ```

3. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your SvelteKit apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Sveltekit app to Railway with this step-by-step guide. It covers quick setup, adapter configuration, one-click deploys and other deployment strategies.

Deploy a SvelteKit App

[Symfony](https://symfony.com) is a PHP web framework composed of a set of decoupled and reusable components all working together in harmony to create websites and web applications.

This guide covers how to deploy a Symfony app to Railway in three ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).

Now, let's create a Symfony app!

## Create a Symfony app

**Note:** If you already have a Symfony app locally or on GitHub, you can skip this step and go straight to the [Deploy Symfony App to Railway](#deploy-the-symfony-app-to-railway).

To create a new Symfony app, ensure that you have [Composer](https://getcomposer.org/download/), [PHP](https://www.php.net/manual/en/install.php) and [Symfony](https://symfony.com/download) installed on your machine.

Run the following command in your terminal to create a new Symfony app:

```bash
symfony new --webapp apphelloworld
```

A new Symfony app will be provisioned for you in the `apphelloworld` directory.

### Run the Symfony app locally

To start your app, run:

```bash
symfony server:start
```

Once the app is running, open your browser and navigate to `http://localhost:8000` to view it in action.

## Deploy the Symfony app to Railway

Railway offers multiple ways to deploy your Symfony app, depending on your setup and preference.

## One-click deploy from a template

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/4tnH_D)

This template sets up a starter Symfony application along with a Postgres database on Railway. You can also choose from a <a href="https://railway.com/templates?q=symfony" target="_blank">variety of Symfony app templates</a> created by the community.

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

## Deploy from the CLI

If you have your Symfony app locally, you can follow these steps:

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Symfony app directory.
     ```bash
     railway init
     ```
   - Follow the prompts to name your project.
   - After the project is created, click the provided link to view it in your browser.
3. **Add a Postgres Database Service**:
   - Run `railway add -d postgres`.
   - Hit **Enter** to add it to your project.
   - A database service will be added to your Railway project.
4. **Add a Service and Environment Variable**:
   - Run `railway add`.
   - Select `Empty Service` from the list of options.
   - In the `Enter a service name` prompt, enter `app-service`.
   - In the `Enter a variable` prompt, enter `DATABASE_URL=${{Postgres.DATABASE_URL}}`.
     - The value, `${{Postgres.DATABASE_URL}}`, references the URL of your new Postgres database. Learn more about [referencing service variables](/variables#referencing-another-services-variable).
   - Set the other environment variables: - `APP_ENV=prod` - This setting informs Symfony that the app is running in a production environment, optimizing it for performance. - `APP_SECRET=secret` where _secret_ is your generated app secret. - `COMPOSER_ALLOW_SUPERUSER="1"` - This is necessary to allow Composer to run as root, enabling the plugins that Symfony requires during installation. - `NIXPACKS_PHP_ROOT_DIR="/app/public"` - This ensures the Nginx configuration points to the correct [root directory path to serve the app](https://nixpacks.com/docs/providers/php).
     **Note:** Explore the [Railway CLI reference](/cli#add) for a variety of options.
5. **Deploy the Application**:
   - Run `railway up` 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.
   - Once the deployment is complete, proceed to generate a domain for the app service.
6. **Set Up a Public URL**:
   - Run `railway domain` to generate a public URL for your app.
   - Visit the new URL to see your app live in action!

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432139/docs/quick-start/symfony7_on_railway.png"
alt="screenshot of the deployed Symfony service"
layout="responsive"
width={2741} height={2193} quality={100} />

## Deploy from a GitHub repo

To deploy a Symfony app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Add Environment Variables and Provision a Database Service**:
   - Click **Add Variables**, but hold off on adding anything just yet. First, proceed with the next step.
   - Right-click on the Railway project canvas or click the **Create** button, then select **Database** and choose **Add PostgreSQL**.
     - This will create and deploy a new PostgreSQL database for your project.
   - Once the database is deployed, you can return to adding the necessary environment variables:
     - `DATABASE_URL`: Set the value to `${{Postgres.DATABASE_URL}}` (this references the URL of your new Postgres database). Learn more about [referencing service variables](/variables#referencing-another-services-variable).
     - `APP_ENV=prod` - This setting informs Symfony that the app is running in a production environment, optimizing it for performance.
     - `APP_SECRET=secret` where _secret_ is your generated app secret.
     - `COMPOSER_ALLOW_SUPERUSER="1"` - This is necessary to allow Composer to run as root, enabling the plugins that Symfony requires during installation.
     - `NIXPACKS_PHP_ROOT_DIR="/app/public"` - This ensures the Nginx configuration points to the correct [root directory path to serve the app](https://nixpacks.com/docs/providers/php).
4. **Deploy the App Service**:
   - Click **Deploy** on the Railway project canvas to apply your changes.
5. **Verify the Deployment**:

   - Once the deployment completes, go to [**View logs**](/observability/logs#build--deploy-panel) to check if the server is running successfully.

   **Note:** During the deployment process, Railway will automatically [detect that it’s a PHP app via Nixpacks](https://nixpacks.com/docs/providers/php).

6. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

**Note:** The next step shows how to run your Symfony app along with a database, migrations, cron jobs, and workers.

## Set up database, migrations, crons and workers

This setup deploys your Symfony app on Railway, ensuring that your database, scheduled tasks (crons), and queue workers are all fully operational.

The deployment structure follows a "majestic monolith" architecture, where the entire Symfony app is managed as a single codebase but split into four separate services on Railway:

- **App Service**: Handles HTTP requests and user interactions.
- **Cron Service**: Manages scheduled tasks (e.g., sending emails or running reports).
- **Worker Service**: Processes background jobs from the queue.
- **Database Service**: Stores and retrieves your application's data.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432227/docs/quick-start/symfony_architecture.png"
alt="screenshot of the deploy architecture of the Symfony app"
layout="responsive"
width={3294} height={2048} quality={100} />
_My Majestic Monolith Symfony app_

Please follow these steps to get started:

1. Create three bash scripts in the root directory of your Symfony app: `run-app.sh`, `run-worker.sh`, and `run-cron.sh`.

   These scripts will contain the commands needed to deploy and run the app, worker, and cron services for your Symfony app on Railway.

   - Add the content below to the `run-app.sh` file:

     **Note:** This is required to start your app service after the build phase is complete. This script will execute the migrations and then start the Nginx server.

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x run-app.sh`
     # Run migrations, process the Nginx configuration template and start Nginx
     php bin/console doctrine:migrations:migrate --no-interaction && node /assets/scripts/prestart.mjs /assets/nginx.template.conf /nginx.conf && (php-fpm -y /assets/php-fpm.conf & nginx -c /nginx.conf)
     ```

   - Add the content below to the `run-worker.sh` file. This script will run the queue worker:

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x run-worker.sh`

     # This command runs the queue worker.
     php bin/console messenger:consume async --time-limit=3600 --memory-limit=128M &
     ```

   - Symfony doesn't natively include a scheduler. So, please install the [CronBundle](https://github.com/Cron/Symfony-Bundle) to define and run scheduled tasks. With that set up, add the content below to the `run-cron.sh` file:

     ```bash
     #!/bin/bash
     # Make sure this file has executable permissions, run `chmod +x run-cron.sh`

     # This block of code runs the scheduler every minute
     while [ true ]
         do
             echo "Running the scheduler..."
             php bin/console cron:start [--blocking] --no-interaction &
             sleep 60
         done
     ```

2. Create a Postgres Database service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas.</a>
   - Click on **Deploy**.
3. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas.</a>
   - Name the service **App Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a> to configure it.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Add `chmod +x ./run-app.sh && sh ./run-app.sh` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.
   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables required for the Symfony app especially the ones listed below.
     - `APP_ENV=prod`
     - `APP_SECRET=secret` where _secret_ is your generated app secret.
     - `COMPOSER_ALLOW_SUPERUSER="1"` - This is necessary to allow Composer to run as root, enabling the plugins that Symfony requires during installation.
     - `NIXPACKS_PHP_ROOT_DIR="/app/public"` - This ensures the Nginx configuration points to the correct [root directory path to serve the app](https://nixpacks.com/docs/providers/php).
     - `DATABASE_URL=${{Postgres.DATABASE_URL}}` (this references the URL of your Postgres database).
   - Click **Deploy**.
4. Create a new service on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a>.
   - Name the service **Cron Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Add `chmod +x ./run-cron.sh && sh ./run-cron.sh` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.
   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables especially those highlighted already in step 3.
   - Click **Deploy**.
5. Create a new service again on the <a href="/overview/the-basics#project--project-canvas" target="_blank">Project Canvas</a>.
   - Name the service **Worker Service**, and click on <a href="/overview/the-basics#service-settings">**Settings**</a>.
   - Connect your GitHub repo to the **Source Repo** in the **Source** section.
   - Add `chmod +x ./run-worker.sh && sh ./run-worker.sh` to the <a href="/guides/start-command">**Custom Start Command**</a> in the **Deploy** section.
   - Head back to the top of the service and click on <a href="/overview/the-basics#service-variables">**Variables**</a>.
   - Add all the necessary environment variables especially those highlighted already in step 3.
   - Click **Deploy**.

At this point, you should have all three services deployed and connected to the Postgres Database service:

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432227/docs/quick-start/symfony_architecture.png"
alt="screenshot of the deploy architecture of the Symfony app"
layout="responsive"
width={3294} height={2048} quality={100} />

- **Cron Service**: This service should run the cron bundler Scheduler to manage scheduled tasks.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432857/docs/quick-start/cron_service.png"
alt="screenshot of the cron service of the Symfony app"
layout="responsive"
width={2547} height={2057} quality={100} />

- **Worker Service**: This service should be running and ready to process jobs from the queue.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432862/docs/quick-start/worker_service_symfony.png"
alt="screenshot of the worker service of the Symfony app"
layout="responsive"
width={2545} height={2069} quality={100} />

- **App Service**: This service should be running and is the only one that should have a public domain, allowing users to access your application.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1731432139/docs/quick-start/symfony7_on_railway.png"
alt="screenshot of the deployed Symfony service"
layout="responsive"
width={2741} height={2193} quality={100} />
_App service_

**Note:** There is a [community template](https://railway.com/template/4tnH_D) available that demonstrates this deployment approach. You can easily deploy this template and then connect it to your own GitHub repository for your application.

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Monitoring](/observability)
- [Deployments](/deployments)

Learn how to deploy a Symfony app to Railway with this step-by-step guide. It covers quick setup, database integration, cron and workers, one-click deploys and other deployment strategies.

Deploy a Symfony App

When your deployment takes longer than expected or your application feels slow, it helps to understand what's happening behind the scenes. This guide walks you through Railway's deployment process, how to identify where slowdowns occur, and what you can do about them.

## Understanding deployment phases

Every deployment on Railway goes through several distinct phases. Understanding these phases helps you identify where delays are occurring.

### Phase overview

| Phase | What Happens | Typical Duration |
|-------|--------------|------------------|
| **Initialization** | Railway takes a snapshot of your code | Seconds |
| **Build** | Your code is built into a container image | 1-10+ minutes |
| **Pre-Deploy** | Dependencies are checked and volumes are migrated if needed | Seconds to minutes |
| **Deploy** | Container is created and started | 30 seconds to 2 minutes |
| **Network** | Healthchecks run (if configured) | Up to 5 minutes (configurable) |
| **Post-Deploy** | Previous deployment is drained and removed | Seconds |

### Detailed phase breakdown

#### Initialization (snapshot Code)

Railway captures a snapshot of your source code. This is typically fast unless you have an unusually large repository or many files.

#### Build phase

The build phase is often the longest part of a deployment. Railway uses [Railpack](/builds/railpack) (or a [Dockerfile](/builds/dockerfiles) if present) to build your application into a container image.

Common causes of slow builds:
- Large dependency trees (many npm packages, Python dependencies, etc.)
- No build caching (first build or cache invalidation)
- Compiling native extensions
- Large assets being processed

**Tip:** Check the build logs to see which steps are taking the longest.

#### Pre-deploy

This phase handles:
- **Waiting for dependencies**: If your service depends on another service that's also deploying, Railway waits for it to be ready
- **Volume migration**: If you changed your service's region and it has a volume attached, the volume data must be migrated. This can take significant time depending on volume size

#### Deploy (creating containers)

This phase involves:
1. **Pulling the container image** to the compute node
2. **Creating the container** with your configuration
3. **Mounting volumes** if configured
4. **Starting your application**

Large container images take longer to pull. Railway caches images on compute nodes when possible, but the first deployment to a new node requires a full pull.

#### Network (healthchecks)

If you have a [healthcheck](/deployments/healthchecks) configured, Railway queries your healthcheck endpoint until it receives an HTTP 200 response. The default timeout is 300 seconds (5 minutes).

If your application takes time to:
- Initialize database connections
- Load large files into memory
- Warm up caches

...the healthcheck phase will reflect that startup time.

#### Post-deploy (drain instances)

Railway stops and removes the previous deployment. By default, old deployments are given 0 seconds to gracefully shut down (configurable via `RAILWAY_DEPLOYMENT_DRAINING_SECONDS`).

## Is it Railway or my app?

Before diving into optimization, determine whether the slowness is on Railway's side or within your application. In the vast majority of cases, performance issues originate from the application itself, rather than the platform. This could be from inefficient queries, resource constraints, or configuration problems.

### Check Railway status

Visit [status.railway.com](https://status.railway.com) to see if there are any ongoing incidents or degraded performance affecting the platform. If there's a platform-wide issue, it will be reported here. If status shows all systems operational, the issue is almost certainly within your application or its dependencies.

### Check build logs

Build logs show output from the build phase (installing dependencies, compiling code, creating the container image). The deployment view shows each phase with timing information.

Look for:
- Dependency installation steps that take disproportionately long
- Cache misses causing full rebuilds
- Large assets being processed

### Check deployment logs

Deployment logs show your application's stdout/stderr while it's running. These help diagnose runtime issues that occur after your app starts.

Look for:
- Database connection errors or timeouts
- Slow query warnings
- Application exceptions or errors
- Healthcheck failures

### Check your application metrics

Railway provides [metrics](/observability/metrics) for CPU, memory, and network usage. High resource usage can indicate:
- Your application is resource-constrained
- Inefficient code paths
- Memory leaks causing garbage collection pressure

For deeper insights, consider integrating an Application Performance Monitoring (APM) tool like Datadog, New Relic, or open-source alternatives like OpenTelemetry. APM tools provide distributed tracing, helping you identify slow database queries, external API calls, and bottlenecks that Railway's built-in metrics don't capture.

### Analyze HTTP logs

Railway captures detailed HTTP request logs for every request to your service. These logs are invaluable for identifying slow endpoints and understanding request patterns. For complete documentation on log features and filtering syntax, see the [Logs guide](/observability/logs).

**Key fields for performance troubleshooting:**

| Field | Description |
|-------|-------------|
| `totalDuration` | Total time from request received to response sent (ms) |
| `upstreamRqDuration` | Time your application took to respond (ms) |
| `httpStatus` | Response status code |
| `path` | Request path to identify which endpoints are slow |
| `responseDetails` | Error details if the request failed |
| `txBytes` / `rxBytes` | Response and request sizes |

**Finding slow requests:**

Use the log filter syntax to find requests exceeding a duration threshold:

```
@totalDuration:>1000
```

This finds all requests taking longer than 1 second. You can combine filters to narrow down:

```
@totalDuration:>500 @path:/api/users @method:GET
```

**Understanding the timing fields:**

- **`totalDuration`** includes everything: network time to/from the edge, time in the proxy, and your application's response time
- **`upstreamRqDuration`** is specifically how long your application took to respond

If `totalDuration` is high but `upstreamRqDuration` is low, the latency is in the network path (edge routing, DNS). If `upstreamRqDuration` is high, the slowness is in your application.

**Identifying error patterns:**

Filter by status code to find failing requests:

```
@httpStatus:>=500
```

Check `responseDetails` for specific error information, and `upstreamErrors` for details about connection failures to your application.

### Test locally

If your app is slow on Railway but fast locally, consider:
- Are you hitting external services with higher latency?
- Are you using the correct region for your database?
- Is your application configured to use private networking?

## Common causes of slow applications

### Database queries

Slow database queries are one of the most common causes of application latency.

**Symptoms:**
- API endpoints that worked fast are now slow
- Timeouts on specific operations
- High CPU on your database service

**Solutions:**
- Add database indexes for frequently queried columns
- Use connection pooling
- Review slow query logs
- Consider read replicas for read-heavy workloads

### Wrong region configuration

If your application is in one region but your database is in another, every query incurs geographic latency as traffic travels between regions on Railway's network.

**Symptoms:**
- Consistently high latency on all database operations (typically 50-150ms+ per query depending on distance)

**Solutions:**
- Deploy your application in the same region as your database

### Not using private networking

If services within the same project communicate over the public internet instead of [private networking](/networking/private-networking), you add unnecessary latency and incur [egress costs](/pricing/plans#resource-usage-pricing). Private networking is for **server-to-server communication only**. It won't work for requests originating from a user's browser.

**Symptoms:**
- Using public URLs (e.g., `your-app.up.railway.app`) for inter-service communication
- Connection strings using public hostnames
- Unexpectedly high network egress charges on your bill

**Solutions:**
- Use `*.railway.internal` hostnames for service-to-service communication
- Update connection strings to use private networking addresses and ports
- For frontend applications that need to call backend APIs, use private networking from your server-side code (API routes, SSR) while keeping public URLs for client-side browser requests

**Example:**
```javascript
// Server-side code (API routes, SSR): use private networking
const apiUrl = "http://api.railway.internal:3000";

// Client-side code (browser): must use public URL
const apiUrl = "https://api.up.railway.app";
```

### Resource constraints

Your application may be hitting resource limits, causing throttling or OOM (out of memory) kills.

**Symptoms:**
- Application crashes with exit code 137 (OOM killed)
- Consistently high CPU usage at 100%
- Slow response times during high load

**Solutions:**
- Check your [metrics](/observability/metrics) to see actual resource usage
- Adjust [resource limits](/deployments/optimize-performance) if you're consistently hitting them
- Optimize your application's memory and CPU usage
- Consider [horizontal scaling](/deployments/scaling#horizontal-scaling-with-replicas) for stateless workloads

### Large container images

Large images take longer to pull, especially on first deployment to a new compute node.

**Symptoms:**
- "Creating containers" phase takes several minutes
- Large build output size shown in build logs

**Solutions:**
- Use multi-stage Docker builds to reduce final image size
- Use smaller base images (e.g., Alpine variants)
- Exclude unnecessary files with `.dockerignore`
- Remove development dependencies from production builds

### Slow application startup

If your application takes time to initialize, it affects the healthcheck phase duration.

**Symptoms:**
- Healthcheck takes a long time to pass
- Application logs show initialization steps running

**Solutions:**
- Defer non-critical initialization to after the app is ready to serve traffic
- Use lazy loading for heavy dependencies
- Increase healthcheck timeout if startup time is legitimate
- Consider a dedicated healthcheck endpoint that responds before full initialization

## What plan upgrades actually do

Upgrading your plan increases your **resource limits**, not guaranteed performance. Understanding this distinction is important.

### What upgrading provides

| Plan | Per-Replica vCPU Limit | Per-Replica Memory Limit |
|------|------------------------|--------------------------|
| **Hobby** | 8 vCPU | 8 GB |
| **Pro** | 24 vCPU | 24 GB |
| **Enterprise** | Custom | Custom |

Upgrading raises the ceiling on how many resources a single replica can use. Your application only uses what it needs, up to the limit.

### When upgrading helps

Upgrading helps when:
- Your metrics show you're hitting current resource limits
- Your application needs more memory (e.g., processing large datasets)
- You need more CPU for compute-intensive tasks
- You want to run more replicas (higher replica limits on higher plans)

### When upgrading doesn't help

Upgrading won't help when:
- Slowness is caused by external services (databases, APIs)
- Your application has inefficient code
- Network latency is the bottleneck
- You're not actually using your current resource allocation

**Always check your metrics before upgrading.** If your service uses 500MB of memory and 0.5 vCPU, upgrading from Hobby to Pro won't make it faster.

## Edge routing and latency

Railway operates edge proxies in multiple regions. For a complete overview of edge infrastructure, see the [Edge Networking reference](/networking/edge-networking). Understanding how traffic is routed helps diagnose latency issues.

### How edge routing works

When a request comes in:
1. It hits the nearest Railway edge proxy
2. The edge proxy routes it to your service in the configured region
3. Your service processes the request and responds

You can see which edge handled a request via the `X-Railway-Edge` response header.

### Checking the edge header

```bash
curl -I https://your-app.up.railway.app | grep -i X-Railway-Edge
```

The header value shows the region, e.g., `railway/us-west2`.

### Why traffic might hit the wrong edge

- DNS caching: Your local DNS resolver may have cached an old record
- CDN/Proxy interference: Services like Cloudflare route based on their own logic
- Geographic routing: Users in certain regions may be routed suboptimally

### Optimizing for global users

If you have users worldwide, you can use [multi-region replicas](/deployments/scaling#multi-region-replicas) to deploy stateless services closer to your users. Railway automatically routes traffic to the nearest region.

**Note:** Multi-region works well for stateless application servers, but databases typically run in a single region. If your app is deployed globally but your database is in one region, replicas far from the database will still experience latency on database queries. To mitigate this:
- Use application-level caching to reduce database round-trips
- Consider database read replicas in additional regions for read-heavy workloads
- Accept the latency trade-off for writes, which must go to the primary database

### Private networking and edge

Private networking (`*.railway.internal`) bypasses the edge entirely. Services communicate directly within Railway's infrastructure, which is faster than going through the public internet.

## When to contact support

Contact Railway support through [Central Station](https://station.railway.com) if:

- Deployments are consistently slow with no apparent cause
- You see **544 Railway Proxy Error** responses, which indicate a platform-side issue (as opposed to 502 errors, which indicate application issues)
- The status page shows no issues but you're experiencing degraded performance
- You need help optimizing your deployment configuration

**Tip:** When reporting issues, include the `X-Railway-Request-Id` header from affected requests. This unique identifier helps Railway support trace your request through the infrastructure. You can find it in your HTTP response headers.

Learn how to diagnose and fix slow deployments and application performance issues on Railway.

Troubleshooting Slow Deployments and Applications

When your deployment takes longer than expected or your application feels slow, it helps to understand what's happening behind the scenes. This guide walks you through Railway's deployment process, how to identify where slowdowns occur, and what you can do about them.

## Understanding deployment phases

Every deployment on Railway goes through several distinct phases. Understanding these phases helps you identify where delays are occurring.

### Phase overview

| Phase | What Happens | Typical Duration |
|-------|--------------|------------------|
| **Initialization** | Railway takes a snapshot of your code | Seconds |
| **Build** | Your code is built into a container image | 1-10+ minutes |
| **Pre-Deploy** | Dependencies are checked and volumes are migrated if needed | Seconds to minutes |
| **Deploy** | Container is created and started | 30 seconds to 2 minutes |
| **Network** | Healthchecks run (if configured) | Up to 5 minutes (configurable) |
| **Post-Deploy** | Previous deployment is drained and removed | Seconds |

### Detailed phase breakdown

#### Initialization (snapshot Code)

Railway captures a snapshot of your source code. This is typically fast unless you have an unusually large repository or many files.

#### Build phase

The build phase is often the longest part of a deployment. Railway uses [Railpack](/builds/railpack) (or a [Dockerfile](/builds/dockerfiles) if present) to build your application into a container image.

Common causes of slow builds:
- Large dependency trees (many npm packages, Python dependencies, etc.)
- No build caching (first build or cache invalidation)
- Compiling native extensions
- Large assets being processed

**Tip:** Check the build logs to see which steps are taking the longest.

#### Pre-deploy

This phase handles:
- **Waiting for dependencies**: If your service depends on another service that's also deploying, Railway waits for it to be ready
- **Volume migration**: If you changed your service's region and it has a volume attached, the volume data must be migrated. This can take significant time depending on volume size

#### Deploy (creating containers)

This phase involves:
1. **Pulling the container image** to the compute node
2. **Creating the container** with your configuration
3. **Mounting volumes** if configured
4. **Starting your application**

Large container images take longer to pull. Railway caches images on compute nodes when possible, but the first deployment to a new node requires a full pull.

#### Network (healthchecks)

If you have a [healthcheck](/deployments/healthchecks) configured, Railway queries your healthcheck endpoint until it receives an HTTP 200 response. The default timeout is 300 seconds (5 minutes).

If your application takes time to:
- Initialize database connections
- Load large files into memory
- Warm up caches

...the healthcheck phase will reflect that startup time.

#### Post-deploy (drain instances)

Railway stops and removes the previous deployment. By default, old deployments are given 0 seconds to gracefully shut down (configurable via `RAILWAY_DEPLOYMENT_DRAINING_SECONDS`).

## Is it Railway or my app?

Before diving into optimization, determine whether the slowness is on Railway's side or within your application. In the vast majority of cases, performance issues originate from the application itself - inefficient queries, resource constraints, or configuration problems - rather than the platform.

### Check Railway status

Visit [status.railway.com](https://status.railway.com) to see if there are any ongoing incidents or degraded performance affecting the platform. If there's a platform-wide issue, it will be reported here. If status shows all systems operational, the issue is almost certainly within your application or its dependencies.

### Check build logs

Build logs show output from the build phase (installing dependencies, compiling code, creating the container image). The deployment view shows each phase with timing information.

Look for:
- Dependency installation steps that take disproportionately long
- Cache misses causing full rebuilds
- Large assets being processed

### Check deployment logs

Deployment logs show your application's stdout/stderr while it's running. These help diagnose runtime issues that occur after your app starts.

Look for:
- Database connection errors or timeouts
- Slow query warnings
- Application exceptions or errors
- Healthcheck failures

### Check your application metrics

Railway provides [metrics](/observability/metrics) for CPU, memory, and network usage. High resource usage can indicate:
- Your application is resource-constrained
- Inefficient code paths
- Memory leaks causing garbage collection pressure

For deeper insights, consider integrating an Application Performance Monitoring (APM) tool like Datadog, New Relic, or open-source alternatives like OpenTelemetry. APM tools provide distributed tracing, helping you identify slow database queries, external API calls, and bottlenecks that Railway's built-in metrics don't capture.

### Analyze HTTP logs

Railway captures detailed HTTP request logs for every request to your service. These logs are invaluable for identifying slow endpoints and understanding request patterns. For complete documentation on log features and filtering syntax, see the [Logs guide](/observability/logs).

**Key fields for performance troubleshooting:**

| Field | Description |
|-------|-------------|
| `totalDuration` | Total time from request received to response sent (ms) |
| `upstreamRqDuration` | Time your application took to respond (ms) |
| `httpStatus` | Response status code |
| `path` | Request path - identify which endpoints are slow |
| `responseDetails` | Error details if the request failed |
| `txBytes` / `rxBytes` | Response and request sizes |

**Finding slow requests:**

Use the log filter syntax to find requests exceeding a duration threshold:

```
@totalDuration:>1000
```

This finds all requests taking longer than 1 second. You can combine filters to narrow down:

```
@totalDuration:>500 @path:/api/users @method:GET
```

**Understanding the timing fields:**

- **`totalDuration`** includes everything: network time to/from the edge, time in the proxy, and your application's response time
- **`upstreamRqDuration`** is specifically how long your application took to respond

If `totalDuration` is high but `upstreamRqDuration` is low, the latency is in the network path (edge routing, DNS). If `upstreamRqDuration` is high, the slowness is in your application.

**Identifying error patterns:**

Filter by status code to find failing requests:

```
@httpStatus:>=500
```

Check `responseDetails` for specific error information, and `upstreamErrors` for details about connection failures to your application.

### Test locally

If your app is slow on Railway but fast locally, consider:
- Are you hitting external services with higher latency?
- Are you using the correct region for your database?
- Is your application configured to use private networking?

## Common causes of slow applications

### Database queries

Slow database queries are one of the most common causes of application latency.

**Symptoms:**
- API endpoints that worked fast are now slow
- Timeouts on specific operations
- High CPU on your database service

**Solutions:**
- Add database indexes for frequently queried columns
- Use connection pooling
- Review slow query logs
- Consider read replicas for read-heavy workloads

### Wrong region configuration

If your application is in one region but your database is in another, every query incurs geographic latency as traffic travels between regions on Railway's network.

**Symptoms:**
- Consistently high latency on all database operations (typically 50-150ms+ per query depending on distance)

**Solutions:**
- Deploy your application in the same region as your database

### Not using private networking

If services within the same project communicate over the public internet instead of [private networking](/private-networking), you add unnecessary latency and incur [egress costs](/pricing/plans#resource-usage-pricing). Private networking is for **server-to-server communication only** - it won't work for requests originating from a user's browser.

**Symptoms:**
- Using public URLs (e.g., `your-app.up.railway.app`) for inter-service communication
- Connection strings using public hostnames
- Unexpectedly high network egress charges on your bill

**Solutions:**
- Use `*.railway.internal` hostnames for service-to-service communication
- Update connection strings to use private networking addresses and ports
- For frontend applications that need to call backend APIs, use private networking from your server-side code (API routes, SSR) while keeping public URLs for client-side browser requests

**Example:**
```javascript
// Server-side code (API routes, SSR): use private networking
const apiUrl = "http://api.railway.internal:3000";

// Client-side code (browser): must use public URL
const apiUrl = "https://api.up.railway.app";
```

### Resource constraints

Your application may be hitting resource limits, causing throttling or OOM (out of memory) kills.

**Symptoms:**
- Application crashes with exit code 137 (OOM killed)
- Consistently high CPU usage at 100%
- Slow response times during high load

**Solutions:**
- Check your [metrics](/observability/metrics) to see actual resource usage
- Adjust [resource limits](/deployments/optimize-performance) if you're consistently hitting them
- Optimize your application's memory and CPU usage
- Consider [horizontal scaling](/deployments/scaling#horizontal-scaling-with-replicas) for stateless workloads

### Large container images

Large images take longer to pull, especially on first deployment to a new compute node.

**Symptoms:**
- "Creating containers" phase takes several minutes
- Large build output size shown in build logs

**Solutions:**
- Use multi-stage Docker builds to reduce final image size
- Use smaller base images (e.g., Alpine variants)
- Exclude unnecessary files with `.dockerignore`
- Remove development dependencies from production builds

### Slow application startup

If your application takes time to initialize, it affects the healthcheck phase duration.

**Symptoms:**
- Healthcheck takes a long time to pass
- Application logs show initialization steps running

**Solutions:**
- Defer non-critical initialization to after the app is ready to serve traffic
- Use lazy loading for heavy dependencies
- Increase healthcheck timeout if startup time is legitimate
- Consider a dedicated healthcheck endpoint that responds before full initialization

## What plan upgrades actually do

Upgrading your plan increases your **resource limits**, not guaranteed performance. Understanding this distinction is important.

### What upgrading provides

| Plan | Per-Replica vCPU Limit | Per-Replica Memory Limit |
|------|------------------------|--------------------------|
| **Hobby** | 8 vCPU | 8 GB |
| **Pro** | 32 vCPU | 32 GB |
| **Enterprise** | Custom | Custom |

Upgrading raises the ceiling on how many resources a single replica can use. Your application only uses what it needs, up to the limit.

### When upgrading helps

Upgrading helps when:
- Your metrics show you're hitting current resource limits
- Your application needs more memory (e.g., processing large datasets)
- You need more CPU for compute-intensive tasks
- You want to run more replicas (higher replica limits on higher plans)

### When upgrading doesn't help

Upgrading won't help when:
- Slowness is caused by external services (databases, APIs)
- Your application has inefficient code
- Network latency is the bottleneck
- You're not actually using your current resource allocation

**Always check your metrics before upgrading.** If your service uses 500MB of memory and 0.5 vCPU, upgrading from Hobby to Pro won't make it faster.

## Edge routing and latency

Railway operates edge proxies in multiple regions. For a complete overview of edge infrastructure, see the [Edge Networking reference](/networking/edge-networking). Understanding how traffic is routed helps diagnose latency issues.

### How edge routing works

When a request comes in:
1. It hits the nearest Railway edge proxy
2. The edge proxy routes it to your service in the configured region
3. Your service processes the request and responds

You can see which edge handled a request via the `X-Railway-Edge` response header.

### Checking the edge header

```bash
curl -I https://your-app.up.railway.app | grep -i X-Railway-Edge
```

The header value shows the region, e.g., `railway/us-west2`.

### Why traffic might hit the wrong edge

- DNS caching: Your local DNS resolver may have cached an old record
- CDN/Proxy interference: Services like Cloudflare route based on their own logic
- Geographic routing: Users in certain regions may be routed suboptimally

### Optimizing for global users

If you have users worldwide, you can use [multi-region replicas](/deployments/scaling#multi-region-replicas) to deploy stateless services closer to your users. Railway automatically routes traffic to the nearest region.

**Note:** Multi-region works well for stateless application servers, but databases typically run in a single region. If your app is deployed globally but your database is in one region, replicas far from the database will still experience latency on database queries. To mitigate this:
- Use application-level caching to reduce database round-trips
- Consider database read replicas in additional regions for read-heavy workloads
- Accept the latency trade-off for writes, which must go to the primary database

### Private networking and edge

Private networking (`*.railway.internal`) bypasses the edge entirely. Services communicate directly within Railway's infrastructure, which is faster than going through the public internet.

## When to contact support

Contact Railway support through [Central Station](https://station.railway.com) if:

- Deployments are consistently slow with no apparent cause
- You see **544 Railway Proxy Error** responses, which indicate a platform-side issue (as opposed to 502 errors, which indicate application issues)
- The status page shows no issues but you're experiencing degraded performance
- You need help optimizing your deployment configuration

**Tip:** When reporting issues, include the `X-Railway-Request-Id` header from affected requests. This unique identifier helps Railway support trace your request through the infrastructure. You can find it in your HTTP response headers.

[Vue](https://vuejs.org), also known as Vue.js or VueJS, is a popular JavaScript library for building snappy, performant and versatile user interfaces for web applications.

Vue prides itself as **The Progressive JavaScript Framework**.

This guide covers how to deploy a Vue app to Railway in four ways:

1. [One-click deploy from a template](#one-click-deploy-from-a-template).
2. [From a GitHub repository](#deploy-from-a-github-repo).
3. [Using the CLI](#deploy-from-the-cli).
4. [Using a Dockerfile](#use-a-dockerfile).

Now, let's create a Vue app!

## Create a Vue app

**Note:** If you already have a Vue app locally or on GitHub, you can skip this step and go straight to the [Deploy Vue App on Railway](#deploy-the-vue-app-to-railway).

To create a new Vue app, ensure that you have [Node](https://nodejs.org/en/learn/getting-started/how-to-install-nodejs) installed on your machine.

Run the following command in your terminal to create a new Vue app using [Vite](https://vite.dev/guide/#scaffolding-your-first-vite-project):

```bash
npm create vue@latest
```

You'll be presented with choices for different options in the prompts. Give the app a name, `helloworld` and answer `Yes` to the other options or select what you want.

A new Vue app will be provisioned for you in the `helloworld` directory.

### Run the Vue app locally

Next, `cd` into the directory and install the dependencies.

```bash
npm install
```

Start the Vite development server by running the following command:

```bash
npm run dev
```

Open your browser and go to `http://localhost:5173` to see your app.

## Deploy the Vue app to Railway

Railway offers multiple ways to deploy your Vue 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. It sets up a Vue app with [Caddy](https://caddyserver.com) to serve the dist folder.

Click the button below to begin:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/new/template/Qh0OAU)

It is highly recommended that [you eject from the template after deployment](/templates/deploy#eject-from-template-repository) to create a copy of the repo on your GitHub account.

**Note:** You can also choose from a <a href="https://railway.com/templates?q=vue" target="_blank">variety of Vue app templates</a> created by the community.

### Deploy from the CLI

1. **Install the Railway CLI**:
   - <a href="/guides/cli#installing-the-cli" target="_blank">Install the CLI</a> and <a href="/guides/cli#authenticating-with-the-cli" target="_blank">authenticate it</a> using your Railway account.
2. **Initialize a Railway Project**:
   - Run the command below in your Vue app directory.
     ```bash
     railway init
     ```
   - 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:
     ```bash
     railway up
     ```
   - This command will scan, compress and upload your app's files to Railway. You’ll see real-time deployment logs in your terminal.
   - Once the deployment completes, go to **View logs** to check if the service is running successfully.
4. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

<Image src="https://res.cloudinary.com/railway/image/upload/f_auto,q_auto/v1729252336/docs/quick-start/vue_app_on_railway.png"
alt="screenshot of the deployed Vue service"
layout="responsive"
width={2642} height={2080} quality={100} />

### Deploy from a GitHub repo

To deploy a Vue app to Railway directly from GitHub, follow the steps below:

1. **Create a New Project on Railway**:
   - Go to <a href="https://railway.com/new" target="_blank">Railway</a> to create a new project.
2. **Deploy from GitHub**:
   - Select **Deploy from GitHub repo** and choose your repository.
     - If your Railway account isn’t linked to GitHub yet, you’ll be prompted to do so.
3. **Deploy the App**:
   - Click **Deploy** to start the deployment process.
   - Once the deployed, a Railway [service](/services) will be created for your app, but it won’t be publicly accessible by default.
4. **Verify the Deployment**:
   - Once the deployment completes, go to **View logs** to check if the server is running successfully.
5. **Set Up a Public URL**:
   - Navigate to the **Networking** section under the [Settings](/overview/the-basics#service-settings) tab of your new service.
   - Click [Generate Domain](/networking/public-networking#railway-provided-domain) to create a public URL for your app.

### Use a Dockerfile

1. Create a `Dockerfile` in the `helloworld` or Vue app's root directory.
2. Add the content below to the `Dockerfile`:

   ```bash
   # Use the Node alpine official image
   # https://hub.docker.com/_/node
   FROM node:lts-alpine AS build

   # Set config
   ENV NPM_CONFIG_UPDATE_NOTIFIER=false
   ENV NPM_CONFIG_FUND=false

   # Create and change to the app directory.
   WORKDIR /app

   # Copy the files to the container image
   COPY package*.json ./

   # Install packages
   RUN npm ci

   # Copy local code to the container image.
   COPY . ./

   # Build the app.
   RUN npm run build

   # Use the Caddy image
   FROM caddy

   # Create and change to the app directory.
   WORKDIR /app

   # Copy Caddyfile to the container image.
   COPY Caddyfile ./

   # Copy local code to the container image.
   RUN caddy fmt Caddyfile --overwrite

   # Copy files to the container image.
   COPY --from=build /app/dist ./dist

   # Use Caddy to run/serve the app
   CMD ["caddy", "run", "--config", "Caddyfile", "--adapter", "caddyfile"]
   ```

   The `Dockerfile` will use Caddy to serve the Vue app.

3. Add a `Caddyfile` to the app's root directory:

   ```bash
   # global options
   {
       admin off # there's no need for the admin api in railway's environment
       persist_config off # storage isn't persistent anyway
       auto_https off # railway handles https for us, this would cause issues if left enabled
       # runtime logs
       log {
           format json # set runtime log format to json mode
       }
       # server options
       servers {
           trusted_proxies static private_ranges 100.0.0.0/8 # trust railway's proxy
       }
   }

   # site block, listens on the $PORT environment variable, automatically assigned by railway
   :{$PORT:3000} {
       # access logs
       log {
           format json # set access log format to json mode
       }

       # health check for railway
       rewrite /health /*

       # serve from the 'dist' folder (Vite builds into the 'dist' folder)
       root * dist

       # enable gzipping responses
       encode gzip

       # serve files from 'dist'
       file_server

       # if path doesn't exist, redirect it to 'index.html' for client side routing
       try_files {path} /index.html
   }
   ```

4. Either deploy via the CLI or from GitHub.

Railway automatically detects the `Dockerfile`, [and uses it to build and deploy the app.](/builds/dockerfiles)

**Note:** Railway supports also <a href="/guides/services#deploying-a-public-docker-image" target="_blank">deployment from public and private Docker images</a>.

This guide covers the main deployment options on Railway. Choose the approach that suits your setup, and start deploying your Vue apps seamlessly!

## Next steps

Explore these resources to learn how you can maximize your experience with Railway:

- [Add a Database Service](/databases/build-a-database-service)
- [Monitor your app](/observability)

Learn how to deploy a Vue app to Railway with this step-by-step guide. It covers quick setup, caddy server setup, one-click deploys, Dockerfile and other deployment strategies.

Guides

Add a CDN using Amazon CloudFront

Deploy an Angular App

Deploy an Astro App

Deploy a Rust Axum App

Deploy a Beego App

Create a Bridge from Railway to AWS RDS with Tailscale

Deploy an OpenTelemetry Collector and Backend on Railway

Deploy Node.js & Express API with Autoscaling, Secrets, and Zero Downtime

Deploying a Monorepo to Railway

Deploy a Django App

Deploy an Express App

Deploy a FastAPI App

Deploy a Fastify App

Deploy a Flask App

Welcome to Railway Tutorials!

Deploy a Gin App

GitHub Actions Post-Deploy

GitHub Actions PR Environment

GitHub Actions Self Hosted Runners

Deploy a Laravel App

Deploy a Lovable App on Railway

Deploy a Clojure Luminus App

Deploy a NestJS App

Deploy a Nuxt App

Deploy a Phoenix App with Distillery

Deploy a Phoenix App

Deploy a Scala Play App

Deploy a Ruby on Rails App

Deploy a React App

Deploy a Remix App

Deploy a Rust Rocket App

Deploy a Sails App

Set Up a Datadog Agent in Railway

Set up a Tailscale Subnet Router

Deploy a SolidJS App

Deploy a Spring Boot App

Deploy Static Sites with Zero Configuration and Custom Domains

Deploy a SvelteKit App

Deploy a Symfony App

Deploy a Vue App

Manage Domains with the Public API

Manage Environments with the Public API

Manage Volumes with the Public API

Troubleshooting Slow Deployments and Applications

Troubleshooting Slow Deployments and Applications