asyavee/medusa-store
1
0
Fork 0
Code Issues Pull Requests Actions 2 Packages Projects Releases Wiki Activity

docs: improvements to deployment guides (#6183)

Browse Source 
- 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
2024-01-24 10:22:50 +02:00
committed by GitHub
parent b3d013940f
commit 75fd6b0c83
15 changed files with 718 additions and 57 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
www/apps/docs/content/deployments/server/deploying-on-digital-ocean.md
View File

@@ -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.

80
www/apps/docs/content/deployments/server/deploying-on-heroku.mdx
View File

@@ -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
www/apps/docs/content/deployments/server/deploying-on-microtica.md
View File

@@ -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.
---

69
www/apps/docs/content/deployments/server/deploying-on-railway.md
View File

@@ -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.
---

71
www/apps/docs/content/deployments/server/general-guide.md
View File

@@ -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
```

3
www/apps/docs/content/deployments/server/index.mdx
View File

@@ -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 />