docs: updates to Medusa server deployment guides (#8268)
* updated railway deployment docs * general updates and fixes
This commit is contained in:
Shahed Nasser
GitHub
@@ -4,7 +4,13 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn about the different methods to deploy your Medusa application.
|
||||
In this chapter, you’ll learn about the approach to deploy your Medusa application.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
As Medusa v2 is still in active development, it's highly recommended not to deploy it for production purposes.
|
||||
|
||||
</Note>
|
||||
|
||||
## Medusa Project Components
|
||||
|
||||
@@ -15,7 +21,7 @@ A standard Medusa project is made up of:
|
||||
|
||||
|
||||
|
||||
You can either deploy the Medusa application fully (server along with the admin), or deploy the Medusa Admin separately. As for the storefront, it's always deployed separately.
|
||||
You can either deploy the Medusa application fully (server with the admin), or deploy the Medusa Admin separately. The storefront is always deployed separately.
|
||||
|
||||
---
|
||||
|
||||
@@ -33,7 +39,7 @@ For optimal experience, make sure that the hosting provider and plan offer at le
|
||||
|
||||
</Note>
|
||||
|
||||
Your server connects to a PostgreSQL database and, optionally, Redis or other services. Most hosting providers support deploying and managing these databases along with your Medusa server (such as Railway and DigitalOcean).
|
||||
Your server connects to a PostgreSQL database, Redis, and other services relevant for your setup. Most hosting providers support deploying and managing these databases along with your Medusa server (such as Railway and DigitalOcean).
|
||||
|
||||
Refer to [this reference](!resources!/deployment) to find how-to deployment guides for specific hosting providers.
|
||||
|
||||
@@ -51,7 +57,7 @@ In this scenario, make sure the hosting provider and plan of your choice provide
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
The server deployment guides mention details on how to deploy the admin along with the backend.
|
||||
The server deployment guides mention details on how to deploy the admin with the Medusa server.
|
||||
|
||||
</Note>
|
||||
|
||||
@@ -73,7 +79,7 @@ Refer to [this reference](!resources!/deployment) to find how-to deployment guid
|
||||
|
||||
The storefront is deployed separately from the Medusa application, 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.
|
||||
If you’re using the Next.js Starter storefront, you may deploy the storefront to any hosting provider that supports frontend frameworks, such as Vercel.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
sidebar_label: "General Guide"
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Medusa Admin`,
|
||||
}
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
sidebar_label: "Vercel"
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Admin to Vercel`,
|
||||
}
|
||||
|
||||
@@ -1,284 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to DigitalOcean`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
The following deployment guide doesn't support Medusa v2 yet.
|
||||
|
||||
</Note>
|
||||
|
||||
[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 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:
|
||||
|
||||
```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 `databaseExtra`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
databaseExtra: { 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.
|
||||
@@ -1,164 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Medusa Application`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
The following deployment guide doesn't support Medusa v2 yet.
|
||||
|
||||
</Note>
|
||||
|
||||
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 [databaseExtra option](/references/medusa-config#databaseExtra) in `medusa-config.js` to disable the `ssl.rejectUnauthorized` option:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["4"]]}
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
databaseExtra: 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 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:
|
||||
|
||||
```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 [adminCors](/references/medusa-config#adminCors) and [storeCors](/references/medusa-config#storeCors) properties of the `http` configuration 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
|
||||
```
|
||||
@@ -1,294 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Heroku`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
The following deployment guide doesn't support Medusa v2 yet.
|
||||
|
||||
</Note>
|
||||
|
||||
[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 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:
|
||||
|
||||
```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 `databaseExtra`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
databaseExtra: { 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.
|
||||
@@ -1,157 +0,0 @@
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Microtica`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
|
||||
The following deployment guide doesn't support Medusa v2 yet.
|
||||
|
||||
</Note>
|
||||
|
||||
<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 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:
|
||||
|
||||
```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.
|
||||
@@ -1,231 +1,420 @@
|
||||
---
|
||||
sidebar_label: "Railway"
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Application to Railway`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
In this document, you’ll learn how to deploy your Medusa application to [Railway](https://railway.app/).
|
||||
|
||||
The following deployment guide doesn't support Medusa v2 yet.
|
||||
<Note title="Important">
|
||||
|
||||
As Medusa v2 is still in active development, it's highly recommended not to deploy it for production purposes.
|
||||
|
||||
</Note>
|
||||
|
||||
[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.
|
||||
## What You’ll Deploy
|
||||
|
||||
You can deploy a Medusa application to Railway instantly with this button:
|
||||
1. PostgreSQL database.
|
||||
2. Redis database.
|
||||
3. Medusa application in server mode.
|
||||
4. Medusa application in worker mode.
|
||||
5. (Optional) Medusa Admin.
|
||||
|
||||
<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>
|
||||
|
||||
The same Medusa project is used to deploy the server and worker modes. Learn more about the `workerMode` configuration in [this document](/references/medusa-config#workermode).
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
<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).
|
||||
- [Medusa application](!docs!) hosted in a GitHub repository.
|
||||
|
||||
</Note>
|
||||
|
||||
## Configure the Admin
|
||||
## 1. Configure Medusa Application
|
||||
|
||||
If you're using the Medusa Admin plugin, you have two options to deploy it: either with the Medusa application or separately.
|
||||
### Worker Mode
|
||||
|
||||
### Deploying with the Medusa Application
|
||||
The `workerMode` configuration determines which mode the Medusa application runs in. As mentioned at the beginning of this guide, you’ll deploy two Medusa applications: one in server mode, and one in worker mode.
|
||||
|
||||
To deploy the admin with the Medusa application:
|
||||
So, add the following configuration in `medusa-config.js`:
|
||||
|
||||
1. Your chosen plan must offer at least 2GB of RAM.
|
||||
2. Enable the autoRebuild option 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...
|
||||
},
|
||||
```js title="medusa-config.js"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
// ...
|
||||
workerMode: process.env.MEDUSA_WORKER_MODE
|
||||
},
|
||||
]
|
||||
})
|
||||
|
||||
```
|
||||
|
||||
Alternatively, you can use a GitHub action to build the admin as explained [here](!docs!/deployment).
|
||||
Later, you’ll set different values of the `MEDUSA_WORKER_MODE` environment variable for each Medusa application deployment.
|
||||
|
||||
### Deploying Separately
|
||||
### Configure Medusa Admin
|
||||
|
||||
To deploy the admin separately, disable the admin plugin's serve option:
|
||||
There are two cases where you may disable the Medusa Admin in your deployed Medusa application:
|
||||
|
||||
```js title="medusa-config.js" highlights={[["10"]]}
|
||||
const plugins = [
|
||||
1. If you choose to host it separately.
|
||||
2. In the Medusa application running in worker mode, as it doesn’t need to run the admin.
|
||||
|
||||
<Note>
|
||||
|
||||
To host the admin with the Medusa application, the hosting provider and plan should offer at least 2GB of RAM.
|
||||
|
||||
</Note>
|
||||
|
||||
Add the following configuration in `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
{
|
||||
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...
|
||||
},
|
||||
},
|
||||
]
|
||||
admin: {
|
||||
disable: process.env.DISABLE_MEDUSA_ADMIN === "true"
|
||||
}
|
||||
})
|
||||
|
||||
```
|
||||
|
||||
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`.
|
||||
Later, you’ll set different values of the `DISABLE_MEDUSA_ADMIN` environment variable.
|
||||
|
||||
You can alternatively remove the admin plugin for the plugins array.
|
||||
### Configure Redis URL
|
||||
|
||||
---
|
||||
Add the following configuration in `medusa-config.js` :
|
||||
|
||||
## Add Nixpacks Configurations
|
||||
```js title="medusa-config.js"
|
||||
module.exports = defineConfig({
|
||||
projectConfig: {
|
||||
// ...
|
||||
redisUrl: process.env.REDIS_URL
|
||||
},
|
||||
})
|
||||
|
||||
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
|
||||
## 2. Add predeploy Script
|
||||
|
||||
In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the Medusa application from the GitHub repository.
|
||||
Before you start the Medusa application in production, you should always run migrations and sync links.
|
||||
|
||||
### Create the PostgreSQL Database
|
||||
So, add the following script in `package.json`:
|
||||
|
||||
On the Railway dashboard:
|
||||
```json
|
||||
"scripts": {
|
||||
// ...
|
||||
"predeploy": "medusa migrations run && medusa links sync"
|
||||
},
|
||||
```
|
||||
|
||||
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.
|
||||
## 3. Install Production Modules and Providers
|
||||
|
||||
### Create the Redis Database
|
||||
By default, your Medusa application uses modules and providers useful for development, such as the In-Memory Cache Module or the Local File Module Provider.
|
||||
|
||||
In the same project view:
|
||||
It’s highly recommended to instead install modules and providers suitable for production, including:
|
||||
|
||||
1. Click on the New button.
|
||||
2. Choose the Database option.
|
||||
3. Choose Add Redis.
|
||||
- [Redis Cache Module](../../../architectural-modules/cache/redis/page.mdx)
|
||||
- [Redis Event Bus Module](../../../architectural-modules/event/redis/page.mdx)
|
||||
- [Workflow Engine Redis Module](../../../architectural-modules/workflow-engine/redis/page.mdx)
|
||||
- [S3 File Module Provider](../../../architectural-modules/file/s3/page.mdx) (or other file module providers production-ready).
|
||||
- [SendGrid Notification Module Provider](../../../architectural-modules/notification/sendgrid/page.mdx) (or other notification module providers production-ready).
|
||||
|
||||
A new Redis database is added to the project view.
|
||||
For example, add the following dependencies in `package.json` for the Cache, Event Bus, and Workflow Engine modules:
|
||||
|
||||
### Note about Modules
|
||||
```json
|
||||
"dependencies": {
|
||||
// ...
|
||||
"@medusajs/cache-redis": "preview",
|
||||
"@medusajs/event-bus-redis": "preview",
|
||||
"@medusajs/workflow-engine-redis": "preview"
|
||||
}
|
||||
```
|
||||
|
||||
If you use modules that require setting up other resources, add them at this point.
|
||||
Then, add these modules in `medusa-config.js`:
|
||||
|
||||
### Deploy the Medusa Application Repository
|
||||
```js title="medusa-config.js"
|
||||
import { Modules } from '@medusajs/utils'
|
||||
|
||||
In the same project view:
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: {
|
||||
// ...
|
||||
[Modules.CACHE]: {
|
||||
resolve: "@medusajs/cache-redis",
|
||||
options: {
|
||||
redisUrl: process.env.REDIS_URL,
|
||||
},
|
||||
},
|
||||
[Modules.EVENT_BUS]: {
|
||||
resolve: "@medusajs/event-bus-redis",
|
||||
options: {
|
||||
redisUrl: process.env.REDIS_URL,
|
||||
},
|
||||
},
|
||||
[Modules.WORKFLOW_ENGINE]: {
|
||||
resolve: "@medusajs/workflow-engine-redis",
|
||||
options: {
|
||||
redis: {
|
||||
url: process.env.REDIS_URL,
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
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.
|
||||
<Note title="Tip">
|
||||
|
||||
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.
|
||||
Check out the [Integrations](../../../integrations/page.mdx) and [Architectural Modules](../../../architectural-modules/page.mdx) documentation for other modules and providers to use.
|
||||
|
||||
### Configure Environment Variables
|
||||
</Note>
|
||||
|
||||
To configure the environment variables of your Medusa application:
|
||||
---
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
## 4. Create Railway Project and Host PostgreSQL Database
|
||||
|
||||
<Note>
|
||||
|
||||
Push all changes you’ve made in the previous step to the GitHub repository before proceeding.
|
||||
|
||||
</Note>
|
||||
|
||||
To create a Railway project:
|
||||
|
||||
1. Go to [Railway](https://railway.app/), and log in or create an account.
|
||||
2. In your account dashboard, click the New Project button.
|
||||
3. Choose Database → Deploy PostgreSQL
|
||||
|
||||
This creates a new project with just a PostgreSQL database. You’ll add more services in the next steps.
|
||||
|
||||
---
|
||||
|
||||
## 5. Add Redis Database to Project
|
||||
|
||||
To add a Redis database service to your project:
|
||||
|
||||
1. Click on the Create button at the top right.
|
||||
2. Choose Database → Add Redis
|
||||
|
||||
---
|
||||
|
||||
## 6. Deploy the Medusa Application in Server Mode
|
||||
|
||||
In this section, you’ll add a Medusa application service in server mode to the Railway project, configure, and deploy it.
|
||||
|
||||
### Create Service
|
||||
|
||||
To create the service for the Medusa application in server mode:
|
||||
|
||||
1. Click on the Create button.
|
||||
2. Choose GitHub Repo.
|
||||
3. Choose the repository of your Medusa application.
|
||||
|
||||
This adds a new service to your project.
|
||||
|
||||
### Add Environment Variables
|
||||
|
||||
To add environment variables to the Medusa application in server mode:
|
||||
|
||||
1. Click on its card in the project dashboard.
|
||||
2. Choose the Variables tab.
|
||||
3. Add the following environment variables:
|
||||
3. Click on RAW Editor, and paste the following in the editor:
|
||||
|
||||
```bash
|
||||
COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
|
||||
JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
|
||||
STORE_CORS= # STOREFRONT URL
|
||||
ADMIN_CORS= # ADMIN URL
|
||||
AUTH_CORS= # STOREFRONT AND ADMIN URLS, SEPARATED BY COMMAS
|
||||
# change to false if you're hosting the admin with the application
|
||||
DISABLE_MEDUSA_ADMIN=true
|
||||
MEDUSA_WORKER_MODE=worker
|
||||
PORT=9000
|
||||
JWT_SECRET=something
|
||||
COOKIE_SECRET=something
|
||||
DATABASE_URL=${{Postgres.DATABASE_URL}}
|
||||
REDIS_URL=${{Redis.REDIS_URL}}
|
||||
DATABASE_URL=${{Postgres.DATABASE_PUBLIC_URL}}
|
||||
POSTGRES_URL=${{Postgres.DATABASE_PUBLIC_URL}}
|
||||
REDIS_URL=${{Redis.REDIS_PUBLIC_URL}}
|
||||
```
|
||||
|
||||
Notice that the values of `DATABASE_URL` and `REDIS_URL` reference the values from the PostgreSQL and Redis databases you created.
|
||||
Where:
|
||||
|
||||
<Note type="warning">
|
||||
- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
|
||||
- `STORE_CORS`'s value is the URL of your storefront. If you don’t have it yet, you can skip adding it for now.
|
||||
- `ADMIN_CORS`'s value is the URL of the admin dashboard. If you don’t have it yet, or you’re deploying the admin with the Medusa application, you can skip adding it for now.
|
||||
- `AUTH_CORS`'s value is the URLs of any application authenticating users, customers, or other actor types, such as the storefront and admin URLs. The URLs are separated by commas. If you don’t have the URLs yet, you can set its value later.
|
||||
- Change `DISABLE_MEDUSA_ADMIN` to `false` if you’re hosting the admin with the Medusa application.
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
Feel free to add any other relevant environment variables. Once you’re done, click the Update Variables button.
|
||||
|
||||
### Set Start Command
|
||||
|
||||
To set the `start` command of your Medusa application in server mode:
|
||||
|
||||
1. Click on its card in the project dashboard.
|
||||
2. Choose the Settings tab.
|
||||
3. Scroll down to the Deploy section.
|
||||
4. For the “Custom Start Command” field, enter the following and click the check mark button:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run redeploy && npm run start
|
||||
```
|
||||
|
||||
### Deploy Changes
|
||||
|
||||
To deploy the changes of the Medusa application in server mode, click on the Deploy button at the top center of the project. This takes a couple of minutes.
|
||||
|
||||
### Set Domain Name
|
||||
|
||||
You can either generate a random domain name or set a custom one. To do that:
|
||||
|
||||
1. Click on the Medusa application running in server mode.
|
||||
2. Choose the Settings tab.
|
||||
3. Scroll down to the Networking section.
|
||||
4. Under Public Networking, click on Generate domain to generate a domain name or Custom domain to add your custom domain.
|
||||
1. Choose the `9000` port.
|
||||
5. Save the changes.
|
||||
|
||||
### Additional Configuration if Deploying with Admin
|
||||
|
||||
If you’re deploying the Medusa application in server mode with the admin, you have to make some changes now that you’ve obtained the application’s URL.
|
||||
|
||||
First, add the following configuration to `medusa-config.js`:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
admin: {
|
||||
// ...
|
||||
backendUrl: process.env.MEDUSA_BACKEND_URL
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
Then, push the changes to the GitHub repository.
|
||||
|
||||
In Railway, add / modify the following environment variables for the Medusa application in server mode:
|
||||
|
||||
```bash
|
||||
ADMIN_CORS= # MEDUSA APPLICATION URL
|
||||
AUTH_CORS= # ADD MEDUSA APPLICATION URL
|
||||
MEDUSA_BACKEND_URL= # MEDUSA APPLICATION URL
|
||||
```
|
||||
|
||||
Where you set the value of `ADMIN_CORS` and `MEDUSA_BACKEND_URL` to the Medusa application’s URL you got from the previous step, and you add the URL to `AUTH_CORS`.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Remember to separate URLs in `AUTH_CORS` by commas.
|
||||
|
||||
</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
|
||||
## 7. Deploy the Medusa Application in Worker Mode
|
||||
|
||||
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.
|
||||
In this section, you’ll add the Medusa application in worker mode to the Railway project, configure, and deploy it.
|
||||
|
||||
To change the start command of your Medusa application:
|
||||
The process is similar to deploying the application in server mode, with slight changes in the configuration.
|
||||
|
||||
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:
|
||||
### Create Service
|
||||
|
||||
To create the service for the Medusa application in worker mode:
|
||||
|
||||
1. Click on the Create button.
|
||||
2. Choose GitHub Repo.
|
||||
3. Choose the repository of your Medusa application.
|
||||
|
||||
This adds a new service to your project.
|
||||
|
||||
### Add Environment Variables
|
||||
|
||||
To add environment variables to the Medusa application in worker mode:
|
||||
|
||||
1. Click on its card in the project dashboard.
|
||||
2. Choose the Variables tab.
|
||||
3. Click on RAW Editor, and paste the following in the editor:
|
||||
|
||||
```bash
|
||||
medusa migrations run && medusa start
|
||||
COOKIE_SECRET=supersecret # TODO GENERATE SECURE SECRET
|
||||
JWT_SECRET=supersecret # TODO GENERATE SECURE SECRET
|
||||
DISABLE_MEDUSA_ADMIN=false
|
||||
MEDUSA_WORKER_MODE=worker
|
||||
PORT=9000
|
||||
DATABASE_URL=${{Postgres.DATABASE_PUBLIC_URL}}
|
||||
POSTGRES_URL=${{Postgres.DATABASE_PUBLIC_URL}}
|
||||
REDIS_URL=${{Redis.REDIS_PUBLIC_URL}}
|
||||
```
|
||||
|
||||
### Add Domain Name
|
||||
Where:
|
||||
|
||||
The last step is to add a domain name to your Medusa application. To do that:
|
||||
- The value of `COOKIE_SECRET` and `JWT_SECRET` must be a randomly generated secret.
|
||||
- Keep `DISABLE_MEDUSA_ADMIN`'s value set to `true`, even if you’re hosting the admin with the Medusa application.
|
||||
|
||||
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.
|
||||
Feel free to add any other relevant environment variables. Once you’re done, click the Update Variables button.
|
||||
|
||||
### Set Start Command
|
||||
|
||||
To set the `start` command of your Medusa application in worker mode:
|
||||
|
||||
1. Click on its card in the project dashboard.
|
||||
2. Choose the Settings tab.
|
||||
3. Scroll down to the Deploy section.
|
||||
4. For the “Custom Start Command” field, enter the following and click the check mark button:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run start
|
||||
```
|
||||
|
||||
### Deploy Changes
|
||||
|
||||
To deploy the changes of the Medusa application in working mode, click on the Deploy button at the top center of the project. This takes a couple of minutes.
|
||||
|
||||
---
|
||||
|
||||
## Test the Deployed Application
|
||||
## 8. Test 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.
|
||||
To test out the deployed application, go to `<APP_URL>/health`, where `<APP_URL>` is the URL of the Medusa application in server mode. If the deployment was successful, you’ll see the `OK` response.
|
||||
|
||||
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.
|
||||
### Open Deployed Medusa Admin
|
||||
|
||||
### Health Route
|
||||
If you deployed the Medusa Admin with the application, it’ll be available at `<APP_URL>/app`.
|
||||
|
||||
Access `/health` to get health status of your deployed application.
|
||||
---
|
||||
|
||||
### Testing the Medusa Admin
|
||||
## Create Admin User
|
||||
|
||||
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.
|
||||
To create an admin user, install the [Railway CLI tool](https://docs.railway.app/guides/cli). Then, log in and link the Railway project to the local directory of the Medusa application.
|
||||
|
||||
<Note>
|
||||
|
||||
Make sure to link it to the Railway service of the Medusa application in server mode.
|
||||
|
||||
</Note>
|
||||
|
||||
Then, in your local directory of the Medusa application, run the following command:
|
||||
|
||||
```bash
|
||||
railway run npx medusa user -e admin-medusa@test.com -p supersecret
|
||||
```
|
||||
|
||||
Replace the email `admin-medusa@test.com` and password `supersecret` with the credentials you want.
|
||||
|
||||
You can use these credentials to log into the Medusa Admin dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into any issues or a problem with your deployed application, check the logs in your Railway container instance:
|
||||
To check issues or errors in your deployed Medusa application:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
1. Click on the card of the Medusa application in server mode.
|
||||
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
|
||||
```
|
||||
|
||||
@@ -6,9 +6,9 @@ export const metadata = {
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
<Note type="soon">
|
||||
<Note title="Important">
|
||||
|
||||
Deployment guides are coming soon for Medusa v2. The following guides are based on Medusa v1.
|
||||
As Medusa v2 is still in active development, it's highly recommended not to deploy it for production purposes.
|
||||
|
||||
</Note>
|
||||
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
sidebar_label: "General Guide"
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `General Deployment Guide for the Next.js Starter`,
|
||||
}
|
||||
|
||||
@@ -1,3 +1,7 @@
|
||||
---
|
||||
sidebar_label: "Vercel"
|
||||
---
|
||||
|
||||
export const metadata = {
|
||||
title: `Deploy Medusa Admin to Vercel`,
|
||||
}
|
||||
|
||||
@@ -655,22 +655,6 @@ export const filesMap = [
|
||||
"filePath": "/www/apps/resources/app/deployment/admin/vercel/page.mdx",
|
||||
"pathname": "/deployment/admin/vercel"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/deployment/medusa-application/digitalocean/page.mdx",
|
||||
"pathname": "/deployment/medusa-application/digitalocean"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/deployment/medusa-application/general/page.mdx",
|
||||
"pathname": "/deployment/medusa-application/general"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/deployment/medusa-application/heroku/page.mdx",
|
||||
"pathname": "/deployment/medusa-application/heroku"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/deployment/medusa-application/microtica/page.mdx",
|
||||
"pathname": "/deployment/medusa-application/microtica"
|
||||
},
|
||||
{
|
||||
"filePath": "/www/apps/resources/app/deployment/medusa-application/railway/page.mdx",
|
||||
"pathname": "/deployment/medusa-application/railway"
|
||||
|
||||
@@ -7935,6 +7935,7 @@ export const generatedSidebar = [
|
||||
"isPathHref": true,
|
||||
"title": "Medusa Application",
|
||||
"hasTitleStyling": true,
|
||||
"autogenerate_path": "/deployment/medusa-application",
|
||||
"children": [
|
||||
{
|
||||
"loaded": true,
|
||||
@@ -7942,34 +7943,6 @@ export const generatedSidebar = [
|
||||
"path": "/deployment/medusa-application/railway",
|
||||
"title": "Railway",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/medusa-application/heroku",
|
||||
"title": "Heroku",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/medusa-application/digitalocean",
|
||||
"title": "DigitalOcean",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/medusa-application/microtica",
|
||||
"title": "Microtica",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/medusa-application/general",
|
||||
"title": "General Guide",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
},
|
||||
@@ -7978,19 +7951,20 @@ export const generatedSidebar = [
|
||||
"isPathHref": true,
|
||||
"title": "Medusa Admin",
|
||||
"hasTitleStyling": true,
|
||||
"autogenerate_path": "/deployment/admin",
|
||||
"children": [
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/admin/vercel",
|
||||
"title": "Vercel",
|
||||
"path": "/deployment/admin/general",
|
||||
"title": "General Deployment Guide for the Medusa Admin",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/admin/general",
|
||||
"title": "General Guide",
|
||||
"path": "/deployment/admin/vercel",
|
||||
"title": "Vercel",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
@@ -8000,19 +7974,20 @@ export const generatedSidebar = [
|
||||
"isPathHref": true,
|
||||
"title": "Next.js Starter",
|
||||
"hasTitleStyling": true,
|
||||
"autogenerate_path": "/deployment/storefront",
|
||||
"children": [
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/storefront/vercel",
|
||||
"title": "Vercel",
|
||||
"path": "/deployment/storefront/general",
|
||||
"title": "General Deployment Guide for the Next.js Starter",
|
||||
"children": []
|
||||
},
|
||||
{
|
||||
"loaded": true,
|
||||
"isPathHref": true,
|
||||
"path": "/deployment/storefront/general",
|
||||
"title": "General Guide",
|
||||
"path": "/deployment/storefront/vercel",
|
||||
"title": "Vercel",
|
||||
"children": []
|
||||
}
|
||||
]
|
||||
|
||||
@@ -2007,56 +2007,17 @@ export const sidebar = sidebarAttachHrefCommonOptions([
|
||||
{
|
||||
title: "Medusa Application",
|
||||
hasTitleStyling: true,
|
||||
children: [
|
||||
{
|
||||
path: "/deployment/medusa-application/railway",
|
||||
title: "Railway",
|
||||
},
|
||||
{
|
||||
path: "/deployment/medusa-application/heroku",
|
||||
title: "Heroku",
|
||||
},
|
||||
{
|
||||
path: "/deployment/medusa-application/digitalocean",
|
||||
title: "DigitalOcean",
|
||||
},
|
||||
{
|
||||
path: "/deployment/medusa-application/microtica",
|
||||
title: "Microtica",
|
||||
},
|
||||
{
|
||||
path: "/deployment/medusa-application/general",
|
||||
title: "General Guide",
|
||||
},
|
||||
],
|
||||
autogenerate_path: "/deployment/medusa-application",
|
||||
},
|
||||
{
|
||||
title: "Medusa Admin",
|
||||
hasTitleStyling: true,
|
||||
children: [
|
||||
{
|
||||
path: "/deployment/admin/vercel",
|
||||
title: "Vercel",
|
||||
},
|
||||
{
|
||||
path: "/deployment/admin/general",
|
||||
title: "General Guide",
|
||||
},
|
||||
],
|
||||
autogenerate_path: "/deployment/admin",
|
||||
},
|
||||
{
|
||||
title: "Next.js Starter",
|
||||
hasTitleStyling: true,
|
||||
children: [
|
||||
{
|
||||
path: "/deployment/storefront/vercel",
|
||||
title: "Vercel",
|
||||
},
|
||||
{
|
||||
path: "/deployment/storefront/general",
|
||||
title: "General Guide",
|
||||
},
|
||||
],
|
||||
autogenerate_path: "/deployment/storefront",
|
||||
},
|
||||
],
|
||||
},
|
||||
|
||||
Reference in New Issue
Block a user