chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
224ebb2154
commit
4fe28f5a95
6187 files changed
+601447
-598226
No files matched your search
@@ -0,0 +1,76 @@
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Medusa Admin`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you’ll learn the general steps to follow when deploying the Medusa Admin separately from the Medusa application.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Deployed Medusa application.
|
||||
- [GitHub repository with the Medusa Admin's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure Build Command
|
||||
|
||||
In the `package.json` of the Medusa application, add or change a build script for the admin:
|
||||
|
||||
```json title="package.json"
|
||||
"scripts": {
|
||||
// other scripts
|
||||
"build:admin": "medusa-admin build --deployment",
|
||||
}
|
||||
```
|
||||
|
||||
When using the `--deployment` option, the Medusa application's URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. You'll configure this environment variable in a later step.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Hosting Provider
|
||||
|
||||
The steps to deploy the admin are 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 application.
|
||||
- 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" }]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS on the Deployed Application
|
||||
|
||||
To send requests from the Medusa Admin dashboard to the Medusa application, set the `ADMIN_CORS` environment variable on your Medusa application to the admin’s URL:
|
||||
|
||||
```bash
|
||||
ADMIN_CORS=<ADMIN_URL>
|
||||
```
|
||||
|
||||
Where `<ADMIN_URL>` is the URL of your admin dashboard.
|
||||
|
||||
Then, restart your Medusa application. Once the application is running again, you can use your admin dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Create Admin User
|
||||
|
||||
To create an admin user, run the following command on your deployed Medusa application:
|
||||
|
||||
```bash
|
||||
npx medusa user --email admin@medusa-test.com --password supersecret
|
||||
```
|
||||
|
||||
You can then log in using the specified email and password.
|
||||
@@ -0,0 +1,135 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Admin to Vercel`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This guide explains how to deploy the Medusa Admin separately from the Medusa application to Vercel.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
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 Medusa Admin on the free plan for development purposes, but for commercial projects, you must update your Vercel plan.
|
||||
|
||||
</Note>
|
||||
|
||||
[Vercel](https://vercel.com/) is a cloud platform for static sites and serverless functions. It provides developers with a platform to deploy web projects quickly and easily.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Deployed Medusa application.
|
||||
- [Vercel account](https://vercel.com/)
|
||||
- [GitHub repository with the Medusa Admin's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure Build Script
|
||||
|
||||
In the `package.json` of the Medusa application, add or change a build script for the admin:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
// other scripts
|
||||
"build:admin": "medusa-admin build --deployment",
|
||||
}
|
||||
```
|
||||
|
||||
When using the `--deployment` option, the Medusa application's URL is loaded from the `MEDUSA_ADMIN_BACKEND_URL` environment variable. You'll configure this environment variable in a later step.
|
||||
|
||||
---
|
||||
|
||||
## Add Vercel Configurations
|
||||
|
||||
In the root directory of the Medusa application, create a new file `vercel.json` with the following content:
|
||||
|
||||
```json
|
||||
{
|
||||
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Push Changes to GitHub
|
||||
|
||||
After making all the previous changes, push them to GitHub before starting the deployment on Vercel:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "prepare repository for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Vercel
|
||||
|
||||
This section covers how to deploy the Medusa Admin, either using the Vercel website or using Vercel’s CLI tool.
|
||||
|
||||
### Option 1: Using the Vercel Website
|
||||
|
||||
This section explains how to deploy the admin using the Vercel website:
|
||||
|
||||
1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in.
|
||||
2. Click on the “Add New…” button next to the search bar.
|
||||
3. Choose Project from the dropdown.
|
||||
4. In the new page that opens, find the Git repository that holds your Medusa application or Medusa Admin and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first.
|
||||
5. In the Configure Project form:
|
||||
1. Set the Framework Preset to Other.
|
||||
2. Open the Build and Output Settings collapsible, and set the Build Command to `yarn build:admin` and the Output Directory to `build`.
|
||||
3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_ADMIN_BACKEND_URL` with the value being the URL to your deployed Medusa application.
|
||||
4. You can optionally edit the Project Name.
|
||||
6. Once you’re done, click on the “Deploy” button.
|
||||
|
||||
This will start the deployment of the admin. Once it’s done, you’ll be redirected to the main dashboard of your new project.
|
||||
|
||||
<Note>
|
||||
|
||||
At this point, when you visit the admin, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the Medusa Admin, follow along the [Configure CORS on the Medusa Application](#configure-cors-on-the-medusa-application) section.
|
||||
|
||||
</Note>
|
||||
|
||||
### Option 2: Using Vercel’s CLI Tool
|
||||
|
||||
This section explains how to deploy the admin using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli).
|
||||
|
||||
In the directory of your Medusa application, run the following command to deploy your Medusa Admin:
|
||||
|
||||
```bash
|
||||
vercel --build-env MEDUSA_ADMIN_BACKEND_URL=<YOUR_APP_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_APP_URL>` is the URL of your deployed Medusa application.
|
||||
|
||||
You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the admin to an existing project, or change the project’s name.
|
||||
|
||||
When asked, ”In which directory is your code located?”, keep the default `./` and just press Enter.
|
||||
|
||||
The project setup will then start. When asked if you want to modify the settings, answer `y`. You’ll then be asked a series of questions:
|
||||
|
||||
1. “Which settings would you like to overwrite”: select Build Command and Output Directory using the space bar, then press Enter.
|
||||
2. “What's your **Build Command**?”: enter `yarn build:admin`.
|
||||
3. “What's your **Output Directory**?”: enter `build`.
|
||||
|
||||
After that, it will take a couple of minutes for the deployment to finish. The link to the admin will be shown in the final output of the command.
|
||||
|
||||
<Note>
|
||||
|
||||
At this point, when you visit the admin, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the Medusa Admin, follow along the [Configure CORS on the Medusa Application](#configure-cors-on-the-medusa-application) section.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS on the Medusa Application
|
||||
|
||||
To send requests to the Medusa application from the admin dashboard, set the `ADMIN_CORS` environment variable on your deployed Medusa application to the admin’s URL.
|
||||
|
||||
On your Medusa application, add the following environment variable:
|
||||
|
||||
```bash
|
||||
ADMIN_CORS=<ADMIN_URL>
|
||||
```
|
||||
|
||||
Where `<ADMIN_URL>` is the URL of the deployed Medusa Admin.
|
||||
|
||||
Then, restart your Medusa application. Once the application is running again, you can use your admin dashboard.
|
||||
@@ -0,0 +1,278 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to DigitalOcean`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
[DigitalOcean](https://www.digitalocean.com/) is a reliable hosting provider that provides different ways to host websites and servers.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Production Event Bus Module installed and configured in the Medusa application, such as the [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx).
|
||||
- Production Cache Module installed and configured in the Medusa application, such as the [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx).
|
||||
- [DigitalOcean account](https://cloud.digitalocean.com/registrations/new).
|
||||
- [GitHub repository with the Medusa application's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure the Admin
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
|
||||
### Deploying with the Medusa Application
|
||||
|
||||
To deploy the admin with the Medusa application:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the [autoRebuild option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-autoRebuild-1-1) of the admin plugin:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["7"]]}
|
||||
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](!docs!/deployment).
|
||||
|
||||
### Deploying Separately
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's [serve option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-serve-1-0):
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Changes to package.json
|
||||
|
||||
Change the `start` script in `package.json` to the following:
|
||||
|
||||
```json
|
||||
"start": "medusa migrations run && medusa start"
|
||||
```
|
||||
|
||||
This ensures that migrations are run every time the Medusa application is restarted.
|
||||
|
||||
---
|
||||
|
||||
## Changes to medusa-config.js
|
||||
|
||||
In `medusa-config.js`, the `DATABASE_URL` variable is set to the environment variable `DATABASE_URL`. You have to change this as DigitalOcean provides the different details of the database connection separately.
|
||||
|
||||
Replace the previous declaration of `DATABASE_URL` in `medusa-config.js` with the following:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
const DB_USERNAME = process.env.DB_USERNAME
|
||||
const DB_PASSWORD = process.env.DB_PASSWORD
|
||||
const DB_HOST = process.env.DB_HOST
|
||||
const DB_PORT = process.env.DB_PORT
|
||||
const DB_DATABASE = process.env.DB_DATABASE
|
||||
|
||||
const DATABASE_URL =
|
||||
`postgres://${DB_USERNAME}:${DB_PASSWORD}` +
|
||||
`@${DB_HOST}:${DB_PORT}/${DB_DATABASE}`
|
||||
```
|
||||
|
||||
In addition, add to the `projectConfig` property in the exported object a new property `database_extra`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
database_extra: { ssl: { rejectUnauthorized: false } },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Changes to .gitignore
|
||||
|
||||
Your `.gitignore` may have `yarn.lock` and `package-lock.json` in it. If so, remove both or one of them to ensure they're committed with your code. Otherwise, you may face build errors after deployment.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to DigitalOcean App
|
||||
|
||||
After logging into your account, click on the Create button in the navigation bar and choose App Platform.
|
||||
|
||||
### Choose Repository
|
||||
|
||||
In the Create App page:
|
||||
|
||||
1. Choose GitHub from the Service Provider list.
|
||||
2. If you haven’t given DigitalOcean access before to your GitHub account, click on Manage Access under Source Code. You’ll then be redirected to GitHub to give DigitalOcean access.
|
||||
3. Once DigitalOcean has access to your GitHub account, you should see a Repository input. Click on it and search for the repository you created earlier.
|
||||
4. Additional inputs will show up to choose the Branch, Source Directory, and Autodeploy options.
|
||||
5. If you host your Medusa application in a monorepo, you should change the Source Directory to the directory the Medusa application. Otherwise, it can be left as is.
|
||||
|
||||
Once you’re done, click Next to move on to the next step.
|
||||
|
||||
### Specify Web Service Resources
|
||||
|
||||
Click on the Edit button next to the Web Service, and ensure the following information is set correctly:
|
||||
|
||||
- Resource Type is set to Node.js
|
||||
- HTTP Port is set to 9000
|
||||
- HTTP Request Routes is set to `/`
|
||||
|
||||
Once you've set up everything correctly, click the Back button at the end of the form.
|
||||
|
||||
### Specify Database Resources
|
||||
|
||||
On the same page:
|
||||
|
||||
1. Expand the Add Resources section, choose Database, then click Add.
|
||||
2. In the new page, you’ll be shown a PostgreSQL database to be created. It’s important to choose a name that you’ll remember as you’ll need the name in next steps. You can leave the name as is if it’s not necessary to change it.
|
||||
3. Once you’re done, click Create and Attach. You’ll be redirected back to the previous page with the database added to the resources.
|
||||
|
||||
Once you’re done, click Next to move on to the next step.
|
||||
|
||||
### Set Environment Variables
|
||||
|
||||
Click Edit on the second row to add environment variables specific to the Web Service. Add the following environment variables:
|
||||
|
||||
```bash
|
||||
DB_USERNAME=${db.USERNAME}
|
||||
DB_PASSWORD=${db.PASSWORD}
|
||||
DB_HOST=${db.HOSTNAME}
|
||||
DB_PORT=${db.PORT}
|
||||
DB_DATABASE=${db.DATABASE}
|
||||
REDIS_URL=${redis.DATABASE_URL}
|
||||
JWT_SECRET=secret
|
||||
COOKIE_SECRET=secret
|
||||
NPM_CONFIG_PRODUCTION=false
|
||||
YARN_PRODUCTION=false
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
Notice how for database environment variables you access the values from the database you created earlier `db`. If you changed the name of the database, you must change `db` here to the name you supplied to the PostgreSQL database.
|
||||
|
||||
Another thing to note here is that you added a `REDIS_URL` environment variable that uses a `redis` resource to retrieve the URL. Redis is necessary if you're using Scheduled Jobs and if you're using Redis modules, such as the Redis Event Bus module. You’ll be creating the Redis resource in a later section.
|
||||
|
||||
If you're using modules that require setting other environment variables, make sure to set them here. You can also add them later.
|
||||
|
||||
<Note type="warning">
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
</Note>
|
||||
|
||||
Once you’re done click Save, then click Next to proceed to the next section.
|
||||
|
||||
### Finalize App
|
||||
|
||||
In the next section, you’ll be shown the app info and the region it will be deployed to. You can leave it all as is or make changes if you find it necessary.
|
||||
|
||||
Once you’re done, click Next to go to the next step.
|
||||
|
||||
In the final step, you can see a review of everything you created. If everything looks good, scroll down and click Create Resource.
|
||||
|
||||
### Create Redis Resource
|
||||
|
||||
While the Medusa application is being deployed, you can create the Redis resource. To do that:
|
||||
|
||||
1. Click the Create button at the top right and choose Databases from the dropdown.
|
||||
2. In the new page under Choose a database engine, choose Redis.
|
||||
3. Scroll down to the “Choose a unique database cluster name” input. Since you used the name `redis` in the `REDIS_URL` environment variables, change the value to `redis` here.
|
||||
4. Once you’re done, click on Create Database Cluster.
|
||||
|
||||
### Attach Redis Database
|
||||
|
||||
Once the Redis database is created, you need to attach it to your app. To do that:
|
||||
|
||||
1. Go back to the App you created earlier by choose App Platform in the sidebar then clicking on the App's name.
|
||||
2. Click the white Create button at the top right and choose Create/Attach Database.
|
||||
3. In the new page, click on the Previously Created DigitalOcean Database radio button. Then, under Database Cluster select the Redis database you just created.
|
||||
4. Once you’re done click Attach Database. This adds the Redis database to the list of resources of your App and will trigger a redeployment of the App.
|
||||
|
||||
### Change Health Check Settings
|
||||
|
||||
By default, DigitalOcean performs a health check immediately as the app runs. However, the Medusa application requires some initial load-time before it's ready for a health check.
|
||||
|
||||
So, you must delay the app's health check to enure that the deployment doesn't fail. To do that:
|
||||
|
||||
1. On your App's page, click on Settings.
|
||||
2. From the tabs before the settings section, choose the name of your web service resource.
|
||||
3. Scroll down and find the "Health Checks" section, then click on "Edit" next to it.
|
||||
4. In the section that opens, expand the "Show Advanced Parameters" section.
|
||||
5. Find the "Initial Delay (s)" input and set its value to `300`.
|
||||
6. Once done, click on the Save button.
|
||||
|
||||
This redeploys your app, which should finish successfully.
|
||||
|
||||
---
|
||||
|
||||
## Test your Deployed Medusa Application
|
||||
|
||||
Once the redeployment is complete, copy the URL of the App which can be found under the App’s name.
|
||||
|
||||
Then, go to `{your_app_url}/store/products` which returns the products in your store.
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed Medusa application.
|
||||
|
||||
### Testing the Medusa Admin
|
||||
|
||||
If you deployed the [Medusa Admin with the Medusa application](#deploying-with-the-medusa-application), you can test it by opening `{your_app_url}/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If errors occur in your deployment, find the logs by going to the Activity tab in your App.
|
||||
|
||||
### ERROR: Failed to build / Project does not contain a package manager
|
||||
|
||||
If you find this error in your logs, make sure to remove `yarn.lock` or `package-lock.json` from the `.gitignore` file in your project, then commit the changes.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on Your Medusa Application
|
||||
|
||||
To run commands on your Medusa application, 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 Medusa application.
|
||||
|
||||
### Create Admin User
|
||||
|
||||
For example, run the following command to create a new admin user:
|
||||
|
||||
```bash
|
||||
npx medusa user --email <EMAIL> --password <PASSWORD>
|
||||
```
|
||||
|
||||
Make sure to replace `<EMAIL>` and `<PASSWORD>` with the credentials you want to give the user.
|
||||
|
||||
---
|
||||
|
||||
## Add Environment Variables
|
||||
|
||||
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
|
||||
|
||||
Refer to [DigitalOcean's documentation](https://docs.digitalocean.com/products/app-platform/how-to/use-environment-variables) on how to add environment variables to your App.
|
||||
@@ -0,0 +1,158 @@
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Medusa Application`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you’ll learn the general steps you need to take when deploying your Medusa application.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Production Event Bus Module installed and configured in the Medusa application, such as the [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx).
|
||||
- Production Cache Module installed and configured in the Medusa application, such as the [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx).
|
||||
- [GitHub repository with the Medusa application's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Start Script in package.json
|
||||
|
||||
Make sure the `start` script in your `package.json` runs migrations, the `build` command, and the `medusa start` command:
|
||||
|
||||
```json title="package.json"
|
||||
"start": "npm run build && medusa migrations run && medusa start"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Set SSL Database Option
|
||||
|
||||
In production, it’s recommended to set the [database_extra option](/medusa-configurations) in `medusa-config.js` to disable the `ssl.rejectUnauthorized` option:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["4"]]}
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
database_extra: process.env.NODE_ENV !== "development" ?
|
||||
{
|
||||
ssl: {
|
||||
rejectUnauthorized: false,
|
||||
},
|
||||
} : {},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setup PostgreSQL Database
|
||||
|
||||
Your Medusa application must connect to a remote PostgreSQL database. If your hosting provider doesn’t support creating a PostgreSQL database, use [Neon](https://neon.tech/).
|
||||
|
||||
Once you set up your PostgreSQL database, make sure to have the connection URL to the database at hand so that you can set it later in your environment variables.
|
||||
|
||||
---
|
||||
|
||||
## Configure the Admin
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
|
||||
### Deploying with the Medusa Application
|
||||
|
||||
To deploy the admin with the Medusa application:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the [autoRebuild option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-autoRebuild-1-1) of the admin plugin:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["7"]]}
|
||||
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](!docs!/deployment).
|
||||
|
||||
### Deploying Separately
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's [serve option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-serve-1-0):
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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 Event Bus Module](../../../architectural-modules/event/redis/page.mdx), you must set up a Redis database and obtain a connection URL to it.
|
||||
|
||||
---
|
||||
|
||||
## Set Environment Variables
|
||||
|
||||
During or after the deployment process, set the following environment variables:
|
||||
|
||||
```bash
|
||||
DATABASE_TYPE=postgres
|
||||
DATABASE_URL=<YOUR_DB_URL>
|
||||
JWT_SECRET=<RANDOM_SECRET>
|
||||
COOKIE_SECRET=<RANDOM_SECRET>
|
||||
NODE_ENV=production
|
||||
NPM_CONFIG_PRODUCTION=false
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<YOUR_DB_URL>` is the connection URL to the PostgreSQL database.
|
||||
- `<RANDOM_SECRET>` is a random string that will be used to create authentication and cookie tokens. Make sure to set different ones for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
Also, add any other environment variables relevant to your Medusa application. For example, if you’ve setup Redis, make sure to add an environment variable for the Redis connection URL.
|
||||
|
||||
---
|
||||
|
||||
## Test the Deployed Medusa Application
|
||||
|
||||
After you’ve deployed your Medusa application, you can test it out in different ways:
|
||||
|
||||
- Go to `{your_app_url}/health`, where `{your_app_url}` is the URL to your deployed Medusa application. If the deployment was successful, you should see `OK` printed in your browser.
|
||||
- If you deployed the [Medusa Admin with the Medusa application](#deploying-with-the-medusa-application), go to `{your_app_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.
|
||||
|
||||
---
|
||||
|
||||
## Set Up CORS Configuration
|
||||
|
||||
To connect your storefront and, if deployed separately, your admin dashboard to your deployed Medusa application, set up the [admin_cors](/medusa-configurations#admin_cors) and [store_cors](/medusa-configurations#store_cors) configurations in `medusa-config.js`.
|
||||
|
||||
---
|
||||
|
||||
## Create Admin User
|
||||
|
||||
If your hosting provider gives you access to execute commands in your deployed Medusa application project, create a new admin user by running the following command in the root directory of your deployed Medusa application:
|
||||
|
||||
```bash
|
||||
npx medusa user --email admin@medusa-test.com --password supersecret
|
||||
```
|
||||
@@ -0,0 +1,288 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Heroku`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
[Heroku](https://www.heroku.com/) is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud.
|
||||
|
||||
Alternatively, you can use this button to deploy the Medusa application to Heroku directly:
|
||||
|
||||
<a href="https://heroku.com/deploy?template=https://github.com/medusajs/medusa-starter-default/tree/feat/deploy-heroku">
|
||||
<img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy to Heroku" className="mb-1" />
|
||||
</a>
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Production Event Bus Module installed and configured in the Medusa application, such as the [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx).
|
||||
- Production Cache Module installed and configured in the Medusa application, such as the [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx).
|
||||
- [Heroku account](https://www.heroku.com/).
|
||||
- [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli).
|
||||
- [GitHub repository with the Medusa application's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure the Admin
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
|
||||
### Deploying with the Medusa Application
|
||||
|
||||
To deploy the Medusa Admin with the Medusa application:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the [autoRebuild option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-autoRebuild-1-1) of the admin plugin:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["7"]]}
|
||||
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](!docs!/deployment).
|
||||
|
||||
### Deploying Separately
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's [serve option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-serve-1-0):
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Heroku
|
||||
|
||||
### Login to Heroku from your CLI
|
||||
|
||||
Before you can create an app with Heroku, you must login with the CLI tool:
|
||||
|
||||
```bash
|
||||
heroku login
|
||||
```
|
||||
|
||||
Follow the instructions to log in.
|
||||
|
||||
### Create an App with Heroku
|
||||
|
||||
In the root directory of your Medusa application, run the following commands to create an app on Heroku and add it as a remote origin:
|
||||
|
||||
```bash
|
||||
heroku create medusa-app
|
||||
heroku git:remote -a medusa-app
|
||||
```
|
||||
|
||||
Where `medusa-app` is the name of the heroku app you're creating. You can use any name you want.
|
||||
|
||||
### Add PostgreSQL Add-On
|
||||
|
||||
Add a PostgreSQL add-on to your Heroku app with the following command:
|
||||
|
||||
```bash
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
```
|
||||
|
||||
This uses Heroku Postgres's smallest plan. Check out [the available plans and pricing of Heroku Postgres on Heroku's website.](https://elements.heroku.com/addons/heroku-postgresql#pricing)
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
The Heroku PostgreSQL add-on automatically adds the connection URL in the environment variable `DATABASE_URL`. If you use a different PostgreSQL , make sure to set the `DATABASE_URL` environment variable.
|
||||
|
||||
</Note>
|
||||
|
||||
### Add Redis Add-On
|
||||
|
||||
Add a Redis instance to your Heroku app with the following command:
|
||||
|
||||
```bash
|
||||
heroku addons:create stackhero-redis:ist-m4euc0
|
||||
```
|
||||
|
||||
This uses the lowest plan in Stackhero Redis. Check out [the plans and pricing of Stackhero Redis on Heroku's website.](https://elements.heroku.com/addons/stackhero-redis#pricing)
|
||||
|
||||
To retrieve the Redis connection URL and use it later to set it as an environment variable, run the following command:
|
||||
|
||||
```bash
|
||||
heroku config:get STACKHERO_REDIS_URL_TLS
|
||||
```
|
||||
|
||||
### Note about Modules
|
||||
|
||||
If you use modules that require setting up other resources, add them at this point.
|
||||
|
||||
### Configure Environment Variables on Heroku
|
||||
|
||||
Run the following commands in the root directory of your Medusa application to set necessary environment variables:
|
||||
|
||||
```bash
|
||||
heroku config:set NODE_ENV=production
|
||||
heroku config:set JWT_SECRET=your-super-secret
|
||||
heroku config:set COOKIE_SECRET=your-super-secret-pt2
|
||||
heroku config:set NPM_CONFIG_PRODUCTION=false
|
||||
heroku config:set REDIS_URL="{redis_url}"
|
||||
```
|
||||
|
||||
Make sure to replace `{redis_url}` with the Redis connection URL.
|
||||
|
||||
You can also add other environment variables for the modules you're using here.
|
||||
|
||||
<Note type="warning">
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
</Note>
|
||||
|
||||
### Set Buildpack
|
||||
|
||||
Set the buildpack to Node.js using the following command:
|
||||
|
||||
```bash
|
||||
heroku buildpacks:set heroku/nodejs
|
||||
```
|
||||
|
||||
### Changes to package.json
|
||||
|
||||
Update the `scripts` in `package.json` to include the following scripts:
|
||||
|
||||
```json title="package.json"
|
||||
"scripts": {
|
||||
// other scripts
|
||||
"serve": "medusa start",
|
||||
"heroku-postbuild": "medusa migrations run",
|
||||
"prepare": "npm run build",
|
||||
},
|
||||
```
|
||||
|
||||
### Changes to medusa-config.js
|
||||
|
||||
Add to the `projectConfig` property in the exported object a new property `database_extra`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
database_extra: { ssl: { rejectUnauthorized: false } },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Push Changes
|
||||
|
||||
Finally, commit and push all changes to Heroku:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Deploy Medusa Application on Heroku"
|
||||
git push heroku HEAD:master
|
||||
```
|
||||
|
||||
This triggers a redeployment of the Medusa application with all the new configurations.
|
||||
|
||||
---
|
||||
|
||||
## Test the Deployed Application
|
||||
|
||||
To test your deployed Medusa application, run the following command to retrieve the application's URL:
|
||||
|
||||
```bash
|
||||
heroku apps:info -a medusa-app
|
||||
```
|
||||
|
||||
Where `medusa-app` is the name of the app. You should see as the output a bunch of info of the app.
|
||||
|
||||
The Medusa application's URL is available under "Web URL". Copy it and perform requests to it to test it out.
|
||||
|
||||
For example, send a request to `{your_app_url}/store/products` which returns the products in your store.
|
||||
|
||||
### Health Route
|
||||
|
||||
Access `/health` to get health status of your deployed Medusa application.
|
||||
|
||||
### Testing the Medusa Admin
|
||||
|
||||
If you deployed the [Medusa Admin with the Medusa Application](#deploying-with-the-medusa-application), you can test it by opening `{your_app_url}/app` in the browser. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Inspect Build Logs
|
||||
|
||||
If an error occurs during the deployment, run the following command in the root directory of your Medusa application to view the Heroku logs:
|
||||
|
||||
```bash
|
||||
heroku logs -n 500000 --remote heroku --tail -a medusa-app
|
||||
```
|
||||
|
||||
Where `medusa-app` is the name of the app.
|
||||
|
||||
### Error: Babel not found
|
||||
|
||||
If you get the following error in the logs of your application:
|
||||
|
||||
```bash
|
||||
/bin/sh: 1: /app/node_modules/.bin/babel: not found
|
||||
```
|
||||
|
||||
Create the file `Procfile` in the root directory of your Medusa application with the following content:
|
||||
|
||||
```
|
||||
web: npm run serve
|
||||
```
|
||||
|
||||
Then, push the changes:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Added Procfile"
|
||||
git push heroku HEAD:master
|
||||
```
|
||||
|
||||
Once the application is redeployed, the error is resolved.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on Your Medusa Application
|
||||
|
||||
To run commands on your deployed Medusa application, use the following command:
|
||||
|
||||
```bash
|
||||
heroku run -a medusa-app -- {command}
|
||||
```
|
||||
|
||||
Where `medusa-app` is the name of the app and `{command}` is the command you want to run.
|
||||
|
||||
### Create Admin User
|
||||
|
||||
For example, to create an admin user, run the following command:
|
||||
|
||||
```bash
|
||||
heroku run -a medusa-app -- npx medusa user -e "<EMAIL>" -p "<PASSWORD>"
|
||||
```
|
||||
|
||||
Where `medusa-app` 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.
|
||||
@@ -0,0 +1,151 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Microtica`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note>
|
||||
|
||||
This guide was submitted through a community contribution.
|
||||
|
||||
</Note>
|
||||
|
||||
[Microtica](https://microtica.com) is a cloud-native delivery platform that enables you to deploy infrastructure and applications to your AWS account, while providing actionable insights to help you optimize resources, performance, & costs.
|
||||
|
||||
Alternatively, you can use this button to deploy the Medusa application to Microtica directly:
|
||||
|
||||
<a href="https://app.microtica.com/templates/new?template=https%3A%2F%2Fraw.githubusercontent.com%2Fmicrotica%2Ftemplates%2Fmaster%2Fmedusa-server%2F.microtica%2Ftemplate.yaml&utm_source=medusa&utm_medium=docs&utm_campaign=medusa" className="img-url">
|
||||
<img src="https://microtica.s3.eu-central-1.amazonaws.com/assets/templates/logos/deploy-with-microtica.svg" alt="Deploy with Microtica" className="no-zoom-img" />
|
||||
</a>
|
||||
|
||||
## What is provisioned on AWS
|
||||
|
||||
The Medusa infrastructure is provisioned on your own AWS account. You retain full control over your infrastructure and data while getting all the benefits of infrastructure automation.
|
||||
|
||||
Since Microtica deploys on your cloud account, here are the resources that the platform is going to provision in the environment:
|
||||
|
||||
- VPC, subnets and networking
|
||||
- Container infrastructure based on Fargate
|
||||
- application load balancer
|
||||
- persistent storage
|
||||
- S3 bucket
|
||||
- Postgres database
|
||||
- and Redis (in production mode)
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Production Event Bus Module installed and configured in the Medusa application, such as the [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx).
|
||||
- Production Cache Module installed and configured in the Medusa application, such as the [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx).
|
||||
- [Microtica account](https://app.microtica.com/).
|
||||
- [AWS account](https://aws.amazon.com/)
|
||||
- [GitHub repository with the Medusa application's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Configure the Admin
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
|
||||
#### Deploying with the Medusa Application
|
||||
|
||||
To deploy the admin with the Medusa application:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the [autoRebuild option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-autoRebuild-1-1) of the admin plugin:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["7"]]}
|
||||
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](!docs!/deployment).
|
||||
|
||||
#### Deploying Separately
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's [serve option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-serve-1-0):
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Microtica
|
||||
|
||||
### Configure the Template
|
||||
|
||||
Add an application name and the admin credentials that will be used to create an initial admin user with which you can later sign in to your Medusa Admin.
|
||||
|
||||
Then, choose whether you want a production Medusa application environment or a development one. The production template will provision your managed Relational Database Service (RDS) PostgreSQL and Redis instances.
|
||||
|
||||
### Connect an AWS account
|
||||
|
||||
In the last step before deployment, select the environment in which you want to deploy the template. An existing default environment called `development` will be preselected here, or you can create a new environment.
|
||||
|
||||
Then, connect your AWS account when prompted. This process takes only a few seconds, so afterward only choose the region you want to deploy in.
|
||||
|
||||
### Deploy to AWS
|
||||
|
||||
Finally, a deployment summary of what will be provisioned on your AWS account is presented. Click on the "Deploy" button to trigger a deployment of the template and start creating the infrastructure for a Medusa application.
|
||||
|
||||
It will take around ten minutes for the solution to be deployed on your cloud account.
|
||||
|
||||
You can follow the build pipeline in real-time by clicking the "View Logs" button.
|
||||
|
||||
Once the build process is complete, a new deployment with the infrastructure resources is triggered. You can follow the logs of the deployment process by clicking the "View deployment" button, and then selecting the deployment from the list.
|
||||
|
||||
---
|
||||
|
||||
## Test the Medusa Application
|
||||
|
||||
After the deployment is finished, navigate to Resources → [AppName] (Medusa in this example) → Overview. Then, under the Resource Outputs section you should see the "AccessUrl". This is the Medusa application's URL that you can use to access API Routes and test them. You can try getting the list of products using the API Route `<AccessUrl>/store/products`.
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed Medusa application.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
If you deployed the [admin dashboard with the Medusa application](#deploying-with-the-medusa-application), 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.
|
||||
|
||||
---
|
||||
|
||||
## Add Environment Variables
|
||||
|
||||
The environment variables can be updated, added, or configured after deployment as well. You can access them with `process.env.<VARIABLE NAME>`.
|
||||
|
||||
You can read more about the built-in environment variables, as well as how to specify custom environment variables in the Medusa application runtime [in Microtica documentation](https://docs.microtica.com/medusa-server?utm_source=medusa&utm_medium=docs&utm_campaign=medusa#z8li6).
|
||||
|
||||
---
|
||||
|
||||
## Updating your Deployed Medusa Application
|
||||
|
||||
Any updates to the Medusa application (for example, updating the Medusa core version) are deployed automatically when changes are committed to the repository. Microtica will handle the entire process of building and deploying your application on your connected AWS account.
|
||||
@@ -0,0 +1,225 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Railway`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
[Railway](https://railway.app/) is a hosting provider that you can use to deploy web applications and databases without having to worry about managing the full infrastructure.
|
||||
|
||||
You can deploy a Medusa application to Railway instantly with this button:
|
||||
|
||||
<a
|
||||
href="https://railway.app/template/zC7eOq?referralCode=TW4Qi0">
|
||||
<img src="https://railway.app/button.svg" alt="Deploy with Railway" className="mb-1"/>
|
||||
</a>
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Production Event Bus Module installed and configured in the Medusa application, such as the [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx).
|
||||
- Production Cache Module installed and configured in the Medusa application, such as the [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx).
|
||||
- [Railway account](https://railway.app).
|
||||
- [GitHub repository with the Medusa application's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure the Admin
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
|
||||
### Deploying with the Medusa Application
|
||||
|
||||
To deploy the admin with the Medusa application:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the [autoRebuild option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-autoRebuild-1-1) of the admin plugin:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["7"]]}
|
||||
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](!docs!/deployment).
|
||||
|
||||
### Deploying Separately
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's [serve option](../../../configurations/medusa-admin/page.mdx#Plugin_Options-serve-1-0):
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
## 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, create the file `nixpacks.toml` in the root of your Medusa application that configure Nixpacks to either use `yarn` or add the `--legacy-peer-deps` option to `npm install`:
|
||||
|
||||
```toml title="nixpacks.toml"
|
||||
[phases.setup]
|
||||
nixPkgs = ['nodejs', 'yarn']
|
||||
|
||||
[phases.install]
|
||||
cmds=['yarn install']
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Railway
|
||||
|
||||
In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the Medusa application from the GitHub repository.
|
||||
|
||||
### Create the PostgreSQL Database
|
||||
|
||||
On the Railway dashboard:
|
||||
|
||||
1. Click on the ”New Project” button.
|
||||
2. Choose from the dropdown the ”Provision PostgreSQL” option.
|
||||
|
||||
A new database is created and, after a few seconds, you'll be redirected to the project page with the created database.
|
||||
|
||||
### Create the Redis Database
|
||||
|
||||
In the same project view:
|
||||
|
||||
1. Click on the New button.
|
||||
2. Choose the Database option.
|
||||
3. Choose Add Redis.
|
||||
|
||||
A new Redis database is added to the project view.
|
||||
|
||||
### Note about Modules
|
||||
|
||||
If you use modules that require setting up other resources, add them at this point.
|
||||
|
||||
### Deploy the Medusa Application Repository
|
||||
|
||||
In the same project view:
|
||||
|
||||
1. Click on the New button.
|
||||
2. Choose the ”GitHub Repo” option.
|
||||
3. If you still haven't given GitHub permissions to Railway, choose the ”Configure GitHub App” option to do that.
|
||||
4. Choose the repository from the GitHub Repo dropdown.
|
||||
|
||||
It takes the Medusa application a few minutes for the deployment to finish. It may fail since you haven't added the environment variables yet.
|
||||
|
||||
### Configure Environment Variables
|
||||
|
||||
To configure the environment variables of your Medusa application:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
2. Choose the Variables tab.
|
||||
3. Add the following environment variables:
|
||||
|
||||
```bash
|
||||
PORT=9000
|
||||
JWT_SECRET=something
|
||||
COOKIE_SECRET=something
|
||||
DATABASE_URL=${{Postgres.DATABASE_URL}}
|
||||
REDIS_URL=${{Redis.REDIS_URL}}
|
||||
```
|
||||
|
||||
Notice that the values of `DATABASE_URL` and `REDIS_URL` reference the values from the PostgreSQL and Redis databases you created.
|
||||
|
||||
<Note type="warning">
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
</Note>
|
||||
|
||||
Make sure to add any other environment variables that are relevant for you here. For example, you can add environment variables related to Medusa Admin or your modules.
|
||||
|
||||
### Change Start Command
|
||||
|
||||
The start command is the command used to run the application. You’ll change it to run any available migrations, then run the Medusa application. This way it's guaranteed that migrations from your customizations or Medusa updates always run first before the application starts.
|
||||
|
||||
To change the start command of your Medusa application:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
2. Click on the Settings tab and scroll down to the Deploy section.
|
||||
3. Paste the following in the Custom Start Command field:
|
||||
|
||||
```bash
|
||||
medusa migrations run && medusa start
|
||||
```
|
||||
|
||||
### Add Domain Name
|
||||
|
||||
The last step is to add a domain name to your Medusa application. To do that:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
2. Click on the Settings tab and scroll down to the Networking section.
|
||||
3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain.
|
||||
|
||||
---
|
||||
|
||||
## Test the Deployed Application
|
||||
|
||||
Every change you make to the settings redeploys the Medusa application. You can check the deployments of the application by clicking on the GitHub repository’s card and choosing the Deployments tab.
|
||||
|
||||
After the application is redeployed successfully, open the app in your browser using the domain name. For example, you can open the URL `{your_app_url}/store/products` which returns the products in your store.
|
||||
|
||||
### Health Route
|
||||
|
||||
Access `/health` to get health status of your deployed application.
|
||||
|
||||
### Testing the Medusa Admin
|
||||
|
||||
If you deployed the Medusa Admin with the application, 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
|
||||
|
||||
If you run into any issues or a problem with your deployed application, check the logs in your Railway container instance:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
2. Click on the Deployments tab.
|
||||
3. Click on the View Logs button.
|
||||
|
||||
### Error: connect ENOENT
|
||||
|
||||
This error may be thrown by a module that uses Redis. If you see it in your build or deploy logs, make sure that your Redis configurations are correct.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on the Medusa Application
|
||||
|
||||
To run commands on your Medusa application, you can use [Railway’s CLI tool to run a local shell and execute commands](https://docs.railway.app/develop/cli#local-shell).
|
||||
|
||||
For example, you can run commands on the application to seed the database or create a new user using [Medusa’s CLI tool](../../../medusa-cli/page.mdx).
|
||||
|
||||
### Create Admin User
|
||||
|
||||
Create an admin user by running the following command in the root of your Medusa application directory:
|
||||
|
||||
```bash
|
||||
railway run npx medusa user --email admin@medusa-test.com --password supersecret
|
||||
```
|
||||
@@ -0,0 +1,9 @@
|
||||
import { ChildDocs } from "docs-ui"
|
||||
|
||||
export const metadata = {
|
||||
title: `Deployments`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<ChildDocs />
|
||||
@@ -0,0 +1,45 @@
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Next.js Starter`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this guide, you’ll learn the general steps to follow when deploying the Next.js Starter.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Deployed Medusa application.
|
||||
- [GitHub repository with the Next.js Starter's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Deploy to Hosting Provider
|
||||
|
||||
The steps to deploy the Next.js Starter are 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. If not:
|
||||
- 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 application.
|
||||
- `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).
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS on the Deployed Medusa Application
|
||||
|
||||
To send requests from the Next.js Starter storefront to the Medusa application, you must set the `STORE_CORS` environment variable on your Medusa application to the storefront’s URL:
|
||||
|
||||
```bash
|
||||
STORE_CORS=<STORE_URL>
|
||||
```
|
||||
|
||||
Where `<STORE_URL>` is the URL of your storefront.
|
||||
|
||||
Then, restart your Medusa application. Once the Medusa application is running again, you can use your storefront.
|
||||
@@ -0,0 +1,99 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Admin to Vercel`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
This guide explains how to deploy the Medusa Admin separately from the Medusa application to Vercel.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
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 Next.js Starter on the free plan for development purposes, but for commercial projects, you must update your Vercel plan.
|
||||
|
||||
</Note>
|
||||
|
||||
[Vercel](https://vercel.com/) is a cloud platform for static sites and serverless functions. It provides developers with a platform to deploy web projects quickly and easily.
|
||||
|
||||
<Note type="check">
|
||||
|
||||
- Deployed Medusa application.
|
||||
- [Vercel account](https://vercel.com/)
|
||||
- [GitHub repository with the Next.js Starter's code](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-new-repository).
|
||||
|
||||
</Note>
|
||||
|
||||
## Deploy to Vercel
|
||||
|
||||
This section covers how to deploy the storefront, either using the Vercel website or using Vercel’s CLI tool.
|
||||
|
||||
### Option 1: Using the Vercel Website
|
||||
|
||||
This section explains how to deploy the storefront using the Vercel website:
|
||||
|
||||
1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in.
|
||||
2. Click on the “Add New…” button next to the search bar.
|
||||
3. Choose Project from the dropdown.
|
||||
4. In the new page that opens, find the Git repository that holds your Next.js Starter Template and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first.
|
||||
5. In the Configure Project form:
|
||||
1. Open the Environment Variables collapsible, and add the following environment variables:
|
||||
- `NEXT_PUBLIC_MEDUSA_BACKEND_URL`: the URL to your deployed Medusa application.
|
||||
- `NEXT_PUBLIC_BASE_URL`: The URL of your storefront. If you don't have a domain ready yet, you can add it later. However, you may face some errors in your 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).
|
||||
2. You can optionally edit the Project Name.
|
||||
6. Once you’re done, click on the “Deploy” button.
|
||||
|
||||
This will start the deployment of the storefront. Once it’s done, you’ll be redirected to the main dashboard of your new project.
|
||||
|
||||
<Note>
|
||||
|
||||
At this point, when you visit the storefront, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the storefront, follow along the [Configure CORS on the storefront](#configure-cors-on-the-medusa-application) section.
|
||||
|
||||
</Note>
|
||||
|
||||
### Option 2: Using Vercel’s CLI Tool
|
||||
|
||||
This section explains how to deploy the storefront using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli).
|
||||
|
||||
In the directory holding your storefront, run the following command to deploy your storefront:
|
||||
|
||||
```bash
|
||||
vercel --build-env NEXT_PUBLIC_MEDUSA_BACKEND_URL=<YOUR_APP_URL>
|
||||
vercel --build-env NEXT_PUBLIC_BASE_URL=<YOUR_BASE_URL>
|
||||
vercel --build-env REVALIDATE_SECRET=<YOUR_REVALIDATION_SECRET>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
- `<YOUR_APP_URL>`: the URL of your deployed Medusa application.
|
||||
- `<YOUR_BASE_URL>`: The URL of your storefront. If you don't have a domain ready yet, you can add it later. However, you may face some errors in your storefront.
|
||||
- `<YOUR_REVALIDATION_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).
|
||||
|
||||
You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the storefront to an existing project, or change the project’s name.
|
||||
|
||||
When asked `In which directory is your code located?`, keep the default `./` and just press Enter.
|
||||
|
||||
The project setup will then start. When asked if you want to modify the settings, answer `N` to keep the default settings.
|
||||
|
||||
It'll take a couple of minutes for the deployment to finish. The link to the storefront will be shown in the final output of the command.
|
||||
|
||||
<Note>
|
||||
|
||||
At this point, when you visit the storefront, you'll face errors related to Cross-Origin Resource Sharing (CORS). Before you start using the storefront, follow along the [Configure CORS on the storefront](#configure-cors-on-the-medusa-application) section.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS on the Medusa application
|
||||
|
||||
To send requests to the Medusa application from the Next.js Starter, set the `STORE_CORS` environment variable on your Medusa application to the deployed storefront's URL.
|
||||
|
||||
On your Medusa application, add the following environment variable:
|
||||
|
||||
```bash
|
||||
STORE_CORS=<STOREFRONT_URL>
|
||||
```
|
||||
|
||||
Where `<STOREFRONT_URL>` is the URL of your storefront.
|
||||
|
||||
Then, restart your Medusa application. Once the application is running again, you can use your storefront.
|
||||
Reference in new issue
Block a user