import styles from '../deployment.module.css'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; # 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](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy?template=https://github.com/medusajs/medusa-starter-default/tree/feat/deploy-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](../../quickstart/quick-start.md). Furthermore, your Medusa server should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Server documentation](../../usage/configurations.md) 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](../../tutorial/0-set-up-your-development-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 server, 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. :::tip In this section, the add-ons are used with a free plan. It's highly recommended that you don't use a free plan in a production environment. ::: #### PostgreSQL Add a Postgres add-on to your Heroku app with the following command: :::note This add-on is added with a free plan. However, Heroku might require you to add a payment method to proceed. ::: ```bash heroku addons:create heroku-postgresql:hobby-dev ``` This uses the free plan of Heroku Postgres. Make sure to check out [more information regarding the plans and pricing of Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql#pricing). #### Redis :::note The Add-on used here for Redis is [Upstash](https://devcenter.heroku.com/articles/upstash-redis) which is currently in beta. However, it provides a generous free plan. You can alternatively go for [Stackhero](https://elements.heroku.com/addons/stackhero-redis) but it does not have a free plan. ::: Add a Redis instance to your Heroku app with the following command: :::note This add-on is added with a free plan. However, Heroku might require you to add a payment method to proceed. ::: ```bash heroku addons:create upstash-redis ``` This uses the free plan of Upstash. Make sure to check out [more information regarding the plans and pricing of Upstash](https://elements.heroku.com/addons/upstash-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 Server](../../usage/configurations.md) document. Run the following commands in the root directory of your Medusa server 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 Upstash adds the Redis URL under the environment variable `UPSTASH_REDIS_URL`. However, Medusa looks for the `REDIS_URL` environment variable when initializing the connection with Redis. Retrieve the value of `UPSTASH_REDIS_URL` with the following command: ```bash heroku config:get UPSTASH_REDIS_URL ``` 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: ```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 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: ```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 server'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 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 `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, }; ``` #### 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\"" }, ``` ### 6. Launch your Medusa Server Finally, commit and push all changes to Heroku: ```bash git add . git commit -m "Deploy Medusa Server on Heroku" git push heroku HEAD:master ``` 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: ```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 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 `/store/products` 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: ```bash heroku logs -n 500000 --remote heroku --tail -a ``` Where `` is the name of the app. ## Run Commands on Your Server To run commands on your server, 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 -- 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. ## What's Next :rocket: - Learn how to [deploy your Medusa admin](../admin/index.mdx). - Learn how to [deploy your storefront](../storefront/index.mdx).