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

@@ -1,10 +1,4 @@
---
title: Medusa Admin Quickstart
---
# Admin Quickstart
# Medusa Admin Quickstart
This document will guide you through setting up the Medusa admin in minutes, as well as some of its features.
@@ -18,6 +12,12 @@ If youre not very familiar with Medusas architecture, you can learn more a
:::
<!-- ## Instant Deployment to Netlify
Instead of manually following this guide to install then later deploy the Medusa Admin, you can deploy the Medusa Admin to Netlify with this button:
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/admin) -->
## Install the Admin
Start by cloning the [Admin GitHub repository](https://github.com/medusajs/admin) and changing to the cloned directory:

View File

@@ -0,0 +1,276 @@
# Deploy Medusa Admin on Netlify
In this document, youll learn how to deploy the Medusa Admin on [Netlify](https://www.netlify.com/).
<!-- Alternatively, you can use this button to deploy the Medusa Admin to Netlify directly:
[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/admin) -->
## Prerequisites
### Medusa Components
Before proceeding with this documentation, it is assumed you already have a Medusa Admin installed locally. If not, please go through the [quickstart guide](../../admin/quickstart.md) first.
Additionally, this documentation does not cover how to deploy the Medusa server. If you want to deploy the Medusa server, check out one of the [deployment documentation related to the Medusa server](../server/index.mdx).
### Needed Accounts
You need a Netlify account to deploy the Medusa Admin. If you dont have one, you can create one on [Netlifys website](https://app.netlify.com/signup?_ga=2.249228995.556918419.1656505909-2004101041.1655191129).
Additionally, you need a GitHub account where you will host the repository for the Medusa admin. You can create it on [GitHubs website](https://github.com/signup).
:::tip
If you want to use another Git Provider, its possible to follow along with this guide but youll have to perform the equivalent steps in your Git Provider.
:::
### Required Tools
Gits CLI tool is required while following along with this tutorial. You can follow [this documentation to learn how to install it for your operating system](../../tutorial/0-set-up-your-development-environment.mdx#git).
## Create GitHub Repository
Before you can deploy your Medusa Admin 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.
![Create Repository](https://i.imgur.com/0YlxBRi.png)
Youll then be redirected to a new page with a form. In the form, enter the Repository Name then scroll down and click Create repository.
![Repository Form](https://i.imgur.com/YPYXAF2.png)
### Push Code to GitHub Repository
The next step is to push the code to the GitHub repository you just created.
After creating the repository, youll be redirected to the repositorys page. On that page, you should see a URL that you can copy to connect your repository to a local directory.
![GitHub Repository URL](https://i.imgur.com/pHfSTuT.png)
Copy the link. Then, open your terminal in the directory that holds your Medusa Admin 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 origin master
```
After pushing the changes, you can find the files in your GitHub repository.
## Deploy to Netlify
This section covers how to deploy Netlify either through the Netlify website or using Netlifys CLI tool.
### Option 1: Using Netlifys Website
After logging in with Netlify, go to the [dashboard](https://app.netlify.com/). Then, at the top right of the “Sites” section, click on “Add new site”, then click on “Import an existing project” from the dropdown.
:::note
Alternatively, if you dont have any other websites, youll see a big button that says “Import an existing project”.
:::
![Create a new website](https://i.imgur.com/IUUOzoW.png)
Youll then be asked to connect to a Git provider.
![Connect Git Provider](https://i.imgur.com/T6lZPDi.png)
Choose GitHub. Youll then be redirected to GitHubs website to give Netlify permissions if you havent done that before.
After you authorize Netlify to use GitHub, youll be asked to pick the repository you want to deploy. Pick the repository you just created.
![Choose Repository](https://i.imgur.com/D0r6Q1e.png)
In the form that shows, keep all fields the same and click on the “Show advanced” button before the “Deploy site” button.
![Show advanced Button](https://i.imgur.com/nUdwRbq.png)
Under the “Advanced build settings” section click on the “New variable” button. This will show 2 inputs for the key and value of the environment variable.
For the first field enter the key `GATSBY_MEDUSA_BACKEND_URL` and for the value enter the URL of your Medusa server.
:::caution
If you havent deployed your Medusa server yet, you can leave the value blank for now and add it later. However, you will not be able to log in to the Medusa Admin without deploying the Medusa server.
:::
![Environment Variable](https://i.imgur.com/DnutZfT.png)
Once youre done, scroll down and click on Deploy site.
Youll be then redirected to the dashboard of the new website. Netlify will build your website in the background. You should see “Site deploy in progress” on the top card.
![Site Deployment Progress](https://i.imgur.com/BCnLPw7.png)
The deployment can take a few minutes.
Once the deployment is done, youll find the URL in the place of the “Site deploy in progress” message you saw earlier.
![Deployment Complete](https://i.imgur.com/fNBxCG2.png)
If you click on it, youll be redirected to the deployed admin website.
![Medusa Admin Login](https://i.imgur.com/6t4ODe4.png)
:::note
Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa server. Follow along in the [Configure CORS on the Medusa Server](#configure-cors-variable-on-the-medusa-server) section.
:::
### Option 2: Using Netlifys CLI Tool
In this section, youll deploy the Medusa Admin using Netlifys CLI tool.
#### Install the Netlify CLI tool
If you dont have the tool installed, run the following command to install it:
```bash
npm install netlify-cli -g
```
#### Login to Netlify
Then, run the following command to log in to Netlify in your terminal:
```bash
netlify login
```
This opens a page to log in on your browser. Youll be asked to authorize the Netlify CLI tool.
![Authorize Application](https://i.imgur.com/JDUdqSE.png)
Click on Authorize. Then, you can go back to your terminal and see that youve successfully logged in.
![Authorized Message](https://i.imgur.com/L13Yqhp.png)
#### Initialize Netlify Website
In your terminal, run the following command:
```bash
netlify init
```
Youll have to follow 5 steps for the initialization:
##### **Step 1: Create Netlify Website**
Youll be asked to either connect to an existing Netlify website or create a new one. Choose the second option to create a new site:
```bash
? What would you like to do?
⇄ Connect this directory to an existing Netlify site
+ Create & configure a new site
```
##### Step 2: Choose Netlify Team
Choose the team you want to create the website in if you have multiple teams.
##### Step 3: Enter Site Name
Youll be asked to optionally enter a site name.
##### Step 4: Configure Webhooks and Deployment Keys
At this point, the website is created on Netlify. However, Netlify needs to configure Webhooks and deployment keys. Youll be asked to either authorize GitHub through Netlifys website or through a personal access token. Youre free to choose either:
```bash
? Netlify CLI needs access to your GitHub account to configure Webhooks and Depl
oy Keys. What would you like to do? (Use arrow keys)
Authorize with GitHub through app.netlify.com
Authorize with a GitHub personal access token
```
If you pick the first option, a page in your browser will open where you have to grant authorization to your Git provider.
If you pick the second option, youll need to create a personal access token on GitHub. You can follow [this guide in GitHubs documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) to learn how to do it.
##### Last Step: Steps with Default Values
For the rest of the steps, you can keep the default values provided by Netlify and press the “Enter” key on your keyboard for each.
#### Set Environment Variables
After the previous command has finished running, your Netlify website will be created. The next step is to add an environment variable that points to your Medusa server.
:::caution
If you havent deployed your Medusa server yet, you can leave the value blank for now and add it later. However, you will not be able to log in to the dashboard or use it without deploying the Medusa server.
:::
Run the following command to add the environment variable:
```bash
netlify env:set GATSBY_MEDUSA_BACKEND_URL "<YOUR_SERVER_URL>"
```
Where `<YOUR_SERVER_URL>` is the URL of your Medusa server.
#### Check deployment status
You can check the deployment status of your website by running the following command:
```bash
netlify watch
```
After the deployment has been completed, you should see a message saying “Deploy complete” with URLs to your website.
#### Open Medusa Admin Website
To open the Medusa Admin website, either use the URL shown to you or run the following command:
```bash
netlify open:site
```
The Medusa Admin will then open in your browser.
![Medusa Admin Login](https://i.imgur.com/6t4ODe4.png)
Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa server.
## Configure CORS Variable on the Medusa Server
To send requests to the Medusa server from the Medusa Admin, you must set the `ADMIN_CORS` environment variable on your server to the Medusa Admins URL.
:::caution
If you want to set a custom domain to your Medusa Admin website on Netlify, make sure to do it before this step. You can refer to this guide on [Netlifys documentation to learn how to add a custom domain](https://docs.netlify.com/domains-https/custom-domains/#assign-a-domain-to-a-site).
:::
On your Medusa server, add the following environment variable:
```bash
ADMIN_CORS=<ADMIN_URL>
```
Where `<ADMIN_URL>` is the URL of your Medusa Admin that you just deployed.
Then, restart your Medusa server. Once the server is running again, you can log in to the Medusa Admin and use it.
## Whats Next 🚀
- Learn how to [deploy your storefront](../storefront/index.mdx).
- Learn more about [how you can configure Medusa](../../usage/configurations.md).

View File

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

View File

@@ -4,7 +4,7 @@ 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.
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.
:::
@@ -175,5 +175,5 @@ You now have an application running on DigitalOcean. This can be scaled and conf
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](https://docs.medusajs.com/how-to/deploying-admin-on-netlify)
- [Deploy Admin on Netlify](../admin/deploying-on-netlify.md)
- Deploy Admin on Gatsby Cloud (Coming soon)

View File

@@ -1,4 +1,4 @@
import styles from './deployment.module.css';
import styles from '../deployment.module.css';
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
@@ -16,7 +16,7 @@ In this document, you'll learn how to deploy your Medusa server on Heroku. Herok
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).
To install a Medusa server, follow our [Quickstart guide](../../quickstart/quick-start.md).
## How to Deploy Your Medusa Server on Heroku
@@ -129,7 +129,7 @@ This uses the free plan of Upstash. Make sure to check out [more information reg
### 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.
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:
@@ -269,5 +269,5 @@ Where `<APP_NAME>` is the name of your Heroku app, and `<EMAIL>` and `<PASSWORD>
## What's Next :rocket:
- Learn how to [deploy your Medusa admin on Netlify](deploying-admin-on-netlify.md).
- Learn how to [deploy your Gatsby Storefront on Netlify](deploying-gatsby-on-netlify.md).
- Learn how to [deploy your Medusa admin](../admin/index.mdx).
- Learn how to [deploy your storefront](../storefront/index.mdx).

View File

@@ -4,7 +4,7 @@ This is a guide for deploying a Medusa project to Qovery. Qovery is a Continuous
:::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.
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.
:::
@@ -134,5 +134,5 @@ You now have an application running on Qovery. This can be scaled and configured
Furthermore, you can deploy Medusa Admin for your application, such that you can start managing your store from an interface.
- [Deploy Admin on Netlify](https://docs.medusajs.com/how-to/deploying-admin-on-netlify)
- [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}/>

View File

@@ -6,7 +6,7 @@ title: "Deploying your Gatsby storefront on Netlify"
This is a guide for deploying our [Gatsby storefront starter](https://github.com/medusajs/gatsby-starter-medusa) on Netlify. Netlify is a platform that offers hosting and backend services for applications and static websites. The steps in this guide will work for most Gatsby projects.
> At this point, you should have a local Gatsby storefront project running. If not, check out [our starter](https://github.com/medusajs/gatsby-starter-medusa) 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.
> At this point, you should have a local Gatsby storefront project running. If not, check out [our starter](https://github.com/medusajs/gatsby-starter-medusa) 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. Install the Netlify CLI

View File

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

View File

@@ -62,7 +62,7 @@ Alternatively, you can build your own storefront with any frontend framework of
- Customize your Medusa server by creating your own [endpoints](./advanced/backend/endpoints/add-storefront.md), [services](./advanced/backend/services/create-service.md), and [subscribers](./advanced/backend/subscribers/create-subscriber.md).
- Check out guides under the Integrations section to install plugins for [CMS](./add-plugins/strapi.md), [Payment](./add-plugins/stripe.md), [Search Engines](./add-plugins/algolia.md), and more.
- Deploy your Medusa server in seconds on [Heroku](./how-to/deploying-on-heroku.mdx), [Qovery](./how-to/deploying-on-qovery.md), or [Digital Ocean](./how-to/deploying-on-digital-ocean.md).
- Deploy your Medusa server in seconds on [Heroku](deployments/server/deploying-on-heroku.mdx), [Qovery](deployments/server/deploying-on-qovery.md), or [Digital Ocean](deployments/server/deploying-on-digital-ocean.md).
## Open Source Contribution

View File

@@ -1,77 +0,0 @@
---
title: "Deploying Admin on Netlify"
---
# Deploying Admin on Netlify
This is a guide for deploying Medusa Admin on Netlify. Netlify is a platform that offers hosting and backend services for applications and static websites.
:::note
At this point, you should have a running instance of Medusa Admin. If not, check out [these steps](https://github.com/medusajs/admin#-setting-up-admin) 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. Install the Netlify CLI
Install Netlify CLI on your machine using npm:
```bash npm2yarn
npm install netlify-cli -g
```
### 2. Login to your Netlify account
Connect to your Netlify account from your terminal:
```bash
netlify login
```
Follow the instructions in your terminal.
### 3. Netlify setup
In order to deploy on Netlify, you need to create a new site, link the admin repository to the site and configure environment variables.
The Netlify CLI is used to achieve this.
#### Create a new site
```bash
netlify init
```
Follow the instructions in your terminal to authorize and connect your Git repository.
The default build and deploy settings fit the needs of a Gatsby application, so leave these as is.
#### Add an environment variable
```bash
netlify env:set GATSBY_MEDUSA_BACKEND_URL "https://your-medusa-server.com"
```
The above environment variable should point to your Medusa server.
### 4. Push and deploy
Finally to deploy the admin, commit and push your changes to the repository connected in step 3.
```bash
git add .
git commit -m "Deploy Medusa Admin on Netlify"
git push origin main
```
Within a couple of minutes, your Medusa Admin is live and running on Netlify.
:::tip
If you experience CORS issues in your new setup, you might need to add your admin url as part of the ADMIN_CORS environment variable in your server setup.
:::
### What's next?
If you haven't deployed your Medusa server to use with your new admin, check out our guide [Deploying on Heroku](https://docs.medusajs.com/how-to/deploying-on-heroku).

View File

@@ -312,5 +312,5 @@ In this guide you created a new content model for Rich Text input in Contentful
In the next part of this guide you will learn how to implement further commerce functionalities to your site such as adding support for discount codes, region based shopping and more. (Coming soon)
- [Deploying Medusa on Heroku](https://docs.medusajs.com/how-to/deploying-on-heroku)
- [Deploying Medusa Admin on Netlify](https://docs.medusajs.com/how-to/deploying-admin-on-netlify)
- [Deploying Medusa Server](../deployments/server/index.mdx)
- [Deploying Medusa Admin](../deployments/admin/index.mdx)

View File

@@ -103,5 +103,5 @@ The Gatsby storefront comes with a lot of features out of the box including:
## Whats Next 🚀
- Check the [Storefront API reference](https://docs.medusajs.com/api/store/auth) for a full list of REST APIs to use on your storefront.
- Learn how to [deploy the Gatsby storefront on Netlify](../how-to/deploying-gatsby-on-netlify.md).
- Learn how to [deploy the Gatsby storefront on Netlify](../deployments/storefront/deploying-gatsby-on-netlify.md).
- Learn how to add [Stripe as a payment provider](../add-plugins/stripe.md#gatsby-storefront).

View File

@@ -337,4 +337,4 @@ It is recommended to use environment variables to store values of options instea
- Check out our [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) starter storefronts.
- Install the [Medusa admin](../admin/quickstart.md).
- Learn about [deploying the Medusa server on Heroku](../how-to/deploying-on-heroku.mdx).
- Learn about [deploying the Medusa server](../deployments/server/index.mdx).

View File

@@ -116,6 +116,6 @@ Inside the root project directory which was specified at the beginning of the in
## Whats Next 🚀
- Learn how to [deploy the Medusa server on Heroku](../how-to/deploying-on-heroku.mdx).
- Learn how to [deploy the Medusa admin on Netlify](../how-to/deploying-admin-on-netlify.md).
- Learn how to [deploy the Gatsby storefront on Netlify](../how-to/deploying-gatsby-on-netlify.md).
- Learn how to [deploy the Medusa server](../deployments/server/index.mdx).
- Learn how to [deploy the Medusa admin](../deployments/admin/index.mdx).
- Learn how to [deploy the storefront](../deployments/storefront/index.mdx).

View File

@@ -75,29 +75,59 @@ module.exports = {
label: "Deployment",
items: [
{
type: "doc",
id: "how-to/deploying-on-heroku",
label: "Deploy: Heroku",
type: "category",
label: "Server",
link: {
type: "doc",
id: "deployments/server/index"
},
items: [
{
type: "doc",
id: "deployments/server/deploying-on-heroku",
label: "Deploy on Heroku"
},
{
type: "doc",
id: "deployments/server/deploying-on-digital-ocean",
label: "Deploy on DigitalOcean"
},
{
type: "doc",
id: "deployments/server/deploying-on-qovery",
label: "Deploy on Qovery"
}
]
},
{
type: "doc",
id: "how-to/deploying-on-qovery",
label: "Deploy: Qovery",
type: "category",
label: "Admin",
link: {
type: "doc",
id: "deployments/admin/index"
},
items: [
{
type: "doc",
id: "deployments/admin/deploying-on-netlify",
label: "Deploy on Netlify"
},
]
},
{
type: "doc",
id: "how-to/deploying-on-digital-ocean",
label: "Deploy: DigitalOcean",
},
{
type: "doc",
id: "how-to/deploying-admin-on-netlify",
label: "Deploy: Admin on Netlify",
},
{
type: "doc",
id: "how-to/deploying-gatsby-on-netlify",
label: "Deploy: Gatsby on Netlify",
type: "category",
label: "Storefront",
link: {
type: "doc",
id: "deployments/storefront/index"
},
items: [
{
type: "doc",
id: "deployments/storefront/deploying-gatsby-on-netlify",
label: "Deploy Gatsby on Netlify"
},
]
},
],
},

View File

@@ -144,7 +144,7 @@ article {
}
@media screen and (min-width: 966px) {
article {
[class*=docItemContainer] > article {
margin-left: 50px;
margin-right: 50px;
max-width: none