api-ref: custom API reference (#4770)
* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
This commit is contained in:
Shahed Nasser authored and 
GitHub committed
1 parent
16249ec280
commit
914d773d3a
3270 files changed
+22075
-192064
No files matched your search
@@ -0,0 +1,278 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Your Medusa Backend to DigitalOcean Apps
|
||||
|
||||
In this document, you'll learn how to deploy your Medusa backend to a DigitalOcean App.
|
||||
|
||||
DigitalOcean is a reliable hosting provider that provides different ways to host websites and servers. One way to host a backend is using their DigitalOcean App Platform.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](../../development/backend/configurations.md) to learn how to do that.
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [DigitalOcean](https://cloud.digitalocean.com/registrations/new) account. You need to provide a payment method on sign up.
|
||||
- A [GitHub](https://github.com/) account to create a repository to host your Medusa backend’s codebase.
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to use another Git Provider supported by DigitalOcean, it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.
|
||||
|
||||
:::
|
||||
|
||||
### Required Tools
|
||||
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git).
|
||||
|
||||
---
|
||||
|
||||
## 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 everytime the Medusa backend is restarted.
|
||||
|
||||
---
|
||||
|
||||
## Changes to medusa-config.js
|
||||
|
||||
In `medusa-config.js`, the `DATABASE_URL` variable is set to the environment variable `DATABASE_URL`. This needs to be changed 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
|
||||
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, you must add to `projectConfig` in the exported object a new property `database_extra`:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
// ...
|
||||
database_extra: { ssl: { rejectUnauthorized: false } },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Create GitHub Repository
|
||||
|
||||
Before you can deploy your Medusa backend you need to create a GitHub repository and push the code base to it.
|
||||
|
||||
On GitHub, click the plus icon at the top right, then click New Repository.
|
||||
|
||||
You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.
|
||||
|
||||
### Push Code to GitHub Repository
|
||||
|
||||
The next step is to push the code to the GitHub repository you just created.
|
||||
|
||||
After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory.
|
||||
|
||||
Copy the link. Then, open your terminal in the directory that holds your Medusa backend codebase and run the following commands:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git remote add origin <GITHUB_URL>
|
||||
```
|
||||
|
||||
Where `<GITHUB_URL>` is the URL you just copied.
|
||||
|
||||
Then, add, commit, and push the changes into the repository:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "initial commit"
|
||||
git push
|
||||
```
|
||||
|
||||
After pushing the changes, you can find the files in your GitHub repository.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to DigitalOcean App
|
||||
|
||||
After logging into your account, click on the Create button at the top right, then choose App.
|
||||
|
||||
### Choose Repository
|
||||
|
||||
In the Create App page, choose GitHub from the Service Provider list.
|
||||
|
||||
If you haven’t given DigitalOcean access before, click on Manage Access under Source Code. You’ll then be redirected to GitHub to give DigitalOcean access.
|
||||
|
||||
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.
|
||||
|
||||
Additional inputs will show up to choose the Branch, Source Directory, and Autodeploy options.
|
||||
|
||||
If you host your Medusa backend in a monorepo, you should change the Source Directory to the directory the backend is available in the repository. Otherwise, it can be left as is.
|
||||
|
||||
Once you’re done, click Next to move on to the next step.
|
||||
|
||||
### Specify Web Service Resources
|
||||
|
||||
In the next step, you’ll see the resources to create.
|
||||
|
||||
If you have a Dockerfile available in the backend’s codebase, you’ll have two resources showing. You can remove it by clicking on the trash icon at the right of the resource.
|
||||
|
||||
By default, DigitalOcean hosts the web service in a sub-path of the domain name of the created App. To change it to the root of the domain, click on the edit icon at the right of the Web Service resource.
|
||||
|
||||
Then, scroll to HTTP Request Routes and expand it by clicking on Edit at its right. Change the value of the Routes input to `/`.
|
||||
|
||||
Once you’re done click Save. You’ll be taken back to the Resources page.
|
||||
|
||||
### Specify Database Resources
|
||||
|
||||
On the same page, expand the Add Resources section, choose Database, then click Add.
|
||||
|
||||
In the new page, you’ll be shown a PostgreSQL database to be created. Notice that 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.
|
||||
|
||||
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
|
||||
|
||||
In this section, you’ll add environment variables that are essential to your Medusa backend.
|
||||
|
||||
You should see two ways to add environment variables: Global or specific to the Web Service.
|
||||
|
||||
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
|
||||
NODE_ENV=production
|
||||
```
|
||||
|
||||
:::caution
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
:::
|
||||
|
||||
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. You’ll be creating this resource in a later section.
|
||||
|
||||
:::note
|
||||
|
||||
If you're using modules that require setting environment variables, make sure to set them here. You can also add them later. For example, if you're using the Redis Event Bus module, you can set the environment variable for it here or use the same `REDIS_URL` variable. Your module may also require setting up other resources than those explained in this guide so make sure to add them as well.
|
||||
|
||||
:::
|
||||
|
||||
Once you’re done click Save.
|
||||
|
||||
### 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 backend is being deployed, you can create the Redis resource.
|
||||
|
||||
Click the Create button at the top right and choose Database from the dropdown.
|
||||
|
||||
In the new page under Choose a database engine, choose Redis.
|
||||
|
||||
Then, scroll down to the “Choose a name” input. Since you used the name `redis` in the `REDIS_URL` environment variables, change the value to `redis` here.
|
||||
|
||||
Once you’re done, click on Create Database Cluster.
|
||||
|
||||
### Attach Redis Database
|
||||
|
||||
Once the Redis database is created go back to the App you created earlier by choose Apps in the sidebar then clicking on the App name.
|
||||
|
||||
Click at the white Create button at the top right and choose Create/Attach Database.
|
||||
|
||||
In the new page, click on the Previously Created DigitalOcean Database radio button. Then, under Database Cluster select the Redis database you just created.
|
||||
|
||||
Once you’re done click Attach Database. This will add the Redis database to the list of resources of your App and will trigger a redeploy of the App.
|
||||
|
||||
---
|
||||
|
||||
## Test your Backend
|
||||
|
||||
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`. If the deployment was successful, you should receive a JSON response.
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed backend.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
|
||||
|
||||
:::
|
||||
|
||||
If you deployed the admin dashboard alongside the backend, you can test it by going to `<YOUR_APP_URL>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on Your Backend
|
||||
|
||||
To run commands on your backend, you can access the console on the App’s page by choosing the Console tab. This opens a console in your browser where you can run commands on your backend.
|
||||
|
||||
For example, you can run the following commands to create a new admin user:
|
||||
|
||||
```bash
|
||||
npm install @medusajs/medusa-cli -g
|
||||
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.
|
||||
|
||||
To add environment variables, on the App’s page click on Settings and choose the Web Service component.
|
||||
|
||||
Then, scroll down and find Environment Variables. You can expand the environment variables by clicking Edit on the right. Here, you can edit, add, and remove environment variables.
|
||||
|
||||
Once you click Save, the environment variables will be saved and a redeployment will be triggered.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy the Medusa Admin](../admin/index.mdx).
|
||||
- [Deploy the Storefront](../storefront/index.mdx).
|
||||
@@ -0,0 +1,334 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Your Medusa Backend on Heroku
|
||||
|
||||
In this document, you'll learn how to deploy your Medusa backend on Heroku. Heroku 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 backend to Heroku directly:
|
||||
|
||||
<a href="https://heroku.com/deploy?template=https://github.com/medusajs/medusa-starter-default/tree/feat/deploy-heroku" className="img-url">
|
||||
<img src="https://www.herokucdn.com/deploy/button.svg" alt="Deploy to Heroku" className="no-zoom-img" />
|
||||
</a>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](../../development/backend/configurations.md) to learn how to do that.
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [Heroku](https://heroku.com/) account.
|
||||
|
||||
### Required Tools
|
||||
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git).
|
||||
- Heroku's CLI tool. You can follow [Heroku's documentation to learn how to install it for your operating system](https://devcenter.heroku.com/articles/heroku-cli).
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Heroku
|
||||
|
||||
### 1. Login to Heroku from your CLI
|
||||
|
||||
Before you can create an app with Heroku, you must login with the CLI tool:
|
||||
|
||||
```bash
|
||||
heroku login
|
||||
```
|
||||
|
||||
Depending on your operating system, you must follow either the instructions in your terminal or a page in your browser will open.
|
||||
|
||||
### 2. Create an App with Heroku
|
||||
|
||||
In the root directory of your Medusa backend, run the following commands to create an app on Heroku and add it as a remote origin:
|
||||
|
||||
```bash
|
||||
heroku create <APP_NAME>
|
||||
heroku git:remote -a <APP_NAME>
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of the app you'll create. You can use any name you want.
|
||||
|
||||
### 3. Install Postgresql and Redis on Heroku
|
||||
|
||||
Medusa requires a Postgres database and a Redis instance to work. You can add those to your Heroku app using Add-ons.
|
||||
|
||||
:::note
|
||||
|
||||
If you don't have a payment method set up in your Heroku account, you'll be asked to enter your payment details when you try to install these addons.
|
||||
|
||||
:::
|
||||
|
||||
#### PostgreSQL
|
||||
|
||||
Add a Postgres add-on to your Heroku app with the following command:
|
||||
|
||||
```bash
|
||||
heroku addons:create heroku-postgresql:mini
|
||||
```
|
||||
|
||||
This uses Heroku Postgres's smallest plan. You can check out [the available plans and pricing of Heroku Postgres on Heroku's website.](https://elements.heroku.com/addons/heroku-postgresql#pricing)
|
||||
|
||||
#### Redis
|
||||
|
||||
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. You can check out [the plans and pricing of Stackhero Redis on Heroku's website.](https://elements.heroku.com/addons/stackhero-redis#pricing)
|
||||
|
||||
### 4. Configure Environment Variables on Heroku
|
||||
|
||||
Medusa requires a set of environment variables to be configured. You can learn more about Medusa's configurations in the [Configure your Medusa backend](../../development/backend/configurations.md) document.
|
||||
|
||||
Run the following commands in the root directory of your Medusa backend to set some 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
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Make sure to replace `your-super-secret` and `your-super-secret-pt2` with actual secrets in a production environment.
|
||||
|
||||
:::
|
||||
|
||||
#### Set Buildpack
|
||||
|
||||
Additionally, you need to set the buildpack to Node.js using the following command:
|
||||
|
||||
```bash
|
||||
heroku buildpacks:set heroku/nodejs
|
||||
```
|
||||
|
||||
#### Configure the Redis URL
|
||||
|
||||
Stackhero Redis adds the Redis URL under the environment variable `STACKHERO_REDIS_URL_TLS`. However, Medusa looks for the `REDIS_URL` environment variable when initializing the connection with Redis.
|
||||
|
||||
Retrieve the value of `STACKHERO_REDIS_URL_TLS` with the following command:
|
||||
|
||||
```bash
|
||||
heroku config:get STACKHERO_REDIS_URL_TLS
|
||||
```
|
||||
|
||||
This prints the value of the environment variable which is a Redis connection string.
|
||||
|
||||
:::note
|
||||
|
||||
If you see nothing, you have to wait until the creation process of the stackhero redis instance is done. Try waiting a few minutes then trying again.
|
||||
|
||||
:::
|
||||
|
||||
Copy that value and use it to set the environment variable `REDIS_URL` with the following command:
|
||||
|
||||
```bash
|
||||
heroku config:set REDIS_URL=<YOUR_REDIS_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_REDIS_URL>` is the value you received from the previous command.
|
||||
|
||||
#### Configure the PostgreSQL Database URL
|
||||
|
||||
If you're using the Heroku PostgreSQL Add-on, it should configure the environment variable `DATABASE_URL`. In that case, you don't need to perform any additional actions.
|
||||
|
||||
However, if you use another add-on, make sure to set the environment variable `DATABASE_URL` to the PostgreSQL Database URL.
|
||||
|
||||
#### (Optional) Configure Modules Environment Variables
|
||||
|
||||
If you use in your Medusa backend modules that require setting environment variables, then you should set them at this point.
|
||||
|
||||
For example, if you use the Redis Event Bus module:
|
||||
|
||||
```bash
|
||||
heroku config:set EVENT_REDIS_URL=<YOUR_REDIS_URL>
|
||||
```
|
||||
|
||||
Make sure to change `EVENT_REDIS_URL` to the environment variable name you use for your module's configurations.
|
||||
|
||||
If your module requires setting up other services, do that then add the environment variables.
|
||||
|
||||
#### (Optional) Configure CORS Variables
|
||||
|
||||
Optionally, if you've deployed the admin dashboard and you want to ensure it can use the backend's REST APIs, you must set the following environment variable:
|
||||
|
||||
```bash
|
||||
heroku config:set ADMIN_CORS=<YOUR_ADMIN_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_ADMIN_URL>` is the URL of your admin dashboard.
|
||||
|
||||
Similarly, if you've deployed the storefront and you want to ensure it can use the backend's REST APIs, you must set the following environment variable:
|
||||
|
||||
```bash
|
||||
heroku config:set STORE_CORS=<YOUR_STOREFRONT_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_STOREFRONT_URL>` is the URL of your storefront.
|
||||
|
||||
### 5. Configure Medusa Backend
|
||||
|
||||
Before jumping into the deployment, you need to configure your Medusa backend to ensure it uses the previous environment variables and the recommended production configurations.
|
||||
|
||||
#### medusa-config.js
|
||||
|
||||
Update `module.exports` to include the following configurations:
|
||||
|
||||
```js
|
||||
module.exports = {
|
||||
projectConfig: {
|
||||
redis_url: REDIS_URL,
|
||||
database_url: DATABASE_URL,
|
||||
database_type: "postgres",
|
||||
store_cors: STORE_CORS,
|
||||
admin_cors: ADMIN_CORS,
|
||||
database_extra:
|
||||
process.env.NODE_ENV !== "development"
|
||||
? { ssl: { rejectUnauthorized: false } }
|
||||
: {},
|
||||
},
|
||||
plugins,
|
||||
modules,
|
||||
}
|
||||
```
|
||||
|
||||
#### package.json
|
||||
|
||||
Update `scripts` to include the following scripts:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
"serve": "medusa start",
|
||||
"start": "medusa develop",
|
||||
"heroku-postbuild": "medusa migrations run",
|
||||
"prepare": "npm run build",
|
||||
"build": "babel src -d dist --extensions \".ts,.js\""
|
||||
},
|
||||
```
|
||||
|
||||
### 6. Launch your Medusa Backend
|
||||
|
||||
Finally, commit and push all changes to Heroku:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Deploy Medusa Backend on Heroku"
|
||||
git push heroku HEAD:master
|
||||
```
|
||||
|
||||
This triggers a redeploy of the Medusa backend with all the new configurations.
|
||||
|
||||
## Test your Backend
|
||||
|
||||
To test your backend, run the following command to retrieve the backend's URL:
|
||||
|
||||
```bash
|
||||
heroku apps:info -a <APP_NAME>
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of the app. You should see as the output a bunch of info of the app.
|
||||
|
||||
The backend's URL is available under "Web URL". You can copy it and perform requests to it to test it out.
|
||||
|
||||
For example, you can send a request to `<YOUR_BACKEND_URL>/store/products` and you should receive a JSON response with the products in your store.
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed backend.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the `serve` command of your backend.
|
||||
|
||||
:::
|
||||
|
||||
If you deployed the admin dashboard alongside the backend, you can test it by going to `<YOUR_APP_URL>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
### Troubleshooting
|
||||
|
||||
#### Inspect Build Logs
|
||||
|
||||
If an error occurs during the deployment, you can explore your Heroku app build logs using the following command in the root directory of your Medusa backend:
|
||||
|
||||
```bash
|
||||
heroku logs -n 500000 --remote heroku --tail -a <APP_NAME>
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` 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
|
||||
```
|
||||
|
||||
You can resolve it by creating a file in the root of your Medusa backend directory named `Procfile` (without an extension) with the following content:
|
||||
|
||||
```
|
||||
web: npm run serve
|
||||
```
|
||||
|
||||
Then, push the changes with Git:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Added Procfile"
|
||||
git push heroku HEAD:master
|
||||
```
|
||||
|
||||
Once the application is re-published, you can access your store as expected.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on Your Backend
|
||||
|
||||
To run commands on your backend, you can use the following command:
|
||||
|
||||
```bash
|
||||
heroku run -a <APP_NAME> -- <COMMAND>
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of the app and `<COMMAND>` is the command you want to run.
|
||||
|
||||
For example, to create an admin user you can run the following command:
|
||||
|
||||
```bash
|
||||
heroku run -a <APP_NAME> -- medusa user -e "<EMAIL>" -p "<PASSWORD>"
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of your Heroku app, and `<EMAIL>` and `<PASSWORD>` are the credentials you want to use to log in to the Medusa admin dashboard.
|
||||
|
||||
---
|
||||
|
||||
## Add Environment Variables
|
||||
|
||||
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
|
||||
|
||||
To set or change an environment variable's value, you can use the following command:
|
||||
|
||||
```bash
|
||||
heroku config:set <ENV_NAME>=<ENV_VALUE> -a <APP_NAME>
|
||||
```
|
||||
|
||||
Where `<APP_NAME>` is the name of your Heroku app, `<ENV_NAME>` is the name of the environment variable, and `<ENV_VALUE>` is the value.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy your Medusa admin](../admin/index.mdx)
|
||||
- [Deploy your storefront](../storefront/index.mdx)
|
||||
@@ -0,0 +1,125 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Your Medusa Backend on Microtica
|
||||
|
||||
In this document, you'll learn how to deploy your Medusa backend on your AWS account with Microtica.
|
||||
|
||||
## Overview
|
||||
|
||||
[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 backend 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>
|
||||
|
||||
:::note
|
||||
|
||||
The Medusa infrastructure will be provisioned on your own AWS account.
|
||||
You retain full control over your infrastructure and data while getting all the benefits of infrastructure automation.
|
||||
|
||||
:::
|
||||
|
||||
### What will be provisioned on AWS
|
||||
|
||||
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)
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](../../development/backend/configurations.md) to learn how to do that.
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [Microtica](https://app.microtica.com/) account. Microtica provides a free plan that you can use.
|
||||
- An [AWS](https://aws.amazon.com/) account that you’ll connect to Microtica to provision the infrastructure.
|
||||
- A [GitHub](https://github.com/) account to create a repository to host your backend's codebase.
|
||||
|
||||
### Required Tools
|
||||
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git).
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Microtica
|
||||
|
||||
### Step 1: Create/Import a Git repository
|
||||
|
||||
Before you can deploy your Medusa backend you need to connect your preferred Git account. Microtica will create a repository on your Git account with a default repo name `medusa-server`.
|
||||
|
||||
If you already have a Medusa backend repository that you want to deploy then you need to perform a couple of changes in your source code. Follow [this tutorial to deploy and existing Medusa Backend app](https://docs.microtica.com/medusa-server?utm_source=medusa&utm_medium=docs&utm_campaign=medusa#xUBRz).
|
||||
|
||||
### Step 2: Configure the Template
|
||||
|
||||
The second step provides customization possibilities by configuring environment variables.
|
||||
|
||||
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 Backend environment or a development one. The production template will provision your managed Relational Database Service (RDS) PostgreSQL and Redis instances.
|
||||
|
||||
### Step 3: 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.
|
||||
|
||||
### Step 4: 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 backend.
|
||||
|
||||
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 Backend
|
||||
|
||||
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 backend's URL that you can use to access API endpoints and test them. You can try getting the list of products using the endpoint `<AccessUrl>/store/products`.
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed backend.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
|
||||
|
||||
:::
|
||||
|
||||
If you deployed the admin dashboard alongside the backend, you can test it by going to `<AccessUrl>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## 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 backend runtime [in Microtica documentation](https://docs.microtica.com/medusa-server?utm_source=medusa&utm_medium=docs&utm_campaign=medusa#z8li6).
|
||||
|
||||
---
|
||||
|
||||
## Updating your Deployed Backend
|
||||
|
||||
Any updates to the backend (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,541 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Your Medusa Backend on Qovery
|
||||
|
||||
:::warning
|
||||
|
||||
The deployment to Qovery rely on Docker. However, support and maintenance for Docker has been dropped in the [Medusa backend's default starter](https://github.com/medusajs/medusa-starter-default). So, the steps in this guide may not work as expected or can reference files that no longer exist in your step. It's kept for reference and to support previous deployments of Medusa to Qovery.
|
||||
|
||||
:::
|
||||
|
||||
In this document, you'll learn how to deploy your Medusa backend on Qovery with the help of Terraform.
|
||||
|
||||
[Qovery](https://www.qovery.com/) is a Continuous Deployment Platform that provides you with the developer experience of Heroku on top of your cloud provider (For example, AWS, DigitalOcean).
|
||||
|
||||
[Terraform](https://www.terraform.io/) is an open source infrastructure as code software (IaC) tool that allows you to easily deploy apps like Medusa and the resources it needs to Qovery using a single script.
|
||||
|
||||
:::note
|
||||
|
||||
This tutorial explains how to deploy Medusa to a Qovery organization with an AWS cluster. If you want to use a cloud provider other than AWS, you need to make changes to some of the keys and variables used in the tutorial.
|
||||
|
||||
:::
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](../../development/backend/configurations.md) to learn how to do that.
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [Qovery](https://start.qovery.com/) account with a created organization. Qovery provides a free plan that you can use.
|
||||
- An [AWS](https://aws.amazon.com/) account that you’ll connect to a Qovery cluster.
|
||||
- A [GitHub](https://github.com/) account to create a repository to host your backend's codebase.
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to use another [Git Provider supported by Qovery](https://hub.qovery.com/docs/useful-resources/faq/#what-git-providers-do-you-support), it’s possible to follow along with this guide but you’ll have to perform the equivalent steps in your Git Provider.
|
||||
|
||||
:::
|
||||
|
||||
### Required Tools
|
||||
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](../../development/backend/prepare-environment.mdx#git).
|
||||
- Terraform’s CLI tool. You can follow [this guide to install it based on your operating system](https://www.terraform.io/downloads).
|
||||
- Qovery’s CLI tool. You can follow [this guide to install it based on your operating system](https://hub.qovery.com/docs/using-qovery/interface/cli/#install).
|
||||
|
||||
---
|
||||
|
||||
## Create GitHub Repository
|
||||
|
||||
Before you can deploy your Medusa backend you need to create a GitHub repository and push the code base to it.
|
||||
|
||||
On GitHub, click the plus icon at the top right, then click New Repository.
|
||||
|
||||
You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.
|
||||
|
||||
### Push Code to GitHub Repository
|
||||
|
||||
The next step is to push the code to the GitHub repository you just created.
|
||||
|
||||
After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory.
|
||||
|
||||
Copy the link. Then, open your terminal in the directory that holds your Medusa backend codebase and run the following commands:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git remote add origin <GITHUB_URL>
|
||||
```
|
||||
|
||||
Where `<GITHUB_URL>` is the URL you just copied.
|
||||
|
||||
Then, add, commit, and push the changes into the repository:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "initial commit"
|
||||
git push
|
||||
```
|
||||
|
||||
After pushing the changes, you can find the files in your GitHub repository.
|
||||
|
||||
---
|
||||
|
||||
## Deploy to Qovery
|
||||
|
||||
In this section, you’ll learn how to deploy your Medusa backend to Qovery with the help of Terraform.
|
||||
|
||||
### Sign in Using Qovery CLI
|
||||
|
||||
If you haven’t logged in to your Qovery account using the Qovery CLI tool yet, run the following command:
|
||||
|
||||
```bash
|
||||
qovery auth
|
||||
```
|
||||
|
||||
This opens a new page in your browser to log in to Qovery.
|
||||
|
||||
### Retrieve Qovery Access Token
|
||||
|
||||
Terraform needs an access token from Qovery so that it can deploy to your Qovery organization.
|
||||
|
||||
Run the following command to retrieve a Qovery access token:
|
||||
|
||||
```bash
|
||||
qovery token
|
||||
```
|
||||
|
||||
You’ll be prompted to choose an organization and add a name and description for the token. Once the command finishes executing, you’ll be given an access token. Save it to use in the next steps.
|
||||
|
||||
### Add Terraform Variables
|
||||
|
||||
You need to add some variables to use for your Medusa deployment to Qovery.
|
||||
|
||||
In the root directory of your Medusa backend, create the file `variables.tf` with the following content:
|
||||
|
||||
```tf
|
||||
variable "qovery_organization_id" {
|
||||
type = string
|
||||
nullable = false
|
||||
description = "ID of Qovery organization"
|
||||
}
|
||||
|
||||
variable "qovery_create_cluster" {
|
||||
type = bool
|
||||
nullable = false
|
||||
default = true
|
||||
description = "Whether to create a new cluster or not"
|
||||
}
|
||||
|
||||
variable "qovery_cluster_id" {
|
||||
type = string
|
||||
nullable = true
|
||||
default = ""
|
||||
description = "The ID of the cluster you want to use if you don't want to create a new one. You can get the Cluster ID using this endpoint: https://api-doc.qovery.com/#tag/Clusters/operation/listOrganizationCluster"
|
||||
}
|
||||
|
||||
variable "qovery_access_token" {
|
||||
type = string
|
||||
sensitive = true
|
||||
nullable = false
|
||||
description = "Qovery's access token generated with the command 'qovery token'"
|
||||
}
|
||||
|
||||
variable "aws_access_key_id" {
|
||||
type = string
|
||||
sensitive = true
|
||||
nullable = true
|
||||
description = "Necessary only if creating a new cluster"
|
||||
}
|
||||
|
||||
variable "aws_secret_access_key" {
|
||||
type = string
|
||||
sensitive = true
|
||||
nullable = true
|
||||
description = "Necessary only if creating a new cluster"
|
||||
}
|
||||
|
||||
variable "aws_region" {
|
||||
type = string
|
||||
nullable = false
|
||||
default = "us-east-2"
|
||||
description = "Necessary only if creating a new cluster"
|
||||
}
|
||||
|
||||
variable "medusa_jwt_secret" {
|
||||
type = string
|
||||
default = "your-super-secret" # TO CHANGE FOR PRODUCTION
|
||||
sensitive = true
|
||||
nullable = false
|
||||
description = "The JWT Secret to use in Medusa"
|
||||
}
|
||||
|
||||
variable "medusa_cookie_secret" {
|
||||
type = string
|
||||
default = "your-super-secret-pt2" # TO CHANGE FOR PRODUCTION
|
||||
sensitive = true
|
||||
nullable = false
|
||||
description = "The Cookie Secret to use in Medusa"
|
||||
}
|
||||
|
||||
variable "git_url" {
|
||||
type = string
|
||||
nullable = false
|
||||
description = "The Git repo associated with the qovery app. Make sure it ends with '.git'."
|
||||
}
|
||||
|
||||
variable "git_branch" {
|
||||
type = string
|
||||
nullable = false
|
||||
default = "master"
|
||||
description = "The branch of the Git repo. Default is master"
|
||||
}
|
||||
|
||||
variable "git_root_path" {
|
||||
type = string
|
||||
nullable = false
|
||||
default = "/"
|
||||
description = "The base directory to run the app from. Default is /"
|
||||
}
|
||||
```
|
||||
|
||||
This defines the required variables and sets some of them as `secret` to ensure their values aren’t printed in the console during deployment.
|
||||
|
||||
Next, to set the values of these variables, create the file `terraform.tfvars` with the following content:
|
||||
|
||||
```bash
|
||||
qovery_organization_id = ""
|
||||
|
||||
# Optional
|
||||
qovery_create_cluster = true
|
||||
|
||||
# Optional
|
||||
qovery_cluster_id = null
|
||||
|
||||
qovery_access_token = ""
|
||||
|
||||
# Optional
|
||||
aws_access_key_id = null
|
||||
|
||||
# Optional
|
||||
aws_secret_access_key = null
|
||||
|
||||
# Optional
|
||||
aws_region = null
|
||||
|
||||
# Optional
|
||||
medusa_jwt_secret = "secret"
|
||||
|
||||
# Optional
|
||||
medusa_cookie_secret = "secret"
|
||||
|
||||
git_url = ""
|
||||
|
||||
# Optional
|
||||
git_branch = "master"
|
||||
|
||||
# Optional
|
||||
git_root_path = "/"
|
||||
```
|
||||
|
||||
Here’s an explanation of each of the variables and how to retrieve their variables:
|
||||
|
||||
- `qovery_organization_id`: The ID of the Qovery organization to deploy the backend to. It can be found by logging into your [Qovery Console](https://console.qovery.com/). You’ll be redirected to the organization’s main page with a URL of the format `https://console.qovery.com/platform/organization/<ORGANIZATION_ID>/projects`. Copy the `<ORGANIZATION_ID>` in the URL to use as the value of this field.
|
||||
- `qovery_create_cluster`: A boolean value indicating whether a new cluster should be created or not. If you already have a cluster that you want to use, you can set the value to `false` and set the value of `qovery_cluster_id`. Otherwise, set the value to `true` and set the values of `aws_access_key_id`, `aws_secret_access_key`, and `aws_region`.
|
||||
- `qovery_cluster_id`: The ID of the existing cluster to use (if `qovery_create_cluster` is set to `false`). You can use [Qovery’s REST API](https://api-doc.qovery.com/#tag/Clusters/operation/listOrganizationCluster) to retrieve the cluster ID. You can use the token you generated earlier for the Bearer authorization token as explained [here](https://hub.qovery.com/docs/using-qovery/interface/cli/#generate-api-token).
|
||||
- `aws_access_key_id`, `aws_secret_access_key`, and `aws_region`: The credentials used to create the cluster (if `qovery_create_cluster` is set to `true`). You can refer to [this guide](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys) to learn how to retrieve the `aws_access_key_id` and `aws_secret_access_key`.
|
||||
- `medusa_jwt_secret`: The value of the JSON Web Token (JWT) Secret on your Medusa backend. It’s recommended to use a strong randomly generated string.
|
||||
- `medusa_cookie_secret`: The value of the Cookie Secret on your Medusa backend. It’s recommended to use a strong randomly generated string.
|
||||
- `git_url`: The URL of the Git repository you created earlier. Make sure it ends with `.git`.
|
||||
- `git_branch`: The branch to use in the GitHub repo. By default it’s `master`.
|
||||
- `git_root_path`: The root path of the Medusa backend. By default, it’s `/`. If you are hosting your Medusa backend in a monorepo in a nested directory, you need to change the value of this variable.
|
||||
|
||||
:::note
|
||||
|
||||
If you're using modules that require setting up other variables, you can add them here.
|
||||
|
||||
:::
|
||||
|
||||
### Add Terraform Configuration File
|
||||
|
||||
In the root directory of your Medusa backend, create the file `main.tf` with the following content:
|
||||
|
||||
```bash
|
||||
# Install the Qovery Terraform provider
|
||||
terraform {
|
||||
required_providers {
|
||||
qovery = {
|
||||
source = "qovery/qovery"
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
# Set the access token
|
||||
provider "qovery" {
|
||||
token = var.qovery_access_token
|
||||
}
|
||||
|
||||
# Create the AWS credentials if qovery_create_cluster is true
|
||||
resource "qovery_aws_credentials" "my_aws_creds" {
|
||||
organization_id = var.qovery_organization_id
|
||||
name = "My AWS Creds"
|
||||
access_key_id = var.aws_access_key_id
|
||||
secret_access_key = var.aws_secret_access_key
|
||||
count = var.qovery_create_cluster ? 1 : 0
|
||||
}
|
||||
|
||||
# Create a new cluster if qovery_create_cluster is true
|
||||
resource "qovery_cluster" "my_cluster" {
|
||||
organization_id = var.qovery_organization_id
|
||||
credentials_id = qovery_aws_credentials.my_aws_creds[0].id
|
||||
name = "Demo Medusa cluster"
|
||||
description = "Terraform medusa cluster"
|
||||
cloud_provider = "AWS"
|
||||
region = var.aws_region
|
||||
instance_type = "T3A_MEDIUM"
|
||||
min_running_nodes = 3
|
||||
max_running_nodes = 4
|
||||
state = "RUNNING"
|
||||
count = var.qovery_create_cluster ? 1 : 0
|
||||
|
||||
depends_on = [
|
||||
qovery_aws_credentials.my_aws_creds
|
||||
]
|
||||
}
|
||||
|
||||
# Create a new project
|
||||
resource "qovery_project" "my_project" {
|
||||
organization_id = var.qovery_organization_id
|
||||
name = "Medusa"
|
||||
|
||||
depends_on = [
|
||||
qovery_cluster.my_cluster
|
||||
]
|
||||
}
|
||||
|
||||
# Create a new environment in the project
|
||||
resource "qovery_environment" "production" {
|
||||
project_id = qovery_project.my_project.id
|
||||
name = "production"
|
||||
mode = "PRODUCTION"
|
||||
cluster_id = !var.qovery_create_cluster && var.qovery_cluster_id != "" ? var.qovery_cluster_id : qovery_cluster.my_cluster[0].id
|
||||
|
||||
depends_on = [
|
||||
qovery_project.my_project
|
||||
]
|
||||
}
|
||||
|
||||
# Create a PostgreSQL database in the environment
|
||||
resource "qovery_database" "my_psql_database" {
|
||||
environment_id = qovery_environment.production.id
|
||||
name = "medusa psql db"
|
||||
type = "POSTGRESQL"
|
||||
version = "13"
|
||||
mode = "MANAGED" # Use AWS RDS for PostgreSQL (backup and PITR automatically configured by Qovery)
|
||||
storage = 10 # 10GB of storage
|
||||
accessibility = "PRIVATE" # do not make it publicly accessible
|
||||
state = "RUNNING"
|
||||
|
||||
depends_on = [
|
||||
qovery_environment.production,
|
||||
]
|
||||
}
|
||||
|
||||
# Create a Redis database in the environment
|
||||
resource "qovery_database" "my_redis_database" {
|
||||
environment_id = qovery_environment.production.id
|
||||
name = "medusa redis db"
|
||||
type = "REDIS"
|
||||
version = "6"
|
||||
mode = "CONTAINER"
|
||||
storage = 10 # 10GB of storage
|
||||
accessibility = "PRIVATE"
|
||||
state = "RUNNING"
|
||||
|
||||
depends_on = [
|
||||
qovery_environment.production,
|
||||
qovery_database.my_psql_database,
|
||||
]
|
||||
}
|
||||
|
||||
# Create the Medusa application with all the configuration needed
|
||||
resource "qovery_application" "medusa_app" {
|
||||
environment_id = qovery_environment.production.id
|
||||
name = "medusa app"
|
||||
cpu = 1000
|
||||
memory = 512
|
||||
state = "RUNNING"
|
||||
git_repository = {
|
||||
url = var.git_url
|
||||
branch = var.git_branch
|
||||
root_path = var.git_root_path
|
||||
}
|
||||
build_mode = "DOCKER"
|
||||
dockerfile_path = "Dockerfile"
|
||||
min_running_instances = 1
|
||||
max_running_instances = 1
|
||||
ports = [
|
||||
{
|
||||
internal_port = 9000
|
||||
external_port = 443
|
||||
protocol = "HTTP"
|
||||
publicly_accessible = true
|
||||
}
|
||||
]
|
||||
environment_variables = [
|
||||
{
|
||||
key = "PORT"
|
||||
value = "9000"
|
||||
},
|
||||
{
|
||||
key = "NODE_ENV"
|
||||
value = "production"
|
||||
},
|
||||
{
|
||||
key = "NPM_CONFIG_PRODUCTION"
|
||||
value = "false"
|
||||
}
|
||||
]
|
||||
secrets = [
|
||||
{
|
||||
key = "JWT_SECRET"
|
||||
value = var.medusa_jwt_secret
|
||||
},
|
||||
{
|
||||
key = "COOKIE_SECRET"
|
||||
value = var.medusa_cookie_secret
|
||||
},
|
||||
{
|
||||
key = "DATABASE_URL"
|
||||
value = "postgresql://${qovery_database.my_psql_database.login}:${qovery_database.my_psql_database.password}@${qovery_database.my_psql_database.internal_host}:${qovery_database.my_psql_database.port}/postgres"
|
||||
},
|
||||
{
|
||||
key = "REDIS_URL"
|
||||
value = "redis://${qovery_database.my_redis_database.login}:${qovery_database.my_redis_database.password}@${qovery_database.my_redis_database.internal_host}:${qovery_database.my_redis_database.port}"
|
||||
}
|
||||
]
|
||||
|
||||
depends_on = [
|
||||
qovery_environment.production,
|
||||
qovery_database.my_psql_database,
|
||||
qovery_database.my_redis_database,
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
If you're using modules that require setting up other resources, make sure to add them here.
|
||||
|
||||
:::
|
||||
|
||||
This is a Terraform configuration file that creates all the resources necessary to deploy Medusa to Qovery. If you set `qovery_create_cluster` to `true`, it will create new credentials and a cluster in your Qovery organization using the AWS credentials you set in the variables.
|
||||
|
||||
Next, it creates a new project, environment, PostgreSQL database, and a Redis database in your Qovery organization.
|
||||
|
||||
Finally, it creates the Medusa app and sets all the necessary environment variables needed to run it.
|
||||
|
||||
### Change develop.sh
|
||||
|
||||
The `Dockerfile` runs the file `develop.sh` to start the backend. Change the content of `develop.sh` to the following:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
|
||||
# Run migrations to ensure the database is updated
|
||||
medusa migrations run
|
||||
|
||||
# Run backend
|
||||
medusa start
|
||||
```
|
||||
|
||||
This makes sure the production backend is started and not a development backend.
|
||||
|
||||
### Initialize Terraform
|
||||
|
||||
In your terminal, run the following command to initialize Terraform:
|
||||
|
||||
```bash
|
||||
terraform init
|
||||
```
|
||||
|
||||
This will install the Qovery Terraform provider and have everything ready before the deployment.
|
||||
|
||||
### Deploy the Medusa App
|
||||
|
||||
Finally, run the following command to deploy your Medusa app:
|
||||
|
||||
```bash
|
||||
terraform apply
|
||||
```
|
||||
|
||||
You’ll be asked to confirm creating all the necessary resources in Qovery. Enter `yes` and the deployment will start.
|
||||
|
||||
The deployment can take up to thirty minutes to finish. You’ll be able to track its status both in your terminal and in the [Qovery Console](https://console.qovery.com/).
|
||||
|
||||
:::tip
|
||||
|
||||
If you run into any errors while running this command, you can just re-run it after fixing the errors and it will pick up from where it left off. For example, if an error occurred after the creation of the PostgreSQL database, terraform continues from the next task and does not recreate the PostgreSQL database.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Test the Backend
|
||||
|
||||
Once the command finishes and the deployment is successful, you can access your backend in the [Qovery Console](https://console.qovery.com/). Go to the project, environment, then the app that you created using Terraform and Qovery. In the app, click the Open button at the top right to open your website in a new tab.
|
||||
|
||||
|
||||
|
||||
You can access any of the endpoints on your backend using the backend URL. For example, you can get the list of products using the endpoint `/store/products`.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
|
||||
|
||||
:::
|
||||
|
||||
If you deployed the admin dashboard alongside the backend, you can test it by going to `<YOUR_APP_URL>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## Run Commands on the Backend
|
||||
|
||||
To run commands on the backend, run the following command:
|
||||
|
||||
```bash
|
||||
qovery shell
|
||||
```
|
||||
|
||||
You’ll be asked to either confirm the existing context or choose a new context.
|
||||
|
||||
After choosing your Medusa app in the context, you should be able to execute any command in the directory of your Medusa backend. For example, you can run the [`user` command using Medusa’s CLI tool to create a new user](../../cli/reference.mdx#user):
|
||||
|
||||
```bash
|
||||
npm install @medusajs/medusa-cli -g
|
||||
medusa user --email <EMAIL> --password <PASSWORD>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Add Environment Variables
|
||||
|
||||
You’ll likely need to add environment variables later such as Admin Cross-Origin Resource Sharing (CORS) and Store CORS variables.
|
||||
|
||||
To add environment variables, in your [Qovery Console](https://console.qovery.com/) go to the Medusa app and choose Environment Variables from the sidebar. You can add environment variables here at any point later on.
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy the Medusa Admin](../admin/index.mdx)
|
||||
- [Deploy the Storefront](../storefront/index.mdx)
|
||||
@@ -0,0 +1,265 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Your Medusa Backend to Railway
|
||||
|
||||
In this document, you’ll learn how to deploy your Medusa backend to Railway.
|
||||
|
||||
## What is Railway
|
||||
|
||||
[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.
|
||||
|
||||
Railway provides a free plan that allows you to deploy your Medusa backend along with PostgreSQL and Redis databases. This is useful mainly for development and demo purposes.
|
||||
|
||||
:::note
|
||||
|
||||
If you're deploying the admin plugin along with the backend, you'll need at least the Developer plan. The resources provided by the starter plan will cause memory errors.
|
||||
|
||||
:::
|
||||
|
||||
If you also don't have a Medusa project, you can deploy to Railway instantly with this button:
|
||||
|
||||
<a
|
||||
href="https://railway.app/template/zC7eOq?referralCode=TW4Qi0" class="img-url no-zoom-img">
|
||||
<img src="https://railway.app/button.svg" alt="Deploy with Railway" class="no-zoom-img"/>
|
||||
</a>
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Backend
|
||||
|
||||
It is assumed that you already have a Medusa backend installed locally. If you don’t, please follow the [quickstart guide](../../development/backend/install.mdx).
|
||||
|
||||
Furthermore, your Medusa backend should be configured to work with PostgreSQL and Redis. You can follow the [Configure your Backend documentation](./../../development/backend/configurations.md) to learn how to do that.
|
||||
|
||||
### Production Modules
|
||||
|
||||
If you're using development modules for events and caching, it's highly recommended to install production modules instead. These can be:
|
||||
|
||||
- [Redis Event Module](../../development/events/modules/redis.md)
|
||||
- [Redis Cache Module](../../development/cache/modules/redis.md)
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [Railway](https://railway.app/) account.
|
||||
- A [GitHub](https://github.com/) account to create a repository to host your backend's codebase.
|
||||
|
||||
### Required Tools
|
||||
|
||||
- Git’s CLI tool. You can follow [this documentation to learn how to install it for your operating system](./../../development/backend/prepare-environment.mdx#git).
|
||||
|
||||
---
|
||||
|
||||
## (Optional) Step 1: Add Nixpacks Configurations
|
||||
|
||||
If you've created your project using `create-medusa-app`, you might receive errors during the deployment process as Railway uses NPM by default. To avoid that, you need to configure Nixpacks to either use `yarn` or add the `--legacy-peer-deps` option to `npm install`.
|
||||
|
||||
In the root of your Medusa project, add the `nixpacks.toml` file with the following content:
|
||||
|
||||
```toml
|
||||
[phases.setup]
|
||||
nixPkgs = ['nodejs', 'yarn']
|
||||
|
||||
[phases.install]
|
||||
cmds=['yarn install']
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Create GitHub Repository
|
||||
|
||||
Before you can deploy your Medusa backend you need to create a GitHub repository and push the code base to it.
|
||||
|
||||
On GitHub, click the plus icon at the top right, then click New Repository.
|
||||
|
||||
You’ll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.
|
||||
|
||||
### Push Code to GitHub Repository
|
||||
|
||||
The next step is to push the code to the GitHub repository you just created.
|
||||
|
||||
After creating the repository, you’ll be redirected to the repository’s page. On that page, you should see a URL that you can copy to connect your repository to a local directory.
|
||||
|
||||
Copy the link. Then, open your terminal in the directory that holds your Medusa backend codebase and run the following commands:
|
||||
|
||||
```bash
|
||||
git init
|
||||
git remote add origin <GITHUB_URL>
|
||||
```
|
||||
|
||||
Where `<GITHUB_URL>` is the URL you just copied.
|
||||
|
||||
Then, add, commit, and push the changes into the repository:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "initial commit"
|
||||
git push
|
||||
```
|
||||
|
||||
After pushing the changes, you can find the files in your GitHub repository.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Deploy to Railway
|
||||
|
||||
In this section, you’ll create the PostgreSQL and Redis databases first, then deploy the backend 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 will be created and, after a few seconds, you will be redirected to the project page where you will see the newly-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 will be added to the project view in a few seconds. Click on it to open the database sidebar.
|
||||
|
||||
|
||||
### Note about Modules
|
||||
|
||||
If you use modules that require setting up other resources, make sure to add them at this point. This guide does not cover configurations specific to a module.
|
||||
|
||||
### Deploy the Medusa Backend 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.
|
||||
|
||||
:::tip
|
||||
|
||||
If the GitHub repositories in the dropdown are stuck on loading and aren't showing, you might need to delete the project and start over. This only happens before you configure your account with GitHub.
|
||||
|
||||
:::
|
||||
|
||||
It will take the backend 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 backend:
|
||||
|
||||
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}}
|
||||
DATABASE_TYPE=postgres
|
||||
```
|
||||
|
||||
Notice that the values of `DATABASE_URL` and `REDIS_URL` reference the values from the PostgreSQL and Redis databases you created.
|
||||
|
||||
:::warning
|
||||
|
||||
It’s highly recommended to use strong, randomly generated secrets for `JWT_SECRET` and `COOKIE_SECRET`.
|
||||
|
||||
:::
|
||||
|
||||
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 backend. You’ll change it to run any available migrations, then run the Medusa backend. This way if you create your own migrations or update the Medusa backend, it's guaranteed that these migrations are run first before the backend starts.
|
||||
|
||||
To change the start command of your Medusa backend:
|
||||
|
||||
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 Start Command field:
|
||||
|
||||
```bash
|
||||
medusa migrations run && medusa start
|
||||
```
|
||||
|
||||
### Add Domain Name
|
||||
|
||||
The last step is to add a domain name to your Medusa backend. To do that:
|
||||
|
||||
1. Click on the GitHub repository’s card.
|
||||
2. Click on the Settings tab and scroll down to the Environment section.
|
||||
3. Either click on the Custom Domain button to enter your own domain or the Generate Domain button to generate a random domain.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Test the Backend
|
||||
|
||||
Every change you make to the settings redeploys the backend. You can check the Deployments of the backend by clicking on the GitHub repository’s card and choosing the Deployments tab.
|
||||
|
||||
After the backend 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 will return the products available on your backend.
|
||||
|
||||
:::tip
|
||||
|
||||
If you generated a random domain, you can find it by clicking on the GitHub repository’s card → Deployment tab.
|
||||
|
||||
:::
|
||||
|
||||
### Health Route
|
||||
|
||||
You can access `/health` to get health status of your deployed backend.
|
||||
|
||||
### Testing the Admin
|
||||
|
||||
:::note
|
||||
|
||||
Make sure to either set the `autoRebuild` option of the admin plugin to `true` or add its [build](../../admin/quickstart.mdx#build-command-options) command as part of the start command of your backend.
|
||||
|
||||
:::
|
||||
|
||||
If you deployed the admin dashboard alongside the backend, you can test it by going to `<YOUR_APP_URL>/app`. If you changed the admin path, make sure to change `/app` to the path you've set.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you run into any issues or a problem with your deployed backend, you can check the logs in your Railway container instance by:
|
||||
|
||||
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 Backend
|
||||
|
||||
To run commands on your backend, 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 backend to seed the database or create a new user using [Medusa’s CLI tool](../../cli/reference.mdx).
|
||||
|
||||
### Create Admin User
|
||||
|
||||
You can create an admin user by running the following command in the root of your Medusa project:
|
||||
|
||||
```bash
|
||||
railway run npx medusa user --email admin@medusa-test.com --password supersecret
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy the Medusa Admin](../admin/index.mdx)
|
||||
- [Deploy the Storefront](../storefront/index.mdx)
|
||||
@@ -0,0 +1,13 @@
|
||||
---
|
||||
hide_table_of_contents: true
|
||||
description: 'Learn how to deploy your Medusa backend to different hosting providers including DigitalOcean, Heroku, Railway, and more.'
|
||||
---
|
||||
|
||||
import DocCardList from '@theme/DocCardList';
|
||||
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
|
||||
|
||||
# Medusa Backend Deployment Guides
|
||||
|
||||
Find in this page guides to deploy your Medusa backend on different platforms.
|
||||
|
||||
<DocCardList items={useCurrentSidebarCategory().items}/>
|
||||
Reference in new issue
Block a user