File: docs/content/deployments/server/deploying-on-digital-ocean.md Copy Chapter

addHowToData: true Copy Chapter

Deploy Your Medusa Backend to DigitalOcean Apps

In this document, you'll learn how to deploy your Medusa backend to a DigitalOcean App.

DigitalOcean is a reliable hosting provider that provides different ways to host websites and servers. One way to host a backend is using their DigitalOcean App Platform.

Prerequisites Copy Chapter

Medusa Backend Copy Section

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.

Needed Accounts Copy Section

• A DigitalOcean account. You need to provide a payment method on sign up.
• A GitHub account to create a repository to host your Medusa backend’s codebase.

:::tip

If you want to use another Git Provider supported by DigitalOcean, it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.

:::

Required Tools Copy Section

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

Changes to package.json Copy Chapter

Change the start script in package.json to the following:

"start": "medusa migrations run && medusa start"

This ensures that Migrations are run everytime the Medusa backend is restarted.

Changes to medusa-config.js Copy Chapter

In medusa-config.js, the DATABASE_URL variable is set to the environment variable DATABASE_URL. This needs to be changed as DigitalOcean provides the different details of the database connection separately.

Replace the previous declaration of DATABASE_URL in medusa-config.js with the following:

const DB_USERNAME = process.env.DB_USERNAME
const DB_PASSWORD = process.env.DB_PASSWORD
const DB_HOST = process.env.DB_HOST
const DB_PORT = process.env.DB_PORT
const DB_DATABASE = process.env.DB_DATABASE

const DATABASE_URL = 
  `postgres://${DB_USERNAME}:${DB_PASSWORD}` + 
  `@${DB_HOST}:${DB_PORT}/${DB_DATABASE}`

In addition, you must add to projectConfig in the exported object a new property database_extra:

module.exports = {
  projectConfig: {
    // ...
    database_extra: { ssl: { rejectUnauthorized: false } },
  },
}

Create GitHub Repository Copy Chapter

Before you can 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 Copy Section

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.

Deploy to DigitalOcean App Copy Chapter

After logging into your account, click on the Create button at the top right, then choose App.

Choose Repository Copy Section

In the Create App page, choose GitHub from the Service Provider list.

If you haven’t given DigitalOcean access before, click on Manage Access under Source Code. You’ll then be redirected to GitHub to give DigitalOcean access.

Once DigitalOcean have access to your GitHub account, you should see a Repository input. Click on it and search for the repository you created earlier.

Additional inputs will show up to choose the Branch, Source Directory, and Autodeploy options.

If you host your Medusa backend in a monorepo, you should change the Source Directory to the directory the backend is available in the repository. Otherwise, it can be left as is.

Once you’re done, click Next to move on to the next step.

Specify Web Service Resources Copy Section

In the next step, you’ll see the resources to create.

If you have a Dockerfile available in the backend’s codebase (which is available by default), you’ll have two resources showing. You can remove it by clicking on the trash icon at the right of the resource.

By default, DigitalOcean hosts the web service in a sub-path of the domain name of the created App. To change it to the root of the domain, click on the edit icon at the right of the Web Service resource.

Then, scroll to HTTP Request Routes and expand it by clicking on Edit at its right. Change the value of the Routes input to /.

Once you’re done click Save. You’ll be taken back to the Resources page.

Specify Database Resources Copy Section

On the same page, expand the Add Resources section, choose Database, then click Add.

In the new page, you’ll be shown a PostgreSQL database to be created. Notice that it’s important to choose a name that you’ll remember as you’ll need the name in next steps. You can leave the name as is if it’s not necessary to change it.

Once you’re done, click Create and Attach. You’ll be redirected back to the previous page with the database added to the resources.

Once you’re done, click Next to move on to the next step.

Set Environment Variables Copy Section

In this section, you’ll add environment variables that are essential to your Medusa backend.

You should see two ways to add environment variables: Global or specific to the Web Service.

Click Edit on the second row to add environment variables specific to the Web Service. Add the following environment variables:

DB_USERNAME=${db.USERNAME}
DB_PASSWORD=${db.PASSWORD}
DB_HOST=${db.HOSTNAME}
DB_PORT=${db.PORT}
DB_DATABASE=${db.DATABASE}
REDIS_URL=${redis.DATABASE_URL}
JWT_SECRET=secret
COOKIE_SECRET=secret
NPM_CONFIG_PRODUCTION=false
NODE_ENV=production

:::caution

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

:::

Notice how for database environment variables you access the values from the database you created earlier db. If you changed the name of the database, you must change db here to the name you supplied to the PostgreSQL database.

Another thing to note here is that you added a REDIS_URL environment variable that uses a redis resource to retrieve the URL. You’ll be creating this resource in a later section.

:::note

If you're using modules that require setting environment variables, make sure to set them here. You can also add them later. For example, if you're using the Redis Event Bus module, you can set the environment variable for it here or use the same REDIS_URL variable. Your module may also require setting up other resources than those explained in this guide so make sure to add them as well.

:::

Once you’re done click Save.

Finalize App Copy Section

In the next section, you’ll be shown the app info and the region it will be deployed to. You can leave it all as is or make changes if you find it necessary.

Once you’re done, click Next to go to the next step.

In the final step, you can see a review of everything you created. If everything looks good, scroll down and click Create Resource.

Create Redis Resource Copy Section

While the backend is being deployed, you can create the Redis resource.

Click the Create button at the top right and choose Database from the dropdown.

In the new page under Choose a database engine, choose Redis.

Then, scroll down to the “Choose a name” input. Since you used the name redis in the REDIS_URL environment variables, change the value to redis here.

Once you’re done, click on Create Database Cluster.

Attach Redis Database Copy Section

Once the Redis database is created go back to the App you created earlier by choose Apps in the sidebar then clicking on the App name.

Click at the white Create button at the top right and choose Create/Attach Database.

In the new page, click on the Previously Created DigitalOcean Database radio button. Then, under Database Cluster select the Redis database you just created.

Once you’re done click Attach Database. This will add the Redis database to the list of resources of your App and will trigger a redeploy of the App.

Test your Backend Copy Chapter

Once the redeployment is complete, copy the URL of the App which can be found under the App’s name.

Then, go to <YOUR_APP_URL>/store/products. If the deployment was successful, you should receive a JSON response.

Run Commands on Your Backend Copy Chapter

To run commands on your backend, you can access the console on the App’s page by choosing the Console tab. This opens a console in your browser where you can run commands on your backend.

For example, you can run the following commands to create a new admin user:

npm install @medusajs/medusa-cli -g
medusa user --email  --password

Make sure to replace and with the credentials you want to give the user.

Add Environment Variables Copy Chapter

You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.

To add environment variables, on the App’s page click on Settings and choose the Web Service component.

Then, scroll down and find Environment Variables. You can expand the environment variables by clicking Edit on the right. Here, you can edit, add, and remove environment variables.

Once you click Save, the environment variables will be saved and a redeployment will be triggered.

See Also Copy Chapter

• Deploy the Medusa Admin.
• Deploy the Storefront.

File: docs/content/deployments/server/deploying-on-heroku.mdx Copy Chapter

addHowToData: true Copy Chapter

import styles from '../deployment.module.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

Deploy Your Medusa Backend on Heroku

In this document, you'll learn how to deploy your Medusa backend on Heroku. Heroku is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud.

Alternatively, you can use this button to deploy the Medusa backend to Heroku directly:

Prerequisites Copy Chapter

Medusa Backend Copy Section

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.

Needed Accounts Copy Section

• A Heroku account.

Required Tools Copy Section

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

Deploy to Heroku Copy Chapter

1. Login to Heroku from your CLI Copy Section

Before you can create an app with Heroku, you must login with the CLI tool:

heroku login

Depending on your operating system, you must follow either the instructions in your terminal or a page in your browser will open.

2. Create an App with Heroku Copy Section

In the root directory of your Medusa backend, run the following commands to create an app on Heroku and add it as a remote origin:

heroku create <APP_NAME>
heroku git:remote -a <APP_NAME>

Where <APP_NAME> is the name of the app you'll create. You can use any name you want.

3. Install Postgresql and Redis on Heroku Copy Section

Medusa requires a Postgres database and a Redis instance to work. You can add those to your Heroku app using Add-ons.

:::note

If you don't have a payment method set up in your Heroku account, you'll be asked to enter your payment details when you try to install these addons.

:::

PostgreSQL

Add a Postgres add-on to your Heroku app with the following command:

heroku addons:create heroku-postgresql:mini

This uses Heroku Postgres's smallest plan. You can check out the available plans and pricing of Heroku Postgres on Heroku's website.

Redis

Add a Redis instance to your Heroku app with the following command:

heroku addons:create stackhero-redis:ist-ebi1rc

This uses the lowest plan in Stackhero Redis. You can check out the plans and pricing of Stackhero Redis on Heroku's website.

4. Configure Environment Variables on Heroku Copy Section

Medusa requires a set of environment variables to be configured. You can learn more about Medusa's configurations in the Configure your Medusa backend document.

Run the following commands in the root directory of your Medusa backend to set some environment variables:

heroku config:set NODE_ENV=production
heroku config:set JWT_SECRET=your-super-secret
heroku config:set COOKIE_SECRET=your-super-secret-pt2
heroku config:set NPM_CONFIG_PRODUCTION=false

:::tip

Make sure to replace your-super-secret and your-super-secret-pt2 with actual secrets in a production environment.

:::

Set Buildpack

Additionally, you need to set the buildpack to Node.js using the following command:

heroku buildpacks:set heroku/nodejs

Configure the Redis URL

Stackhero Redis adds the Redis URL under the environment variable STACKHERO_REDIS_URL_TLS. However, Medusa looks for the REDIS_URL environment variable when initializing the connection with Redis.

Retrieve the value of STACKHERO_REDIS_URL_TLS with the following command:

heroku config:get STACKHERO_REDIS_URL_TLS

This prints the value of the environment variable which is a Redis connection string.

Copy that value and use it to set the environment variable REDIS_URL with the following command:

heroku config:set REDIS_URL=<YOUR_REDIS_URL>

Where <YOUR_REDIS_URL> is the value you received from the previous command.

Configure the PostgreSQL Database URL

If you're using the Heroku PostgreSQL Add-on, it should configure the environment variable DATABASE_URL. In that case, you don't need to perform any additional actions.

However, if you use another add-on, make sure to set the environment variable DATABASE_URL to the PostgreSQL Database URL.

(Optional) Configure Modules Environment Variables

If you use in your Medusa backend modules that require setting environment variables, then you should set them at this point.

For example, if you use the Redis Event Bus module:

heroku config:set EVENT_REDIS_URL=<YOUR_REDIS_URL>

Make sure to change EVENT_REDIS_URL to the environment variable name you use for your module's configurations.

If your module requires setting up other services, do that then add the environment variables.

(Optional) Configure CORS Variables

Optionally, if you've deployed the admin dashboard and you want to ensure it can use the backend's REST APIs, you must set the following environment variable:

heroku config:set ADMIN_CORS=<YOUR_ADMIN_URL>

Where <YOUR_ADMIN_URL> is the URL of your admin dashboard.

Similarly, if you've deployed the storefront and you want to ensure it can use the backend's REST APIs, you must set the following environment variable:

heroku config:set STORE_CORS=<YOUR_STOREFRONT_URL>

Where <YOUR_STOREFRONT_URL> is the URL of your storefront.

5. Configure Medusa Backend Copy Section

Before jumping into the deployment, you need to configure your Medusa backend to ensure it uses the previous environment variables and the recommended production configurations.

medusa-config.js

Update module.exports to include the following configurations:

module.exports = {
  projectConfig: {
    redis_url: REDIS_URL,
    database_url: DATABASE_URL,
    database_type: "postgres",
    store_cors: STORE_CORS,
    admin_cors: ADMIN_CORS,
    database_extra:
      process.env.NODE_ENV !== "development"
        ? { ssl: { rejectUnauthorized: false } }
        : {},
  },
  plugins,
}

package.json

Update scripts to include the following scripts:

"scripts": {
    "serve": "medusa start",
    "start": "medusa develop",
    "heroku-postbuild": "medusa migrations run",
    "prepare": "npm run build",
    "build": "babel src -d dist --extensions \".ts,.js\""
},

6. Launch your Medusa Backend Copy Section

Finally, commit and push all changes to Heroku:

git add .
git commit -m "Deploy Medusa Backend on Heroku"
git push heroku HEAD:master

This triggers a redeploy of the Medusa backend with all the new configurations.

Test your Backend Copy Chapter

To test your backend, run the following command to retrieve the backend's URL:

heroku apps:info -a <APP_NAME>

Where <APP_NAME> is the name of the app. You should see as the output a bunch of info of the app.

The backend's URL is available under "Web URL". You can copy it and perform requests to it to test it out.

For example, you can send a request to <YOUR_BACKEND_URL>/store/products and you should receive a JSON response with the products in your store.

Troubleshooting: Inspect Build Logs Copy Section

If an error occurs during the deployment, you can explore your Heroku app build logs using the following command in the root directory of your Medusa backend:

heroku logs -n 500000 --remote heroku --tail -a <APP_NAME>

Where <APP_NAME> is the name of the app.

Run Commands on Your Backend Copy Chapter

To run commands on your backend, you can use the following command:

heroku run -a <APP_NAME> -- <COMMAND>

Where <APP_NAME> is the name of the app and <COMMAND> is the command you want to run.

For example, to create an admin user you can run the following command:

heroku run -a <APP_NAME> -- medusa user -e "" -p ""

Where <APP_NAME> is the name of your Heroku app, and and are the credentials you want to use to log in to the Medusa admin dashboard.

Add Environment Variables Copy Chapter

You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.

To set or change an environment variable's value, you can use the following command:

heroku config:set <ENV_NAME>=<ENV_VALUE> -a <APP_NAME>

Where <APP_NAME> is the name of your Heroku app, <ENV_NAME> is the name of the environment variable, and <ENV_VALUE> is the value.

See Also Copy Chapter

• Deploy your Medusa admin
• Deploy your storefront

File: docs/content/deployments/server/deploying-on-qovery.md Copy Chapter

addHowToData: true Copy Chapter

Deploy Your Medusa Backend on Qovery

In this document, you'll learn how to deploy your Medusa backend on Qovery with the help of Terraform.

Qovery is a Continuous Deployment Platform that provides you with the developer experience of Heroku on top of your cloud provider (For example, AWS, DigitalOcean).

Terraform is an open source infrastructure as code software (IaC) tool that allows you to easily deploy apps like Medusa and the resources it needs to Qovery using a single script.

:::note

This tutorial explains how to deploy Medusa to a Qovery organization with an AWS cluster. If you want to use a cloud provider other than AWS, you need to make changes to some of the keys and variables used in the tutorial.

:::

Prerequisites Copy Chapter

Medusa Backend Copy Section

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.

Needed Accounts Copy Section

• A Qovery account with a created organization. Qovery provides a free plan that you can use.
• An AWS account that you’ll connect to a Qovery cluster.
• A GitHub account to create a repository to host your backend's codebase.

:::tip

If you want to use another Git Provider supported by Qovery, it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.

:::

Required Tools Copy Section

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

Create GitHub Repository Copy Chapter

Before you can 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 Copy Section

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.

Deploy to Qovery Copy Chapter

In this section, you’ll learn how to deploy your Medusa backend to Qovery with the help of Terraform.

Sign in Using Qovery CLI Copy Section

If you haven’t logged in to your Qovery account using the Qovery CLI tool yet, run the following command:

qovery auth

This opens a new page in your browser to log in to Qovery.

Retrieve Qovery Access Token Copy Section

Terraform needs an access token from Qovery so that it can deploy to your Qovery organization.

Run the following command to retrieve a Qovery access token:

qovery token

You’ll be prompted to choose an organization and add a name and description for the token. Once the command finishes executing, you’ll be given an access token. Save it to use in the next steps.

Add Terraform Variables Copy Section

You need to add some variables to use for your Medusa deployment to Qovery.

In the root directory of your Medusa backend, create the file variables.tf with the following content:

/* Detailed source-code truncated for AI context efficiency. */

This defines the required variables and sets some of them as secret to ensure their values aren’t printed in the console during deployment.

Next, to set the values of these variables, create the file terraform.tfvars with the following content:

qovery_organization_id = ""

# Optional
qovery_create_cluster = true

# Optional
qovery_cluster_id = null

qovery_access_token = ""

# Optional
aws_access_key_id = null

# Optional
aws_secret_access_key = null

# Optional
aws_region = null

# Optional
medusa_jwt_secret = "secret"

# Optional
medusa_cookie_secret = "secret"

git_url = ""

# Optional
git_branch = "master"

# Optional
git_root_path = "/"

Here’s an explanation of each of the variables and how to retrieve their variables:

• qovery_organization_id: The ID of the Qovery organization to deploy the backend to. It can be found by logging into your Qovery Console. You’ll be redirected to the organization’s main page with a URL of the format https://console.qovery.com/platform/organization/<ORGANIZATION_ID>/projects. Copy the <ORGANIZATION_ID> in the URL to use as the value of this field.
• qovery_create_cluster: A boolean value indicating whether a new cluster should be created or not. If you already have a cluster that you want to use, you can set the value to false and set the value of qovery_cluster_id. Otherwise, set the value to true and set the values of aws_access_key_id, aws_secret_access_key, and aws_region.
• qovery_cluster_id: The ID of the existing cluster to use (if qovery_create_cluster is set to false). You can use Qovery’s REST API to retrieve the cluster ID. You can use the token you generated earlier for the Bearer authorization token as explained here.
• aws_access_key_id, aws_secret_access_key, and aws_region: The credentials used to create the cluster (if qovery_create_cluster is set to true). You can refer to this guide to learn how to retrieve the aws_access_key_id and aws_secret_access_key.
• medusa_jwt_secret: The value of the JSON Web Token (JWT) Secret on your Medusa backend. It’s recommended to use a strong randomly generated string.
• medusa_cookie_secret: The value of the Cookie Secret on your Medusa backend. It’s recommended to use a strong randomly generated string.
• git_url: The URL of the Git repository you created earlier. Make sure it ends with .git.
• git_branch: The branch to use in the GitHub repo. By default it’s master.
• git_root_path: The root path of the Medusa backend. By default, it’s /. If you are hosting your Medusa backend in a monorepo in a nested directory, you need to change the value of this variable.

:::note

If you're using modules that require setting up other variables, you can add them here.

:::

Add Terraform Configuration File Copy Section

In the root directory of your Medusa backend, create the file main.tf with the following content:

/* Detailed source-code truncated for AI context efficiency. */

:::note

If you're using modules that require setting up other resources, make sure to add them here.

:::

This is a Terraform configuration file that creates all the resources necessary to deploy Medusa to Qovery. If you set qovery_create_cluster to true, it will create new credentials and a cluster in your Qovery organization using the AWS credentials you set in the variables.

Next, it creates a new project, environment, PostgreSQL database, and a Redis database in your Qovery organization.

Finally, it creates the Medusa app and sets all the necessary environment variables needed to run it.

:::tip

This deployment uses Docker. By default, you should have the files Dockerfile and docker-compose.yml` in the root of your Medusa backend.

:::

Change develop.sh Copy Section

The Dockerfile runs the file develop.sh to start the backend. Change the content of develop.sh to the following:

#!/bin/bash

# Run migrations to ensure the database is updated
medusa migrations run

# Run backend
medusa start

This makes sure the production backend is started and not a development backend.

Initialize Terraform Copy Section

In your terminal, run the following command to initialize Terraform:

terraform init

This will install the Qovery Terraform provider and have everything ready before the deployment.

Deploy the Medusa App Copy Section

Finally, run the following command to deploy your Medusa app:

terraform apply

You’ll be asked to confirm creating all the necessary resources in Qovery. Enter yes and the deployment will start.

The deployment can take up to thirty minutes to finish. You’ll be able to track its status both in your terminal and in the Qovery Console.

:::tip

If you run into any errors while running this command, you can just re-run it after fixing the errors and it will pick up from where it left off. For example, if an error occurred after the creation of the PostgreSQL database, terraform continues from the next task and does not recreate the PostgreSQL database.

:::

Test the Backend Copy Chapter

Once the command finishes and the deployment is successful, you can access your backend in the Qovery Console. Go to the project, environment, then the app that you created using Terraform and Qovery. In the app, click the Open button at the top right to open your website in a new tab.

You can access any of the endpoints on your backend using the backend URL. For example, you can get the list of products using the endpoint /store/products.

Run Commands on the Backend Copy Chapter

To run commands on the backend, run the following command:

qovery shell

You’ll be asked to either confirm the existing context or choose a new context.

After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa backend. For example, you can run the user command using Medusa’s CLI tool to create a new user:

npm install @medusajs/medusa-cli -g
medusa user --email  --password

Add Environment Variables Copy Chapter

You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.

To add environment variables, in your Qovery Console go to the Medusa app and choose Environment Variables from the sidebar. You can add environment variables here at any point later on.

See Also Copy Chapter

• Deploy the Medusa Admin
• Deploy the Storefront

File: docs/content/deployments/server/deploying-on-railway.md Copy Chapter

addHowToData: true Copy Chapter

Deploy Your Medusa Backend to Railway

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

What is Railway Copy Chapter

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 plan that allows you to deploy your Medusa backend along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes.

Prerequisites Copy Chapter

Medusa Backend Copy Section

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.

Needed Accounts Copy Section

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

Required Tools Copy Section

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

Changes to Medusa Backend Codebase Copy Chapter

By default, Railway looks for a Dockerfile in the root of the codebase. If there is one, it will try to deploy your backend using it.

As this guide doesn't use Docker, make sure to delete Dockerfile from the root of your Medusa backend.

Create GitHub Repository Copy Chapter

Before you can 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 Copy Section

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.

Deploy to Railway Copy Chapter

In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the backend from the GitHub repository.

Create the PostgreSQL Database Copy Section

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.

To find the PostgreSQL database URL which you’ll need later:

1. Click on the PostgreSQL card.
2. Choose the Connect tab.
3. Copy the Postgres Connection URL.

Create the Redis Database Copy Section

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.

To find the Redis database URL which you’ll need later:

1. Click on the Redis card.
2. Choose the Connect tab.
3. Copy the Redis Connection URL.

Note about Modules Copy Section

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 the Medusa Backend Repository Copy Section

In the same project view:

1. Click on the New button.
2. Choose the ”GitHub Repo” option.
3. Choose the ”Configure GitHub App” option to give Railway permission to read and pull your code from GitHub.
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 to deploy successfully.

Configure Environment Variables Copy Section

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=<YOUR_DATABASE_URL>
REDIS_URL=<YOUR_REDIS_URL>

Where <YOUR_DATABASE_URL> and <YOUR_REDIS_URL> are the URLs you copied earlier when you created the PostgreSQL and Redis databases respectively.

:::warning

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

:::

Change Start Command Copy Section

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 Service section.
3. Paste the following in the Start Command field:

medusa migrations run && medusa develop

Add Domain Name Copy Section

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 Domains section.
3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain.

Test the Backend Copy Chapter

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.

:::

Troubleshooting Copy Chapter

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.

Run Commands on the Backend Copy Chapter

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.

See Also Copy Chapter

• Deploy the Medusa Admin
• Deploy the Storefront