docs: improve Deploy Admin to Netlify documentation (#1757)

* changes to deployment pages structure

* fix sidebar links

* added button to quickstart

* comment out button

* comment out button

* added note

* small fixes

* small fixes
This commit is contained in:
Shahed Nasser
2022-06-30 18:27:01 +03:00
committed by GitHub
parent de2390e5df
commit 109afa45c1
18 changed files with 375 additions and 122 deletions

View File

@@ -0,0 +1,179 @@
# Deploying on DigitalOcean App Platform
This is a guide for deploying a Medusa project on DigitalOcean App Platform.
:::note
It is assumed, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../../usage/create-medusa-app.mdx) for a small walkthrough.
:::
### 1. Configure Medusa
Before jumping into DigitalOcean, your Medusa application needs to be configured.
#### Update `medusa-config.js`
Instead of using a single environment variable for the database, `DATABASE_URL`, set `DB_*` variables and declare `DATABASE_URL` like so:
```javascript=
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}`;
```
Update `module.exports` to include the following:
```javascript=
module.exports = {
projectConfig: {
redis_url: REDIS_URL,
database_url: DATABASE_URL,
database_type: "postgres",
store_cors: STORE_CORS,
admin_cors: ADMIN_CORS,
database_extra: { ssl: { rejectUnauthorized: false } }
},
plugins,
};
```
#### Update `package.json`
Update `scripts` to have the following:
```json=
...
"scripts": {
"serve": "medusa start",
"start": "medusa migrations run && medusa develop",
"build": "babel src -d dist --extensions \".ts,.js\""
}
...
```
Add a newer version of node to `engines`:
```json=
...
"engines": {
"node": "14.x"
}
...
```
#### Push changes to your repository
```shell=
git add .
git commit -m "chore: DigitalOcean setup"
git push origin master
```
### 2. [DigitalOcean](https://cloud.digitalocean.com/login)
[Sign in](https://cloud.digitalocean.com/login) to your DigitalOcean Account or [create a new one](https://cloud.digitalocean.com/registrations/new).
### 3. Create an App
Navigate to the top-right dropdown **Create** and select **Apps**.
### 4. Connect you Git repository
Choose **GitHub** or **GitLab** and select the repository that holds your Medusa project. Check **Autodeploy code changes**, if you want DigitalOcean to deploy on every push to your repository.
:::tip
It's important, that DigitalOcean is pointing to the directory holding the Medusa store engine as it is only this which that will be deployed (If you followed the quickstart guide this will simply be the created project, and if you used the npx command this will be the backend folder inside of the newly created project).
:::
### 5. Configure environment variables
The default settings for your app should be sufficient. We only need to change environment variables to hold the following:
```shell=
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=your-jwt-secret
COOKIE_SECRET=your-cookie-secret
```
:::tip
Make sure to use actual secrets in a production environment
:::
### 6. Set up a Database
Click **Add a Database**. If you named your database instance something different than `db`, make sure your environment variable reflect this. See our use of `db` below.
```shell=
DB_USERNAME=${db.USERNAME}
```
### 7. Give your app a name
Enter a name for your app and select the most suitable region for your setup.
### 8. Finalize the setup
Choose a plan for your App. For just getting started, the Basic plan should be sufficient. For a production environment, the **Pro plan** is recommended.
Finally, launch the app.
### 9. Add a Redis Database
The following steps will add a Redis database to your Medusa setup.
1. Navigate to the top-right dropdown **Create** and select **Databases**
2. Select **Redis**
3. Select the same region you chose for your App
4. Leave VPC Network as it is
5. Choose a name for your Redis Database
Similarly to our other database, if you choose to name Redis something different than `redis`, you should udpdate the environment variable as well. See our use of `redis` below.
```shell=
REDIS_URL=${redis.DATABASE_URL}
```
6. Create the Redis database for your project
### 10. Configure Redis for your App
1. In the navbar on the left, click **Apps** and select your Medusa App
2. Select **Settings** ➜ **Add component** ➜ **Database**
3. Select **Previously Created DigitalOcean Database**
4. Select the Redis Cluster created in the previous step
### 11. Deploy Medusa
If you haven't already, make sure to rebuild and deploy your Medusa App.
### 12. Try it out!
In DigitalOcean, navigate to your App overview and access your endpoint to try out your new setup.
```
https://your-endpoint.ondigitalocean.app/health
```
### What's next?
You now have an application running on DigitalOcean. This can be scaled and configured to fit your business needs.
Furthermore, you can deploy a Medusa Admin for your application, such that you can start managing your store from an interface.
- [Deploy Admin on Netlify](../admin/deploying-on-netlify.md)
- Deploy Admin on Gatsby Cloud (Coming soon)

View File

@@ -0,0 +1,273 @@
import styles from '../deployment.module.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
# Deploy Your Medusa Server on Heroku
In this document, you'll learn how to deploy your Medusa server on Heroku. Heroku is a PaaS (Platform as a Service) that allows you to easily deploy your applications in the cloud.
<div>
<video width="100%" height="100%" playsinline autoplay muted controls>
<source src="https://user-images.githubusercontent.com/59018053/154798681-37060f13-5248-47c5-97c5-81c06da301d4.mp4" type="video/mp4" />
</video>
</div>
## Prerequisites
Before you start with this guide, you must have a Medusa server installed locally.
To install a Medusa server, follow our [Quickstart guide](../../quickstart/quick-start.md).
## How to Deploy Your Medusa Server on Heroku
### 1. Install the Heroku CLI
Install the Heroku CLI tool using the instructions that belong to your operating system.
<Tabs groupId="operating-systems" wrapperClassName={styles.osTabs}>
<TabItem value="windows" label="Windows" default>
Download the appropriate installer for your Windows installation:
[64-bit installer](https://cli-assets.heroku.com/heroku-x64.exe)
[32-bit installer](https://cli-assets.heroku.com/heroku-x86.exe)
</TabItem>
<TabItem value="linux" label="Linux">
For Ubuntu, you can use the following command:
```bash
sudo snap install --classic heroku
```
As for other Linux distributions, please check [Heroku's guide](https://devcenter.heroku.com/articles/heroku-cli#standalone-installation-with-a-tarball).
</TabItem>
<TabItem value="macos" label="macOS">
For macOS you can install Heroku's CLI tool using Homebrew:
```bash
brew tap heroku/brew && brew install heroku
```
For other installation options, please check [Heroku's guide](https://devcenter.heroku.com/articles/heroku-cli#standalone-installation-with-a-tarball)
</TabItem>
</Tabs>
### 2. 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.
### 3. Create an App with Heroku
In the root directory of your Medusa server, 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.
### 4. 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.
:::tip
In this section, the add-ons are used with a free plan. It's highly recommended that you don't use a free plan in a production environment.
:::
#### PostgreSQL
Add a Postgres add-on to your Heroku app with the following command:
:::note
This add-on is added with a free plan. However, Heroku might require you to add a payment method to proceed.
:::
```bash
heroku addons:create heroku-postgresql:hobby-dev
```
This uses the free plan of Heroku Postgres. Make sure to check out [more information regarding the plans and pricing of Heroku Postgres](https://elements.heroku.com/addons/heroku-postgresql#pricing).
#### Redis
:::note
The Add-on used here for Redis is [Upstash](https://devcenter.heroku.com/articles/upstash-redis) which is currently in beta. However, it provides a generous free plan. You can alternatively go for [Stackhero](https://elements.heroku.com/addons/stackhero-redis) but it does not have a free plan.
:::
Add a Redis instance to your Heroku app with the following command:
:::note
This add-on is added with a free plan. However, Heroku might require you to add a payment method to proceed.
:::
```bash
heroku addons:create upstash-redis
```
This uses the free plan of Upstash. Make sure to check out [more information regarding the plans and pricing of Upstash](https://elements.heroku.com/addons/upstash-redis#pricing).
### 5. 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 Server](../../usage/configurations.md) document.
Run the following commands in the root directory of your Medusa server 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
Upstash adds the Redis URL under the environment variable `UPSTASH_REDIS_URL`. However, Medusa looks for the `REDIS_URL` environment variable when initializing the connection with Redis.
So, retrieve the value of `UPSTASH_REDIS_URL` with the following command:
```bash
heroku config:get UPSTASH_REDIS_URL
```
This prints the value of the environment variable which is a Redis connection string.
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`. So, 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 CORS Variables
Optionally, if you've deployed the admin dashboard and you want to ensure it can use the server'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 server'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.
### 6. Configure Medusa Server
Before jumping into the deployment, you need to configure your Medusa server 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,
};
```
#### 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\""
},
```
### 7. Launch your Medusa Server
Finally, commit and push all changes to Heroku:
```bash
git add .
git commit -m "Deploy Medusa Server on Heroku"
git push heroku HEAD:master
```
This triggers a redeploy of the Medusa server with all the new configurations.
## 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 server:
```bash
heroku logs -n 500000 --remote heroku --tail
```
## Create a User
As an optional extra step, you can create a user to use when your admin dashboard is up and running:
```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.
## What's Next :rocket:
- Learn how to [deploy your Medusa admin](../admin/index.mdx).
- Learn how to [deploy your storefront](../storefront/index.mdx).

View File

@@ -0,0 +1,138 @@
# Deploying on Qovery
This is a guide for deploying a Medusa project to Qovery. Qovery is a Continuous Deployment Platform, that provides you with the developer experience of Heroku on top of your cloud provider (e.g. AWS, DigitalOcean).
:::note
We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusajs.com/quickstart/quick-start) or use `npx create-medusa-app` to set up your application in a matter of minutes. For the latter, see [this guide](../../usage/create-medusa-app.mdx) for a small walkthrough.
:::
### 1. Qovery Console
Create an account on [Qovery](https://www.qovery.com/) on their free community plan and jump into the console.
### 2. Setup
Create a project and an environment.
### 3. Add your Medusa app
Add a new app to your Qovery environment and connect the Git repository that holds your Medusa project. In your application settings, set the port to 9000 unless something else is specified in your setup.
:::note
If you used our `npx` starter, your repository will most likely hold all components; storefront, admin and backend. Ensure that **Root application path** in Qovery is pointing to your Medusa project (`/backend`).
:::
### 4. Add a database
Navigate to your environment overview and add the databases required by Medusa.
- Add Postgres database version 10, 11 or 12
- Add Redis database version 5 or 6
### 5. Configure Medusa
Our Medusa project needs a bit of configuration to fit the needs of Qovery.
#### Update `medusa-config.js`
First, add the Postgres and Redis database url to your `medusa-config.js`. In Qovery, click on your Medusa app in the environment overview. Navigate to environment variables in the sidebar on the left. Among the secret variables you should find your database urls. They should look something like this:
```bash
QOVERY_REDIS_123456789_DATABASE_URL
QOVERY_POSTGRESQL_123456789_DATABASE_URL
```
Add these to your `medusa-config.js`.
```js
const DATABASE_URL = process.env.QOVERY_POSTGRESQL_123456789_DATABASE_URL
const REDIS_URL= process.env.QOVERY_REDIS_123456789_DATABASE_URL
```
Furthermore, update `module.exports` to include the following:
```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: { }
},
plugins,
};
```
:::caution IMPORTANT
We are using the Qovery community plan, that does not allow SSL connections for the database, so this is disabled.
In a production environment, you would need the following in the config:
`database_extra: { ssl: { rejectUnauthorized: false } }`
:::
#### Add some extra variables
We need to add a couple of more environment variables in Qovery. Add the following variables in your Console with an application scope:
```bash
JTW_SECRET=something_secret_jwt
COOKIE_SECRET=something_secret_cookie
```
:::tip
Make sure to use actual secrets in a production environment.
:::
#### Update `package.json`
Update `scripts` to the following:
```json
"scripts": {
"serve": "medusa start",
"start": "medusa migrations run && medusa start",
"prepare": "npm run build",
"build": "babel src -d dist --extensions \".ts,.js\""
},
```
### 6. Deploy Medusa
Finally, deploy your Redis and Postgres followed by your Medusa application.
#### Deploy databases
In your environment overview in Qovery, deploy your databases one after the other. Only when these are deployed, proceed to next step.
#### Push changes to your repository
To initialise your first build Qovery, simply commit and push your changes.
```bash
git add .
git commit -m "chore: Qovery setup"
git push origin main
```
### 6. Try it out!
In Qovery, click on your Medusa app in the environment overview. In the top right you are able to open up your application. Navigate to `/health` to ensure, that the app is running.
### What's next?
You now have an application running on Qovery. This can be scaled and configured to fit your business needs. As mentioned, we used the community plan, so this should be upgraded when moving to production.
Furthermore, you can deploy Medusa Admin for your application, such that you can start managing your store from an interface.
- [Deploy Admin on Netlify](../admin/deploying-on-netlify.md)
- Deploy Admin on Gatsby Cloud (Coming soon)

View File

@@ -0,0 +1,8 @@
import DocCardList from '@theme/DocCardList';
import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
# Medusa Server Deployment Guides
Find in this page guides to deploy your Medusa server on different platforms.
<DocCardList items={useCurrentSidebarCategory().items}/>