--- description: 'Learn step-by-step.' addHowToData: true --- # 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: Deploy to Heroku ## Prerequisites ### Medusa Backend It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx). Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](../../references/medusa_config/interfaces/medusa_config.ConfigModule.mdx) to learn how to do that. ### Needed Accounts - A [Heroku](https://heroku.com/) account. ### Required Tools - Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git). - Heroku's CLI tool. You can follow [Heroku's documentation to learn how to install it for your operating system](https://devcenter.heroku.com/articles/heroku-cli). --- ## 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: ```bash 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 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: ```bash heroku create heroku git:remote -a ``` Where `` 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. :::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: ```bash 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.](https://elements.heroku.com/addons/heroku-postgresql#pricing) #### Redis Add a Redis instance to your Heroku app with the following command: ```bash heroku addons:create stackhero-redis:ist-m4euc0 ``` This uses the lowest plan in Stackhero Redis. You can check out [the plans and pricing of Stackhero Redis on Heroku's website.](https://elements.heroku.com/addons/stackhero-redis#pricing) ### 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 backend](../../references/medusa_config/interfaces/medusa_config.ConfigModule.mdx) document. Run the following commands in the root directory of your Medusa backend to set some environment variables: ```bash 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: ```bash 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: ```bash heroku config:get STACKHERO_REDIS_URL_TLS ``` This prints the value of the environment variable which is a Redis connection string. :::note If you see nothing, you have to wait until the creation process of the stackhero redis instance is done. Try waiting a few minutes then trying again. ::: Copy that value and use it to set the environment variable `REDIS_URL` with the following command: ```bash heroku config:set REDIS_URL= ``` Where `` 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 modules in your Medusa backend that require setting environment variables, then you should set them at this point. For example, if you use the Redis Event Bus module: ```bash heroku config:set EVENTS_REDIS_URL= ``` Make sure to change `EVENTS_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: ```bash heroku config:set ADMIN_CORS= ``` Where `` 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: ```bash heroku config:set STORE_CORS= ``` Where `` is the URL of your storefront. ### 5. Configure Medusa Backend Before jumping into the deployment, you must configure your Medusa backend to use the previous environment variables and the recommended production configurations. #### medusa-config.js Update `module.exports` to include the following configurations: ```js 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, modules, } ``` #### package.json Update `scripts` to include the following scripts: ```json "scripts": { "serve": "medusa start", "start": "medusa develop", "heroku-postbuild": "medusa migrations run", "prepare": "npm run build", "build": "babel src -d dist --extensions \".ts,.js\"" }, ``` ### (Optional) 6. 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](../../admin/configuration.mdx#plugin-options) of the admin plugin: ```js title="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](../index.mdx#deploy-admin-through-github-action). #### Deploying Separately If you choose to deploy the admin separately, disable the admin plugin's [serve option](../../admin/configuration.mdx#plugin-options): ```js title="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](../admin/index.mdx). ::: ### 7. Launch your Medusa Backend Finally, commit and push all changes to Heroku: ```bash 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 To test your backend, run the following command to retrieve the backend's URL: ```bash heroku apps:info -a ``` Where `` 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 `/store/products` and you should receive a JSON response with the products in your store. ### 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](#deploying-with-the-backend), you can test it by going to `/app`. If you changed the admin path, make sure to change `/app` to the path you've set. --- ## 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 backend: ```bash heroku logs -n 500000 --remote heroku --tail -a ``` Where `` is the name of the app. ### Error: Babel not found If you get the following error in the logs of your application: ```bash /bin/sh: 1: /app/node_modules/.bin/babel: not found ``` You can resolve it by creating a file in the root of your Medusa backend directory named `Procfile` (without an extension) with the following content: ``` web: npm run serve ``` Then, push the changes with Git: ```bash git add . git commit -m "Added Procfile" git push heroku HEAD:master ``` Once the application is re-published, you can access your store as expected. --- ## Run Commands on Your Backend To run commands on your backend, you can use the following command: ```bash heroku run -a -- ``` Where `` is the name of the app and `` is the command you want to run. For example, to create an admin user you can run the following command: ```bash heroku run -a -- npx medusa user -e "" -p "" ``` Where `` 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 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: ```bash heroku config:set = -a ``` Where `` is the name of your Heroku app, `` is the name of the environment variable, and `` is the value. --- ## See Also - [Deploy your Medusa Admin](../admin/index.mdx) - [Deploy your storefront](../storefront/index.mdx)