diff --git a/docs/content/homepage.md b/docs/content/homepage.md index 935c0c0229..e9a7c2a088 100644 --- a/docs/content/homepage.md +++ b/docs/content/homepage.md @@ -62,7 +62,7 @@ Alternatively, you can build your own storefront with any frontend framework of - Customize your Medusa server by creating your own [endpoints](./advanced/backend/endpoints/add-storefront.md), [services](./advanced/backend/services/create-service.md), and [subscribers](./advanced/backend/subscribers/create-subscriber.md). - Check out guides under the Integrations section to install plugins for [CMS](./add-plugins/strapi.md), [Payment](./add-plugins/stripe.md), [Search Engines](./add-plugins/algolia.md), and more. -- Deploy your Medusa server in seconds on [Heroku](./how-to/deploying-on-heroku.md), [Qovery](./how-to/deploying-on-qovery.md), or [Digital Ocean](./how-to/deploying-on-digital-ocean.md). +- Deploy your Medusa server in seconds on [Heroku](./how-to/deploying-on-heroku.mdx), [Qovery](./how-to/deploying-on-qovery.md), or [Digital Ocean](./how-to/deploying-on-digital-ocean.md). ## Open Source Contribution diff --git a/docs/content/how-to/deploying-on-heroku.md b/docs/content/how-to/deploying-on-heroku.md deleted file mode 100644 index 204032730d..0000000000 --- a/docs/content/how-to/deploying-on-heroku.md +++ /dev/null @@ -1,226 +0,0 @@ ---- -title: "Deploying on Heroku" ---- - -# Deploying on Heroku - -This is a guide for deploying a Medusa project on Heroku. Heroku is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud. - -
- -
- -:::note - -We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](https://docs.medusajs.com/how-to/create-medusa-app) for a small walkthrough. - -::: - -### 1. Install the Heroku CLI - -Install Heroku on your machine: - -**Ubuntu** - -```bash -sudo snap install --classic heroku -``` - -**MacOS** - -```bash -brew tap heroku/brew && brew install heroku -``` - -**Windows** - -Download the appropriate installer for your Windows installation: - -[64-bit installer](https://cli-assets.heroku.com/heroku-x64.exe) -[32-bit installer](https://cli-assets.heroku.com/heroku-x86.exe) - -### 2. Login to Heroku from your CLI - -Connect to your Heroku account from your terminal: - -```bash -heroku login -``` - -:::note - -Follow the instructions on your terminal - -::: - -### 3. Create an app on Heroku - -In your **Medusa project directory**, run the following commands to create an app on Heroku and add it as a remote origin. - -```bash -heroku create medusa-test-app -heroku git:remote -a medusa-test-app -``` - -### 4. Install Postgresql and Redis on Heroku - -Medusa requires a Postgres database and a Redis instance to work. These are added through the Heroku CLI using the following commands. - -:::tip - -In this example below, we initialize the resources on free plans. This is not a valid configuration for a production environment. - -::: - -#### Postgresql - -Add a Postgres add-on to your Heroku app - -```bash -heroku addons:create heroku-postgresql:hobby-dev -``` - -You can find more informations, plans and pricing about Heroku Postgres [here](https://elements.heroku.com/addons/heroku-postgresql). - -#### Redis To Go - -Add a Redis instance to your Heroku app - -:::note - -The add-on `redistogo:nano` is free, but Heroku requires you to add a payment method to proceed. - -::: - -```bash -heroku addons:create redistogo:nano -``` - -You can find more informations, plans and pricing about Redis To Go [here](https://elements.heroku.com/addons/redistogo). - -### 5. Configure environment variables on Heroku - -Medusa requires a set of environment variables. From you project repository, run the following commands:. - -```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 use actual secrets in a production environment. - -::: - -Additionally, we need to set the buildpack to Node.js - -```bash -heroku buildpacks:set heroku/nodejs -``` - -#### Configure the Redis URL - -The library we use for connecting to Redis, does not allow usernames in the connection string. Therefore, we need to perform the following commands to remove it. -Get the current Redis URL: - -```bash -heroku config:get REDISTOGO_URL -``` - -You should get something like: - -```bash -redis://redistogo:some_password_123@some.redistogo.com:9660/ -``` - -Remove the username from the Redis URL: - -```bash -redis://r̶e̶d̶i̶s̶t̶o̶g̶o̶:some_password_123@sole.redistogo.com:9660/ -``` - -Set the new environment variable `REDIS_URL` - -```bash -heroku config:set REDIS_URL=redis://:some_password_123@sole.redistogo.com:9660/ -``` - -### 6. Configure Medusa - -Before jumping into the deployment, we need to configure Medusa. - -#### `medusa-config.js` - -Update `module.exports` to include the following: - -```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: - -```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 app - -Finally, we need to commit and push our changes to Heroku: - -```bash -git add . -git commit -m "Deploy Medusa App on Heroku" -git push heroku HEAD:master -``` - -### 7. Inspect your build logs - -You can explore your Heroku app build logs using the following command in your project directory. - -```bash -heroku logs -n 500000 --remote heroku --tail -``` - -### 8. Create a user (optional) - -As an optional extra step, we can create a user for you to use when your admin system is up and running. - -```bash -heroku run -a medusa-test-app -- medusa user -e "some-user@test.com" -p "SuperSecret1234" -``` - -### What's next? - -You now have a production ready application running on Heroku. This can be scaled and configured to fit your business needs. - -Furthermore, you can deploy a Medusa Admin for your application, such that you can start managing your store from an interface. - -- [Deploy Admin on Netlify](https://docs.medusajs.com/how-to/deploying-admin-on-netlify) -- Deploy Admin on Gatsby Cloud (Coming soon) diff --git a/docs/content/how-to/deploying-on-heroku.mdx b/docs/content/how-to/deploying-on-heroku.mdx new file mode 100644 index 0000000000..349f2bc8bb --- /dev/null +++ b/docs/content/how-to/deploying-on-heroku.mdx @@ -0,0 +1,273 @@ +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. + +
+ +
+ +## Prerequisites + +Before you start with this guide, you must have a Medusa server installed locally. + +To install a Medusa server, follow our [Quickstart guide](../quickstart/quick-start.md). + +## How to Deploy Your Medusa Server on Heroku + +### 1. Install the Heroku CLI + +Install the Heroku CLI tool using the instructions that belong to your operating system. + + + + +Download the appropriate installer for your Windows installation: + +[64-bit installer](https://cli-assets.heroku.com/heroku-x64.exe) + +[32-bit installer](https://cli-assets.heroku.com/heroku-x86.exe) + + + + +For Ubuntu, you can use the following command: + +```bash +sudo snap install --classic heroku +``` + +As for other Linux distributions, please check [Heroku's guide](https://devcenter.heroku.com/articles/heroku-cli#standalone-installation-with-a-tarball). + + + + +For macOS you can install Heroku's CLI tool using Homebrew: + +```bash +brew tap heroku/brew && brew install heroku +``` + +For other installation options, please check [Heroku's guide](https://devcenter.heroku.com/articles/heroku-cli#standalone-installation-with-a-tarball) + + + + +### 2. 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. + +### 3. 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. + +### 4. 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). + +### 5. 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. + +So, 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`. So, 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. + +### 6. 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\"" +}, +``` + +### 7. 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. + +## 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 +``` + +## Create a User + +As an optional extra step, you can create a user to use when your admin dashboard is up and running: + +```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. + +## What's Next :rocket: + +- Learn how to [deploy your Medusa admin on Netlify](deploying-admin-on-netlify.md). +- Learn how to [deploy your Gatsby Storefront on Netlify](deploying-gatsby-on-netlify.md). diff --git a/docs/content/how-to/deployment.module.css b/docs/content/how-to/deployment.module.css new file mode 100644 index 0000000000..f649207965 --- /dev/null +++ b/docs/content/how-to/deployment.module.css @@ -0,0 +1,10 @@ +.osTabs { + background-color: #f4f4f4; + padding: 10px; + border-radius: 6.4px; + color: #000; +} + +.osTabs li:not([aria-selected=true]) { + color: #000; +} \ No newline at end of file diff --git a/docs/content/usage/configurations.md b/docs/content/usage/configurations.md index b51027d614..69586f081a 100644 --- a/docs/content/usage/configurations.md +++ b/docs/content/usage/configurations.md @@ -283,4 +283,4 @@ const plugins = [ - Check out our [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts. - Install the [Medusa admin](../admin/quickstart.md). -- Learn about [deploying the Medusa server on Heroku](../how-to/deploying-on-heroku.md). +- Learn about [deploying the Medusa server on Heroku](../how-to/deploying-on-heroku.mdx).