chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser
@@ -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
|
||||
```
|
||||
Reference in New Issue
Block a user