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
This commit is contained in:
Shahed Nasser
GitHub
126
www/apps/docs/content/deployments/admin/general-guide.mdx
Normal file
126
www/apps/docs/content/deployments/admin/general-guide.mdx
Normal file
@@ -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 <GITHUB_URL>
|
||||
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=<ADMIN_URL>
|
||||
```
|
||||
|
||||
Where `<ADMIN_URL>` 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
|
||||
|
||||
<DetailsList
|
||||
sections={[
|
||||
{
|
||||
title: 'CORS Error',
|
||||
content: <CorsErrorSection />
|
||||
},
|
||||
]}
|
||||
/>
|
||||
@@ -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.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
:::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).
|
||||
|
||||
:::
|
||||
|
||||
<DocCardList />
|
||||
109
www/apps/docs/content/deployments/index.mdx
Normal file
109
www/apps/docs/content/deployments/index.mdx
Normal file
@@ -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
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
<DocCardList
|
||||
items={getCategoryItems({
|
||||
categoryCustomId: "deploy_backend"
|
||||
})}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
### 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.
|
||||
|
||||
:::
|
||||
|
||||
<DocCardList
|
||||
items={getCategoryItems({
|
||||
categoryCustomId: "deploy_admin"
|
||||
})}
|
||||
/>
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
:::
|
||||
|
||||
<DocCardList
|
||||
items={getCategoryItems({
|
||||
categoryCustomId: "deploy_storefront"
|
||||
})}
|
||||
/>
|
||||
@@ -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 `<YOUR_APP_URL>/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 `<YOUR_APP_URL>/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 <EMAIL> --password <PASSWORD>
|
||||
npx medusa user --email <EMAIL> --password <PASSWORD>
|
||||
```
|
||||
|
||||
Make sure to replace `<EMAIL>` and `<PASSWORD>` with the credentials you want to give the user.
|
||||
|
||||
@@ -178,7 +178,7 @@ Where `<YOUR_STOREFRONT_URL>` 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 `<YOUR_APP_URL>/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 `<YOUR_APP_URL>/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 <APP_NAME>
|
||||
|
||||
Where `<APP_NAME>` 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 `<APP_NAME>` is the name of the app and `<COMMAND>` is the command you wan
|
||||
For example, to create an admin user you can run the following command:
|
||||
|
||||
```bash
|
||||
heroku run -a <APP_NAME> -- medusa user -e "<EMAIL>" -p "<PASSWORD>"
|
||||
heroku run -a <APP_NAME> -- npx medusa user -e "<EMAIL>" -p "<PASSWORD>"
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of your Heroku app, and `<EMAIL>` and `<PASSWORD>` are the credentials you want to use to log in to the Medusa admin dashboard.
|
||||
|
||||
@@ -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 `<AccessUrl>/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 `<AccessUrl>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 `<YOUR_APP_URL>/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 `<YOUR_APP_URL>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 `<BACKEND_URL>/health`, where `<BACKEND_URL>` 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 `<BACKEND_URL>/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 `<BACKEND_URL>/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
|
||||
```
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
<DocCardList />
|
||||
@@ -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 <GITHUB_URL>
|
||||
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=<STORE_URL>
|
||||
```
|
||||
|
||||
Where `<STORE_URL>` 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
|
||||
|
||||
<DetailsList
|
||||
sections={[
|
||||
{
|
||||
title: 'CORS Error',
|
||||
content: <CorsErrorSection />
|
||||
},
|
||||
]}
|
||||
/>
|
||||
@@ -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.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
<DocCardList />
|
||||
@@ -13,23 +13,31 @@ Find in this page the upgrade guides that require necessary steps when upgrading
|
||||
## Backend
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Backend')}
|
||||
item={getFirstCategoryItem({
|
||||
categoryLabel: 'Backend'
|
||||
})}
|
||||
/>
|
||||
|
||||
## Admin Dashboard
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Admin Dashboard')}
|
||||
item={getFirstCategoryItem({
|
||||
categoryLabel: 'Admin Dashboard'
|
||||
})}
|
||||
/>
|
||||
|
||||
## Medusa React
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Medusa React')}
|
||||
item={getFirstCategoryItem({
|
||||
categoryLabel: 'Medusa React'
|
||||
})}
|
||||
/>
|
||||
|
||||
## Medusa UI
|
||||
|
||||
<DocCard
|
||||
item={getFirstCategoryItem('Medusa UI')}
|
||||
item={getFirstCategoryItem({
|
||||
categoryLabel: 'Medusa UI'
|
||||
})}
|
||||
/>
|
||||
|
||||
@@ -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",
|
||||
|
||||
1
www/apps/docs/src/types/index.d.ts
vendored
1
www/apps/docs/src/types/index.d.ts
vendored
@@ -56,6 +56,7 @@ declare module "@medusajs/docs" {
|
||||
sidebar_is_divider_line?: boolean
|
||||
sidebar_is_back_link?: boolean
|
||||
sidebar_badge?: BadgeProps
|
||||
category_id?: string
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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]
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user