Skip to main content

Deploy Your Medusa Server on Heroku

In this document, you'll learn how to deploy your Medusa server 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 server to Heroku directly:

Deploy to Heroku

Prerequisites

Medusa Server

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

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

Needed Accounts

Required Tools

Deploy to Heroku

1. Login to Heroku from your CLI

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku login
Copy to Clipboard

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

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku create <APP_NAME>
heroku git:remote -a <APP_NAME>
Copy to Clipboard

Where Copy to Clipboard is the name of the app you'll create. You can use any name you want.

3. Install Postgresql and Redis on Heroku

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

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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku addons:create heroku-postgresql:hobby-basic
Copy to Clipboard

This uses Heroku Postgres's basic 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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku addons:create stackhero-redis:ist-ebi1rc
Copy to Clipboard

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

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

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
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
Copy to Clipboard

Make sure to replace Copy to Clipboard and Copy to Clipboard with actual secrets in a production environment.

Set Buildpack

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku buildpacks:set heroku/nodejs
Copy to Clipboard

Configure the Redis URL

Stackhero Redis adds the Redis URL under the environment variable Copy to Clipboard. However, Medusa looks for the Copy to Clipboard environment variable when initializing the connection with Redis.

Retrieve the value of Copy to Clipboard with the following command:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku config:get STACKHERO_REDIS_URL_TLS
Copy to Clipboard

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 Copy to Clipboard with the following command:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku config:set REDIS_URL=<YOUR_REDIS_URL>
Copy to Clipboard

Where Copy to Clipboard 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 Copy to Clipboard. 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 Copy to Clipboard to the PostgreSQL Database URL.

(Optional) Configure CORS Variables

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku config:set ADMIN_CORS=<YOUR_ADMIN_URL>
Copy to Clipboard

Where Copy to Clipboard is the URL of your admin dashboard.

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku config:set STORE_CORS=<YOUR_STOREFRONT_URL>
Copy to Clipboard

Where Copy to Clipboard is the URL of your storefront.

5. Configure Medusa Server

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

medusa-config.js

Update Copy to Clipboard to include the following configurations:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
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,
};
Copy to Clipboard

package.json

Update Copy to Clipboard to include the following scripts:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
"scripts": {
"serve": "medusa start",
"start": "medusa develop",
"heroku-postbuild": "medusa migrations run",
"prepare": "npm run build",
"build": "babel src -d dist --extensions \".ts,.js\""
},
Copy to Clipboard

6. Launch your Medusa Server

Finally, commit and push all changes to Heroku:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
git add .
git commit -m "Deploy Medusa Server on Heroku"
git push heroku HEAD:master
Copy to Clipboard

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

Test your Server

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku apps:info -a <APP_NAME>
Copy to Clipboard

Where Copy to Clipboard is the name of the app. You should see as the output a bunch of info of the app.

The server'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 Copy to Clipboard and you should receive a JSON response with the products in your store.

Troubleshooting: Inspect Build Logs

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku logs -n 500000 --remote heroku --tail -a <APP_NAME>
Copy to Clipboard

Where Copy to Clipboard is the name of the app.

Run Commands on Your Server

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku run -a <APP_NAME> -- <COMMAND>
Copy to Clipboard

Where Copy to Clipboard is the name of the app and Copy to Clipboard is the command you want to run.

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

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku run -a <APP_NAME> -- medusa user -e "<EMAIL>" -p "<PASSWORD>"
Copy to Clipboard

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

Add Environment Variables

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:

Report Incorrect CodeReport Incorrect CodeReport Incorrect CodeCopy to Clipboard
heroku config:set <ENV_NAME>=<ENV_VALUE> -a <APP_NAME>
Copy to Clipboard

Where Copy to Clipboard is the name of your Heroku app, Copy to Clipboard is the name of the environment variable, and Copy to Clipboard is the value.

What's Next