Railway

Railway is a cloud development platform that streamlines building and deploying applications with built-in support for databases and services. It offers an intuitive interface and automates infrastructure.

Prerequisites

To deploy to Railway using Wasp CLI:

1. Create a Railway account,

2. Install the railway CLI on your machine.

Deploying

Using the Wasp CLI, you can easily deploy a new app to Railway with a single command:

wasp deploy railway launch my-wasp-app

Please do not CTRL-C or exit your terminal while the commands are running.

Keep in mind that:

1. Your project name (for example my-wasp-app) must be unique across all your Railway projects or deployment will fail (this is a current limitation of the Wasp CLI and Railway integration #2926).

2. If you are a member of multiple Railway organizations, the CLI will prompt you to select the organization under which you want to deploy your app.

The project name is used as a base for your app's service name on Railway:

• my-wasp-app-server

Your service keeps the -server suffix for historical reasons: it used to be one of two services, the one serving your API. It now serves your whole app, pages included.

Railway doesn't allow setting the database service name using the Railway CLI. It will always be named Postgres. This also applies when using the --db-image flag.

Coming From an Older Wasp Version?

Wasp used to deploy your pages as a service of their own, called my-wasp-app-client. Your app now serves its own pages, so nothing is deployed to that service anymore.

Once your users are on your app's URL, you can remove it from your Railway project. Wasp reminds you about it when you run setup or deploy.

When you run the launch command, Wasp CLI knows what your Wasp app needs to run, so it sets up the required environment variables for it:

1. WASP_SERVER_URL and WASP_WEB_CLIENT_URL, both set to your app's own URL, since one app serves both your pages and your API.
2. DATABASE_URL which is required to connect your app to the database.
3. JWT_SECRET which is required for authentication to work.

If you have any additional environment variables that your app needs, read how to set them in the API Reference section.

If you want to automate the deployment process, check out the CI/CD Deployment page to re-deploy your app on each commit as part of your CI/CD pipeline.

Using a Custom Domain For Your App

Setting up a custom domain is a three-step process:

1. Add your domain to your app's Railway service:

   • Go into the Railway dashboard.
   • Select your project (for example my-wasp-app).
   • Click on your app's service (for example my-wasp-app-server).
   • Go to the Settings tab and click Custom Domain.
   • Enter your domain name (for example mycoolapp.com) and port 8080.
   • Click Add Domain.

2. Update the DNS records for your domain, adding a CNAME record at the domain or subdomain you want, pointing to the address you've been given in the previous step. This step depends on your domain provider, consult their documentation in case of doubt.

3. Tell your app about its new URL, by setting it as the WASP_SERVER_URL and WASP_WEB_CLIENT_URL environment variables (for example https://mycoolapp.com) in the Railway dashboard.

   • Go into the Railway dashboard.
   • Select your project (for example my-wasp-app).
   • Click on your app's service (for example my-wasp-app-server).
   • Go to the Variables tab.

   Update both the WASP_SERVER_URL and the WASP_WEB_CLIENT_URL variables with your new domain.

   Wasp builds links from these: the ones in the emails your app sends, and the ones it redirects OAuth logins to. WASP_WEB_CLIENT_URL defaults to WASP_SERVER_URL, but setup sets both, so you update both.

That's it, your app should be available at https://mycoolapp.com!

API Reference

The launch command

launch is a convenience command that runs setup and deploy in sequence.

wasp deploy railway launch <project-name>

It accepts the following arguments:

• <project-name> required

  The name of your project.

Running wasp deploy railway launch is the same as running the following commands:

wasp deploy railway setup <project-name>
wasp deploy railway deploy <project-name>

Using a custom PostgreSQL database

By default, Wasp uses the standard PostgreSQL image provided by Railway when creating a new database for your app. However, if your application requires specific PostgreSQL extensions (e.g., PostGIS), you can specify a Docker image with a custom PostgreSQL installation, with the --db-image <docker-image> flag.

tip

You only need to specify the Docker image once, when first creating the app.

# Use PostGIS:
wasp deploy railway launch my-wasp-app --db-image postgis/postgis

# Use pgvector:
wasp deploy railway launch my-wasp-app --db-image pgvector/pgvector:pg16

The service name will always be Postgres, regardless of the image used.

Explicitly providing the Railway project ID

By default, Wasp CLI tries to create a new Railway project named <project-name>. If you want to use an existing Railway project, pass its ID with --existing-project-id option:

wasp deploy railway launch <project-name> --existing-project-id <railway-project-id>

Explicitly providing the Railway Workspace

By default, Wasp CLI will prompt you to select a Railway workspace for your project. If you want to skip the prompt and provide the workspace id or name directly, use the --workspace option:

wasp deploy railway launch <project-name> --workspace <railway-workspace-id-or-name>

Environment Variables

Server

If you are deploying an app that requires any other environment variables (like social auth secrets), you can set them with the --server-secret option:

wasp deploy railway launch my-wasp-app --server-secret GOOGLE_CLIENT_ID=<...> --server-secret GOOGLE_CLIENT_SECRET=<...>

Client

Client-side environment variables are part of your app's pages and assets, so they can't be set on the deployed app. Read more about it in the Client Environment Variables section.

Custom Server URL

One app serves both your pages and your API, so your pages look for the API on their own origin. There is nothing to point anywhere, not even when you use a custom domain.

The --custom-server-url option is left over from when the client and the server were deployed as two separate apps. It no longer has any effect, so you can drop it from your deployment scripts:

# The option is ignored:
wasp deploy railway launch my-wasp-app --custom-server-url https://api.myapp.com

If you really do serve your API from another origin, that's the REACT_APP_API_URL client environment variable, which is baked into your pages when they are built.

The deploy command

The deploy command deploys your app to Railway.

wasp deploy railway deploy <project-name>

It accepts the following arguments:

• <project-name> required

  The name of your project.

Run this command whenever you want to update your deployed app with the latest changes:

wasp deploy railway deploy <project-name>

Explicitly providing the Railway project ID

When you run the deploy command, Wasp CLI will use the Railway project that's linked to the Wasp project directory. If no Railway project is linked, the command will fail asking you to run the setup command first.

If you are deploying your Railway app in the CI, you can pass the --existing-project-id option to tell Wasp CLI the Railway project ID to use for the deployment:

wasp deploy railway deploy <project-name> --existing-project-id <railway-project-id>

Other Available Options

• --skip-server - do not deploy the app
• --skip-client - deprecated and ignored, since your app serves its own pages and there is no separate client to deploy

If you've added any client-side environment variables to your app, this command can't get them into your app's pages and assets. Read more about it in the Client Environment Variables section.

Custom Server URL

One app serves both your pages and your API, so your pages look for the API on their own origin. There is nothing to point anywhere, not even when you use a custom domain.

The --custom-server-url option is left over from when the client and the server were deployed as two separate apps. It no longer has any effect, so you can drop it from your deployment scripts:

# The option is ignored:
wasp deploy railway deploy my-wasp-app --custom-server-url https://api.myapp.com

If you really do serve your API from another origin, that's the REACT_APP_API_URL client environment variable, which is baked into your pages when they are built.

The setup command

The setup command creates your app's service and its database service on Railway. It also configures environment variables. It does not deploy your app.

wasp deploy railway setup <project-name>

It accepts the following arguments:

• <project-name>

  the name of your project.

The project name is used as a base for your app's service name on Railway:

• <project-name>-server

Railway also creates a PostgreSQL database service named Postgres.

Using a custom PostgreSQL database

By default, Wasp uses the standard PostgreSQL image provided by Railway when creating a new database for your app. However, if your application requires specific PostgreSQL extensions (e.g., PostGIS), you can specify a Docker image with a custom PostgreSQL installation, with the --db-image <docker-image> flag.

tip

You only need to specify the Docker image once, when first creating the app.

# Use PostGIS:
wasp deploy railway setup my-wasp-app --db-image postgis/postgis

# Use pgvector:
wasp deploy railway setup my-wasp-app --db-image pgvector/pgvector:pg16

The service name will always be Postgres, regardless of the image used.

Explicitly providing the Railway project ID

By default, Wasp CLI tries to create a new Railway project named <project-name>. If you want to use an existing Railway project, pass its ID with --existing-project-id option:

wasp deploy railway setup <project-name> --existing-project-id <railway-project-id>

Explicitly providing the Railway Workspace

By default, Wasp CLI will prompt you to select in which Railway workspace you want to create your project. If you want to skip the prompt and provide the workspace id or name directly, use the --workspace option:

wasp deploy railway setup <project-name> --workspace <railway-workspace-id-or-name>

Execute Only Once

You should only run setup once per app. Wasp CLI skips creating the services if they already exist.

Environment Variables

Server Secrets

If your app requires any other server-side environment variables (like social auth secrets), you can set them:

1. Initially in the launch or setup commands with the --server-secret option
2. After the app has already been deployed, go into the Railway dashboard and set them in the Variables tab of your app's service.

Client Environment Variables

Your client-side environment variables end up inside your app's pages and assets, so they have to be there when your app's image is built, not when it runs. Railway builds that image for you, and wasp deploy has no way of passing them to that build yet.

Until it does, if your app needs any REACT_APP_* variable, build the image yourself with the WASP_CLIENT_ENV build argument and deploy it as described on the Cloud Providers page:

docker build \
  --build-arg WASP_CLIENT_ENV="REACT_APP_ANOTHER_VAR='somevalue'" \
  -t my-wasp-app \
  .wasp/out