Deploy Your Medusa Backend to Railway

In this document, you’ll learn how to deploy your Medusa backend to Railway.

What is Railway

Railway is a hosting provider that you can use to deploy web applications and databases without having to worry about managing the full infrastructure.

Railway provides a free trial (no credit card required) that allows you to deploy your Medusa backend along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes.

Note

If you're deploying the admin plugin along with the backend, you'll need at least the Developer plan. The resources provided by the starter plan will cause memory errors.

If you also don't have a Medusa project, you can deploy to Railway instantly with this button:

---

Prerequisites

Medusa Backend

It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the quickstart guide.

Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the Configure your Backend documentation to learn how to do that.

Production Modules

If you're using development modules for events and caching, it's highly recommended to install production modules instead. These can be:

• Redis Event Module
• Redis Cache Module

Needed Accounts

• A Railway account.
• A GitHub account to create a repository to host your backend's codebase.

Required Tools

• Git’s CLI tool. You can follow this documentation to learn how to install it for your operating system.

---

(Optional) Step 0: Configure the Admin

If you're using the Medusa Admin plugin, you have two options to deploy it: either with the backend or separately.

Deploying with the Backend

To deploy the admin with the backend:

1. Your chosen plan must offer at least 2GB of RAM.
2. Enable the autoRebuild option of the admin plugin:

medusa-config.js

const plugins = [
  // ...
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      autoRebuild: true,
      // other options...
    },
  },
]

Alternatively, you can use a GitHub action to build the admin as explained here.

Deploying Separately

If you choose to deploy the admin separately, disable the admin plugin's serve option:

medusa-config.js

const plugins = [
  // ...
  {
    resolve: "@medusajs/admin",
    /** @type {import('@medusajs/admin').PluginOptions} */
    options: {
      // only enable `serve` in development
      // you may need to add the NODE_ENV variable
      // manually
      serve: process.env.NODE_ENV === "development",
      // other options...
    },
  },
]

This ensures that the admin isn't built or served in production. You can also change @medusajs/admin dependency to be a dev dependency in package.json.

You can alternatively remove the admin plugin for the plugins array.

Tip

Refer to the admin deployment guides on how to deploy the admin separately.

---

(Optional) Step 1: Add Nixpacks Configurations

If you've created your project using create-medusa-app, you might receive errors during the deployment process as Railway uses NPM by default. To avoid that, you need to configure Nixpacks to either use yarn or add the --legacy-peer-deps option to npm install.

In the root of your Medusa project, add the nixpacks.toml file with the following content:

[phases.setup]
nixPkgs = ['nodejs', 'yarn']

[phases.install]
cmds=['yarn install']

---

Step 2: Add Worker Mode Configuration

Note

Learn more about the Worker Mode in this guide.

Set the worker_mode configuration in your medusa-config.js, if you haven't already:

const projectConfig = {
  // ...,
  database_url: "...",
  worker_mode: process.env.MEDUSA_WORKER_MODE,
}

This allows you to switch between modes for different deployed Medusa instances based on the MEDUSA_WORKER_MODE environment variable.

---

Step 3: Create GitHub Repository

Before you deploy your Medusa backend you need to create a GitHub repository and push the code base to it.

On GitHub, click the plus icon at the top right, then click New Repository.

You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.

Push Code to GitHub Repository

The next step is to push the code to the GitHub repository you just created.

After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory.

Copy the link. Then, open your terminal in the directory that holds your Medusa backend codebase and run the following commands:

git init
git remote add origin <GITHUB_URL>

Where <GITHUB_URL> is the URL you just copied.

Then, add, commit, and push the changes into the repository:

git add .
git commit -m "initial commit"
git push

After pushing the changes, you can find the files in your GitHub repository.

---

Step 4: Deploy to Railway

In this section, you’ll create the PostgreSQL and Redis databases first, then deploy two instances of the Medusa backend: one having a server runtime mode, and another having a worker runtime mode.

Create the PostgreSQL Database

On the Railway dashboard:

1. Click on the ”New Project**”** button.
2. Choose from the dropdown the ”Provision PostgreSQL” option.

A new database will be created and, after a few seconds, you will be redirected to the project page where you will see the newly-created database.

Create the Redis Database

In the same project view:

1. Click on the New button.
2. Choose the Database option.
3. Choose Add Redis.

A new Redis database will be added to the project view in a few seconds. Click on it to open the database sidebar.

Note about Modules

If you use modules that require setting up other resources, make sure to add them at this point. This guide does not cover configurations specific to a module.

Deploy Medusa in Server Mode

In this section, you'll create a Medusa backend instance running in server runtime mode.

In the same project view:

1. Click on the New button.
2. Choose the ”GitHub Repo” option.
3. If you still haven't given GitHub permissions to Railway, choose the ”Configure GitHub App” option to do that.
4. Choose the repository from the GitHub Repo dropdown.

Tip

If the GitHub repositories in the dropdown are stuck on loading and aren't showing, you might need to delete the project and start over. This only happens before you configure your account with GitHub.

It will take the backend a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet.

Configure Backend Environment Variables

To configure the environment variables of your Medusa backend:

1. Click on the GitHub repository’s card.
2. Choose the Variables tab.
3. Add the following environment variables:

PORT=9000
JWT_SECRET=something
COOKIE_SECRET=something
DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}
DATABASE_TYPE=postgres
MEDUSA_WORKER_MODE=server

Notice that the values of DATABASE_URL and REDIS_URL reference the values from the PostgreSQL and Redis databases you created.

Warning

It’s highly recommended to use strong, randomly generated secrets for JWT_SECRET and COOKIE_SECRET.

Make sure to add any other environment variables that are relevant for you here. For example, you can add environment variables related to Medusa Admin or your modules.

Change Backend's Start Command

The start command is the command used to run the backend. You’ll change it to run any available migrations, then run the Medusa backend. This way if you create your own migrations or update the Medusa backend, it's guaranteed that these migrations are run first before the backend starts.

To change the start command of your Medusa backend:

1. Click on the GitHub repository’s card.
2. Click on the Settings tab and scroll down to the Deploy section.
3. Paste the following in the Start Command field:

medusa migrations run && medusa start

Deploy Medusa in Worker Mode

You'll now create another Medusa instance that'll be in worker runtime mode.

In the same project view:

1. Click on the New button.
2. Choose the ”GitHub Repo” option.
3. Choose the same repository from the GitHub Repo dropdown.

It will take the worker backend a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet.

Configure Environment Variables for Worker Mode

To configure the environment variables of the Medusa instance running in worker mode:

1. Click on the card of the Medusa instance you just created..
2. Choose the Variables tab.
3. Add the following environment variables:

PORT=9000
JWT_SECRET=something
COOKIE_SECRET=something
DATABASE_URL=${{Postgres.DATABASE_URL}}
REDIS_URL=${{Redis.REDIS_URL}}
DATABASE_TYPE=postgres
MEDUSA_WORKER_MODE=worker

Notice that the values of DATABASE_URL and REDIS_URL reference the values from the PostgreSQL and Redis databases you created.

Warning

It’s highly recommended to use strong, randomly generated secrets for JWT_SECRET and COOKIE_SECRET.

Make sure to add any other environment variables that are relevant for you here.

Change Worker's Start Command

The start command is the command used to run the Medusa instance in worker mode. To set it:

1. Click on the worker’s card.
2. Click on the Settings tab and scroll down to the Deploy section.
3. Paste the following in the Start Command field:

medusa start

Add Domain Name

The last step is to add a domain name to your Medusa backend. To do that:

1. Click on the GitHub repository’s card.
2. Click on the Settings tab and scroll down to the Environment section.
3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain.

---

Step 5: Test the Backend

Every change you make to the settings redeploys the backend. You can check the Deployments of the backend by clicking on the GitHub repository’s card and choosing the Deployments tab.

After the backend is redeployed successfully, open the app in your browser using the domain name. For example, you can open the URL <YOUR_APP_URL>/store/products which will return the products available on your backend.

Tip

If you generated a random domain, you can find it by clicking on the GitHub repository’s card → Deployment tab.

Health Route

You can access /health to get health status of your deployed backend.

Testing the Admin

If you deployed the admin dashboard with the backend, you can test it by going to <YOUR_APP_URL>/app. If you changed the admin path, make sure to change /app to the path you've set.

---

Troubleshooting

If you run into any issues or a problem with your deployed backend, you can check the logs in your Railway container instance by:

1. Click on the GitHub repository’s card.
2. Click on the Deployments tab.
3. Click on the View Logs button.

Error: connect ENOENT

This error may be thrown by a module that uses Redis. If you see it in your build or deploy logs, make sure that your Redis configurations are correct.

---

Run Commands on the Backend

To run commands on your backend, you can use Railway’s CLI tool to run a local shell and execute commands.

For example, you can run commands on the backend to seed the database or create a new user using Medusa’s CLI tool.

Create Admin User

You can create an admin user by running the following command in the root of your Medusa project:

railway run npx medusa user --email admin@medusa-test.com --password supersecret

---

See Also

• Deploy the Medusa Admin
• Deploy the Storefront