From 75fd6b0c830da75a2be09696cded675c640e3a5e Mon Sep 17 00:00:00 2001 From: Shahed Nasser Date: Wed, 24 Jan 2024 10:22:50 +0200 Subject: [PATCH] docs: improvements to deployment guides (#6183) - Add a new deployment overview page giving a general overview of how a Medusa project is deployed - Add a new section in all backend deployment guides related to the Medusa admin. - Add a general deployment guide for the medusa admin. - Add a general deployment guide for the Next.js starter --- .../deployments/admin/general-guide.mdx | 126 ++++++++++++++++++ .../docs/content/deployments/admin/index.mdx | 9 +- www/apps/docs/content/deployments/index.mdx | 109 +++++++++++++++ .../server/deploying-on-digital-ocean.md | 72 ++++++++-- .../server/deploying-on-heroku.mdx | 80 +++++++++-- .../server/deploying-on-microtica.md | 66 ++++++++- .../server/deploying-on-railway.md | 69 ++++++++-- .../deployments/server/general-guide.md | 71 +++++++++- .../docs/content/deployments/server/index.mdx | 3 +- .../deployments/storefront/general-guide.mdx | 96 +++++++++++++ .../content/deployments/storefront/index.mdx | 3 +- .../docs/content/upgrade-guides/index.mdx | 16 ++- www/apps/docs/sidebars.js | 33 +++++ www/apps/docs/src/types/index.d.ts | 1 + .../docs/src/utils/get-first-category-item.ts | 21 ++- 15 files changed, 718 insertions(+), 57 deletions(-) create mode 100644 www/apps/docs/content/deployments/admin/general-guide.mdx create mode 100644 www/apps/docs/content/deployments/index.mdx create mode 100644 www/apps/docs/content/deployments/storefront/general-guide.mdx diff --git a/www/apps/docs/content/deployments/admin/general-guide.mdx b/www/apps/docs/content/deployments/admin/general-guide.mdx new file mode 100644 index 0000000000..f68b7d3e84 --- /dev/null +++ b/www/apps/docs/content/deployments/admin/general-guide.mdx @@ -0,0 +1,126 @@ +--- +description: "General steps for deploying the admin." +addHowToData: true +--- + +import DetailsList from '@site/src/components/DetailsList' +import CorsErrorSection from '../../troubleshooting/cors-issues.md' + +# General Deployment Guide for Medusa Admin + +In this guide, you’ll learn the general steps to follow when deploying the Medusa admin separately from the backend. This guide isn’t tailored towards any hosting provider. + +## Prerequisites + +### Medusa Project + +Before you deploy the admin, you need a Medusa project with the backend and admin plugin. You can refer to [this guide to learn how to install it](../../create-medusa-app.mdx). + +### Deployed Medusa Backend + +The deployed admin must connect to a publicly deployed backend. So, deploy the backend first to obtain its URL. + +You can follow one of [these backend deployment guides](../server/index.mdx). + +--- + +## (Optional) Step 1: Create GitHub Repository + +Many hosting providers allow you to deploy your project directly from GitHub. This makes it easier for you to push changes and updates without having to manually trigger the update in the hosting provider. + +If your hosting provider supports that, create a GitHub repository and push the Medusa backend project’s code to it: + +:::note + +Even though you’re just deploying the admin, you must include the entire Medusa backend project in the deployed repository. The build process of the admin uses many of the backend’s dependencies. + +::: + +```bash +git init +git remote add origin +git add . +git commit -m "initial commit" +git push +``` + +--- + +## Step 2: Configure Build Command + +In the `package.json` of the Medusa backend, add or change a build script for the admin: + +```json title="package.json" +"scripts": { + // other scripts + "build:admin": "medusa-admin build --deployment", +} +``` + +:::note + +When using the `--deployment` option, the backend's URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. You'll configure this environment variable in a later step. + +::: + +--- + +## Step 3: Deploy to Hosting Provider + +The steps to deploy the admin can be different based on the hosting provider you use. The following points cover common configurations across hosting providers: + +- If your hosting provider supports choosing a Framework Preset, choose the “Other” option as the Medusa admin doesn’t follow known framework presets. +- Set the build command of your deployed project to use the `build:admin` command: + +```bash npm2yarn +npm run build:admin +``` + +- Set the output directory of your deployed project to `build`. +- Add the environment variable `MEDUSA_ADMIN_BACKEND_URL` and set its value to the URL of your deployed Medusa backend. +- If your hosting provider supports URL rewrites, add a configuration to rewrite the `/(.*)` URL pattern to `/index.html`. For example, if you’re deploying to Vercel you add the following in `vercel.json`: + +```json +{ + "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }] +} +``` + +--- + +## Step 4: Configure CORS on the Deployed Backend + +To send requests from the admin dashboard to the Medusa backend, you must set the `ADMIN_CORS` environment variable on your backend to the admin’s URL: + +```bash +ADMIN_CORS= +``` + +Where `` is the URL of your admin dashboard that you just deployed. + +Then, restart your Medusa backend. Once the backend is running again, you can use your admin dashboard. + +--- + +## Step 5: (Optional) Create Admin User + +To log in to the admin dashboard, you must have an admin user. To create one, run the following command on your deployed backend: + +```bash +npx medusa user --email admin@medusa-test.com --password supersecret +``` + +You can then log in using the specified email and password. + +--- + +## Troubleshooting + + + }, + ]} +/> diff --git a/www/apps/docs/content/deployments/admin/index.mdx b/www/apps/docs/content/deployments/admin/index.mdx index b5b8202536..1daad57bbd 100644 --- a/www/apps/docs/content/deployments/admin/index.mdx +++ b/www/apps/docs/content/deployments/admin/index.mdx @@ -4,10 +4,15 @@ description: 'Learn how to deploy the Medusa Admin to different hosting provider --- import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; # Medusa Admin Deployment Guides Find in this page guides to deploy your Medusa Admin on different platforms. - \ No newline at end of file +:::note + +These guides are for deploying the admin separately from the backend. If you want to deploy them together, you can refer to the [deployment guides of the backend](../server/index.mdx). Learn more [here](../index.mdx#deploying-the-medusa-admin). + +::: + + \ No newline at end of file diff --git a/www/apps/docs/content/deployments/index.mdx b/www/apps/docs/content/deployments/index.mdx new file mode 100644 index 0000000000..71e8945bca --- /dev/null +++ b/www/apps/docs/content/deployments/index.mdx @@ -0,0 +1,109 @@ +--- +description: "In this document, learn about the general approach of deploying a Medusa project. This includes how to deploy the backend, admin, and storefront." +--- + +import DocCardList from '@theme/DocCardList'; +import { getCategoryItems } from '@site/src/utils/get-first-category-item'; + +# Deployment Overview + +In this document, you’ll learn about the different ways you can deploy your Medusa project. + +## Overview + +A standard Medusa project is made up of the following: + +- Medusa backend +- Medusa admin +- One or more storefronts + +![Diagram showcasing the connection between the three deployed components](https://res.cloudinary.com/dza7lstvk/image/upload/v1705999238/Medusa%20Docs/Diagrams/Social_Media_Graphics_2024_options_uxzmlx.jpg) + +This guide details options to consider when deploying each of these components in your Medusa project. + +--- + +## Deploying the Medusa Backend + +You must deploy the Medusa backend before the admin or storefront, as both of them connect to the backend and won’t work without a deployed Medusa backend URL. + +![Diagram showcasing how the Medusa admin and its associated services would be deployed](https://res.cloudinary.com/dza7lstvk/image/upload/v1705999287/Medusa%20Docs/Diagrams/Social_Media_Graphics_2024_backend_deployment__1_twbdsd.jpg) + +The Medusa backend is a Node.js server. So, it must be deployed to a hosting provider that supports deploying servers, such as Railway, DigitalOcean, AWS, Heruko, etc… + +:::tip + +For optimal experience, make sure that the hosting provider and plan offer at least 2GB of RAM. + +::: + +Your backend connects to PostgreSQL and Redis databases. Most hosting providers support deploying and managing these databases along with your Medusa backend (such as Railway and DigitalOcean). You can also choose a separate hosting for either of them and connect to them with Medusa’s configurations. + + + +--- + +## Deploying the Medusa Admin + +There are two options to deploy the Medusa admin: + +### Deploy Admin with Backend + +Since the Medusa admin is a plugin installed in the backend, you may choose to host it along with the backend. + +In this scenario, make sure the hosting provider and plan of your choice provide at least 2GB of RAM, as the admin build requires high RAM usage. + +![Diagram showcasing how the admin would be deployed along with the Medusa backend.](https://res.cloudinary.com/dza7lstvk/image/upload/v1705999347/Medusa%20Docs/Diagrams/Social_Media_Graphics_2024_Admin_Deployment_q5qxan.jpg) + +The backend deployment guides mention details on how to deploy the admin along with the backend. + +### Deploy Admin through GitHub Action + +Alternatively, if you host your backend’s code on GitHub, you can: + +1. Disable the [`autoRebuild` option](../admin/configuration.mdx#plugin-options) of the admin plugin. +2. Create a GitHub action that builds the admin before the deployment is triggered. + +With this solution, the hosting provider doesn’t handle the admin building, decreasing the RAM usage. + +![Diagram showcasing how the admin can be built through a GitHub action before deployment](https://res.cloudinary.com/dza7lstvk/image/upload/v1705999378/Medusa%20Docs/Diagrams/Social_Media_Graphics_2024_admin_deployment_1_rdzzkp.jpg) + +### Deploy Admin Separately + +You may choose to deploy the admin into a separate hosting provider or instance. The admin can be hosted on providers that support front-end websites and frameworks, such as Vercel. + +:::note + +As per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the admin on the free plan for development purposes, but for commercial projects, you must update your Vercel plan. + +::: + + + +--- + +## Deploying the Storefront + +The storefront is deployed separately from the Medusa backend, and the hosting options depend on the tools and frameworks you use to create the storefront. + +If you’re using the Next.js starter, you may deploy the storefront to any hosting provider that supports frontend frameworks, such as Vercel. + +:::note + +As per Vercel’s [license and plans](https://vercel.com/pricing), their free plan can only be used for personal, non-commercial projects. So, you can deploy the storefront on the free plan for development purposes, but for commercial projects, you must update your Vercel plan. + +::: + + diff --git a/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md b/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md index b04e43af9c..54bd73485e 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md +++ b/www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md @@ -94,6 +94,66 @@ Your `.gitignore` may have `yarn.lock` and `package-lock.json` in it. If so, rem --- +## (Optional) 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). + +::: + +--- + ## (Optional) Use Production Modules If you're using development modules, such as the Local Event Bus or the In-Memory Cache Modules, it's highly recommended to use a production module instead. @@ -280,13 +340,7 @@ You can access `/health` to get health status of your deployed backend. ### Testing the Admin -:::note - -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. - -::: - -If you deployed the admin dashboard alongside 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. +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. --- @@ -304,10 +358,10 @@ If you find this error in your logs, make sure to remove `yarn.lock` or `package 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: +For example, you can run the following command to create a new admin user: ```bash -npx @medusajs/medusa-cli user --email --password +npx medusa user --email --password ``` Make sure to replace `` and `` with the credentials you want to give the user. diff --git a/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx b/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx index 4b820e83af..00b587ff33 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx +++ b/www/apps/docs/content/deployments/server/deploying-on-heroku.mdx @@ -178,7 +178,7 @@ Where `` is the URL of your storefront. ### 5. Configure Medusa Backend -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. +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 @@ -216,7 +216,65 @@ Update `scripts` to include the following scripts: }, ``` -### 6. Launch your Medusa Backend +### (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: @@ -228,6 +286,8 @@ 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: @@ -248,17 +308,13 @@ You can access `/health` to get health status of your deployed backend. ### Testing the Admin -:::note +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. -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the `serve` command of your backend. +--- -::: +## Troubleshooting -If you deployed the admin dashboard alongside 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 +### 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: @@ -268,7 +324,7 @@ heroku logs -n 500000 --remote heroku --tail -a Where `` is the name of the app. -#### Error: Babel not found +### Error: Babel not found If you get the following error in the logs of your application: @@ -307,7 +363,7 @@ Where `` is the name of the app and `` is the command you wan For example, to create an admin user you can run the following command: ```bash -heroku run -a -- medusa user -e "" -p "" +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. diff --git a/www/apps/docs/content/deployments/server/deploying-on-microtica.md b/www/apps/docs/content/deployments/server/deploying-on-microtica.md index 08f9a0bb29..ed8ce396e3 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-microtica.md +++ b/www/apps/docs/content/deployments/server/deploying-on-microtica.md @@ -66,6 +66,64 @@ Furthermore, your Medusa backend should be configured to work with PostgreSQL an ## Deploy to Microtica +### (Optional) Step 0: 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). + +::: + ### Step 1: Create/Import a Git repository Before you can deploy your Medusa backend you need to connect your preferred Git account. Microtica will create a repository on your Git account with a default repo name `medusa-server`. @@ -108,13 +166,7 @@ You can access `/health` to get health status of your deployed backend. ### Testing the Admin -:::note - -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. - -::: - -If you deployed the admin dashboard alongside 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. +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. --- diff --git a/www/apps/docs/content/deployments/server/deploying-on-railway.md b/www/apps/docs/content/deployments/server/deploying-on-railway.md index 4afe05c6f1..d12ce5069c 100644 --- a/www/apps/docs/content/deployments/server/deploying-on-railway.md +++ b/www/apps/docs/content/deployments/server/deploying-on-railway.md @@ -54,6 +54,66 @@ If you're using development modules for events and caching, it's highly recommen --- +## (Optional) Step 0: 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). + +::: + +--- + ## (Optional) Step 1: Add Nixpacks Configurations If you've created your project using `create-medusa-app`, you might receive errors during the deployment process as Railway uses NPM by default. To avoid that, you need to configure Nixpacks to either use `yarn` or add the `--legacy-peer-deps` option to `npm install`. @@ -128,7 +188,6 @@ In the same project view: A new Redis database will be added to the project view in a few seconds. Click on it to open the database sidebar. - ### Note about Modules 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. @@ -219,13 +278,7 @@ You can access `/health` to get health status of your deployed backend. ### Testing the Admin -:::note - -Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/configuration.mdx#build-command-options) command as part of the start command of your backend. - -::: - -If you deployed the admin dashboard alongside 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. +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. --- diff --git a/www/apps/docs/content/deployments/server/general-guide.md b/www/apps/docs/content/deployments/server/general-guide.md index b9b865b2cb..2223df5749 100644 --- a/www/apps/docs/content/deployments/server/general-guide.md +++ b/www/apps/docs/content/deployments/server/general-guide.md @@ -1,5 +1,5 @@ --- -description: "General steps for all hosting providers." +description: "General steps for deploying the backend." addHowToData: true --- @@ -59,13 +59,73 @@ Once you set up your PostgreSQL database, make sure to have the connection URL t --- -## (Optional) Step 5: Setup Architectural Services +## (Optional) Step 5: 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 hosting provider and 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). + +::: + +--- + +## (Optional) Step 6: Setup Architectural Services Aside from PostgreSQL, you may be using modules or plugins that require some additional architectural setup. For example, if you’re using the [Redis Events Module](../../development/events/modules/redis.md), you must set up a Redis database and obtain a connection URL to it. --- -## Step 6: Deploy your Backend +## Step 7: Deploy your Backend You can deploy your backend now to your hosting provider. During or after the deployment process, based on your hosting provider, you need to add the following environment variables: @@ -87,12 +147,12 @@ Make sure to also add any other environment variables relevant to your backend. --- -## Step 7: Test it Out +## Step 8: Test it Out After you’ve deployed your backend, you can test it out in different ways: - Go to `/health`, where `` is the URL to your deployed backend. If the deployment was successful, you should see `OK` printed in your browser. -- If you deployed the admin dashboard, you can go to `/app` to view the admin dashboard. If you changed the value of the admin plugin’s `path` configuration, make sure to replace `app` with that instead. +- If you deployed the [admin dashboard with the backend](#deploying-with-the-backend), you can go to `/app` to view the admin dashboard. If you changed the value of the admin plugin’s `path` configuration, make sure to replace `app` with that instead. --- @@ -109,4 +169,3 @@ If your hosting provider gives you access to execute commands in your deployed M ```bash npx medusa user --email admin@medusa-test.com --password supersecret ``` - diff --git a/www/apps/docs/content/deployments/server/index.mdx b/www/apps/docs/content/deployments/server/index.mdx index 931e45786c..4149286621 100644 --- a/www/apps/docs/content/deployments/server/index.mdx +++ b/www/apps/docs/content/deployments/server/index.mdx @@ -4,10 +4,9 @@ description: 'Learn how to deploy your Medusa backend to different hosting provi --- import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; # Medusa Backend Deployment Guides Find in this page guides to deploy your Medusa backend on different platforms. - \ No newline at end of file + \ No newline at end of file diff --git a/www/apps/docs/content/deployments/storefront/general-guide.mdx b/www/apps/docs/content/deployments/storefront/general-guide.mdx new file mode 100644 index 0000000000..d72882a4e4 --- /dev/null +++ b/www/apps/docs/content/deployments/storefront/general-guide.mdx @@ -0,0 +1,96 @@ +--- +description: "General steps for deploying the Next.js starter." +addHowToData: true +--- + +import DetailsList from '@site/src/components/DetailsList' +import CorsErrorSection from '../../troubleshooting/cors-issues.md' + +# General Deployment Guide for Next.js Starter + +In this guide, you’ll learn the general steps to follow when deploying the Next.js starter storefront. This guide isn’t tailored towards any hosting provider. + +## Prerequisites + +### Deployed Medusa Backend + +The deployed storefront must connect to a publicly deployed backend. So, deploy the backend first to obtain its URL. + +You can follow one of [these backend deployment guides](../server/index.mdx). + +### Installed Storefront + +You must have an installed Next.js storefront before proceeding with the deployment. You can refer to [this installation guide](../../starters/nextjs-medusa-starter.mdx). + +--- + +## Step 1: Storefront Preparations + +If you're not using the [Serverless Modules](../../starters/nextjs-medusa-starter.mdx#using-serverless-modules) in your storefront, either delete the `src/app/api` directory or exclude it in `.gitignore`. + +Otherwise, the deployment may fail. + +--- + +## (Optional) Step 2: Create GitHub Repository + +Many hosting providers allow you to deploy your project directly from GitHub. This makes it easier for you to push changes and updates without having to manually trigger the update in the hosting provider. + +If your hosting provider supports that, create a GitHub repository and push the Next.js starter’s code: + +```bash +git init +git remote add origin +git add . +git commit -m "initial commit" +git push +``` + +--- + +## Step 3: Deploy to Hosting Provider + +The steps to deploy the Next.js starter can be different based on the hosting provider you use. The following points cover common configurations across hosting providers: + +- If your hosting provider supports choosing a framework preset, set it to Next.js. You can then skip setting the build command and output directory as they are default Next.js configurations. +- Set the build command of your deployed project to the `build` command: + +```bash npm2yarn +npm run build +``` + +- Set the output directory of your deployed project to `.next`. +- Add the following environment variables: + - `NEXT_PUBLIC_MEDUSA_BACKEND_URL`: The URL of your deployed Medusa backend. + - `NEXT_PUBLIC_BASE_URL`: The URL of the storefront. If you still don’t have the URL you can wait until later to add it. However, you may face errors when using the storefront. + - `REVALIDATE_SECRET`: A secret used for revalidating data. Learn more in the [Next.js documentation](https://nextjs.org/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating#on-demand-revalidation). + - If you’re using serverless modules: + - Set `MEDUSA_FF_MEDUSA_V2` to `true`. + - Set `POSTGRES_URL` to the connection URL of the PostgreSQL database. + +--- + +## Step 4: Configure CORS on the Deployed Backend + +To send requests from the Next.js starter storefront to the Medusa backend, you must set the `STORE_CORS` environment variable on your backend to the storefront’s URL: + +```bash +STORE_CORS= +``` + +Where `` is the URL of your Next.js starter storefront that you just deployed. + +Then, restart your Medusa backend. Once the backend is running again, you can use your storefront. + +--- + +## Troubleshooting + + + }, + ]} +/> \ No newline at end of file diff --git a/www/apps/docs/content/deployments/storefront/index.mdx b/www/apps/docs/content/deployments/storefront/index.mdx index 65d6e0e6bb..7e35b0c197 100644 --- a/www/apps/docs/content/deployments/storefront/index.mdx +++ b/www/apps/docs/content/deployments/storefront/index.mdx @@ -4,10 +4,9 @@ description: 'Learn how to deploy your storefronts to different hosting provider --- import DocCardList from '@theme/DocCardList'; -import {useCurrentSidebarCategory} from '@docusaurus/theme-common'; # Storefront Deployment Guides Find in this page guides to deploy your storefront on different platforms. - \ No newline at end of file + \ No newline at end of file diff --git a/www/apps/docs/content/upgrade-guides/index.mdx b/www/apps/docs/content/upgrade-guides/index.mdx index 94e2756e52..1212f6e0ba 100644 --- a/www/apps/docs/content/upgrade-guides/index.mdx +++ b/www/apps/docs/content/upgrade-guides/index.mdx @@ -13,23 +13,31 @@ Find in this page the upgrade guides that require necessary steps when upgrading ## Backend ## Admin Dashboard ## Medusa React ## Medusa UI diff --git a/www/apps/docs/sidebars.js b/www/apps/docs/sidebars.js index bf6f3e97c7..c1a01f4837 100644 --- a/www/apps/docs/sidebars.js +++ b/www/apps/docs/sidebars.js @@ -322,6 +322,10 @@ module.exports = { customProps: { sidebar_icon: "cloud-arrow-up", }, + link: { + type: "doc", + id: "deployments/index", + }, items: [ { type: "category", @@ -371,6 +375,10 @@ module.exports = { "https://res.cloudinary.com/dza7lstvk/image/upload/v1681296578/Medusa%20Docs/Other/aF4ZuDS_t11rcu.png", dark: "https://res.cloudinary.com/dza7lstvk/image/upload/v1681296612/Medusa%20Docs/Other/Lg7NHQk_qo6oax.png", }, + badge: { + variant: "blue", + children: "Community", + }, }, }, { @@ -382,6 +390,9 @@ module.exports = { }, }, ], + customProps: { + category_id: "deploy_backend", + }, }, { type: "category", @@ -403,7 +414,18 @@ module.exports = { }, }, }, + { + type: "doc", + id: "deployments/admin/general-guide", + label: "General Deployment", + customProps: { + iconName: "academic-cap-solid", + }, + }, ], + customProps: { + category_id: "deploy_admin", + }, }, { type: "category", @@ -425,7 +447,18 @@ module.exports = { }, }, }, + { + type: "doc", + id: "deployments/storefront/general-guide", + label: "General Deployment", + customProps: { + iconName: "academic-cap-solid", + }, + }, ], + customProps: { + category_id: "deploy_storefront", + }, }, ], className: "homepage-sidebar-item", diff --git a/www/apps/docs/src/types/index.d.ts b/www/apps/docs/src/types/index.d.ts index 9d6a254eaf..23ae233336 100644 --- a/www/apps/docs/src/types/index.d.ts +++ b/www/apps/docs/src/types/index.d.ts @@ -56,6 +56,7 @@ declare module "@medusajs/docs" { sidebar_is_divider_line?: boolean sidebar_is_back_link?: boolean sidebar_badge?: BadgeProps + category_id?: string } } diff --git a/www/apps/docs/src/utils/get-first-category-item.ts b/www/apps/docs/src/utils/get-first-category-item.ts index ea5468f69e..41910645c1 100644 --- a/www/apps/docs/src/utils/get-first-category-item.ts +++ b/www/apps/docs/src/utils/get-first-category-item.ts @@ -4,11 +4,22 @@ import { } from "@docusaurus/theme-common/internal" import { PropSidebarItem } from "@docusaurus/plugin-content-docs" -export default function getFirstCategoryItem( - categoryLabel: string -): PropSidebarItem | undefined { +type Options = { + categoryLabel?: string + categoryCustomId?: string +} + +export function getCategoryItems({ categoryLabel, categoryCustomId }: Options) { return findSidebarCategory( useDocsSidebar().items, - (item) => item.label === categoryLabel - )?.items[0] + (item) => + item.label === categoryLabel || + item.customProps.category_id === categoryCustomId + )?.items +} + +export default function getFirstCategoryItem( + options: Options +): PropSidebarItem | undefined { + return getCategoryItems(options)?.[0] }