docs: add documentation for v1.8 (#3669)
This commit is contained in:
Shahed Nasser
@@ -1,319 +0,0 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Medusa Admin on Netlify
|
||||
|
||||
In this document, you’ll 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:
|
||||
|
||||
<a href="https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/admin" class="img-url">
|
||||
<img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify" class="no-zoom-img" />
|
||||
</a>
|
||||
|
||||
## 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.mdx) first.
|
||||
|
||||
Additionally, this documentation does not cover how to deploy the Medusa backend. If you want to deploy the Medusa backend, check out one of the [deployment documentation related to the Medusa backend](../server/index.mdx).
|
||||
|
||||
### Needed Accounts
|
||||
|
||||
- A [Netlify](https://app.netlify.com/signup) account to deploy the Medusa Admin.
|
||||
- A [GitHub](https://github.com/signup) account where you will host the repository for the Medusa admin.
|
||||
|
||||
:::tip
|
||||
|
||||
If you want to use another Git Provider, 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).
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
|
||||
|
||||
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 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 Netlify’s CLI tool.
|
||||
|
||||
### Option 1: Using Netlify’s 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 don’t have any other websites, you’ll see a big button that says “Import an existing project”.
|
||||
|
||||
:::
|
||||
|
||||
|
||||
|
||||
You’ll then be asked to connect to a Git provider.
|
||||
|
||||
|
||||
|
||||
Choose GitHub. You’ll then be redirected to GitHub’s website to give Netlify permissions if you haven’t done that before.
|
||||
|
||||
After you authorize Netlify to use GitHub, you’ll be asked to pick the repository you want to deploy. Pick the repository you just created.
|
||||
|
||||
|
||||
|
||||
In the "Basic build settings" section, make sure the fields have the following values:
|
||||
|
||||
- Base directory: (leave empty)
|
||||
- Build command: yarn build
|
||||
- Publish directory: public
|
||||
|
||||
|
||||
Next, click the “Show advanced” button, which is above the “Deploy site” button.
|
||||
|
||||
|
||||
|
||||
Under the “Advanced build settings” section click on the “New variable” button. This will show two inputs for the key and value of the environment variable.
|
||||
|
||||
For the first field enter the key `MEDUSA_BACKEND_URL` and for the value enter the URL of your Medusa backend.
|
||||
|
||||
:::caution
|
||||
|
||||
If you haven’t deployed your Medusa backend 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 backend.
|
||||
|
||||
:::
|
||||
|
||||
:::note
|
||||
|
||||
In previous versions of the admin, the environment variable name was `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` instead. The admin remains backwards compatible, so if you've used this an older version you can keep the same environment variables. However, it's highly recommended you change it to `MEDUSA_BACKEND_URL`.
|
||||
|
||||
:::
|
||||
|
||||
Once you’re done, scroll down and click on Deploy site.
|
||||
|
||||
You’ll 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.
|
||||
|
||||
|
||||
|
||||
The deployment can take a few minutes.
|
||||
|
||||
Once the deployment is done, you’ll find the URL in the place of the “Site deploy in progress” message you saw earlier.
|
||||
|
||||
|
||||
|
||||
If you click on it, you’ll be redirected to the deployed admin website.
|
||||
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa backend. Follow along in the [Configure Cross-Origin Resource Sharing (CORS) on the Medusa Backend](#configure-cors-variable-on-the-medusa-backend) section.
|
||||
|
||||
:::
|
||||
|
||||
### Option 2: Using Netlify’s CLI Tool
|
||||
|
||||
In this section, you’ll deploy the Medusa Admin using Netlify’s CLI tool.
|
||||
|
||||
#### Install the Netlify CLI tool
|
||||
|
||||
If you don’t 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. You’ll be asked to authorize the Netlify CLI tool.
|
||||
|
||||
|
||||
|
||||
Click on Authorize. Then, you can go back to your terminal and see that you’ve successfully logged in.
|
||||
|
||||
|
||||
|
||||
#### Initialize Netlify Website
|
||||
|
||||
In your terminal, run the following command:
|
||||
|
||||
```bash
|
||||
netlify init
|
||||
```
|
||||
|
||||
You’ll have to follow five steps for the initialization:
|
||||
|
||||
##### **Step 1: Create Netlify Website**
|
||||
|
||||
You’ll 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 noReport
|
||||
? 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
|
||||
|
||||
You’ll 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. You’ll be asked to either authorize GitHub through Netlify’s website or through a personal access token. You’re free to choose either:
|
||||
|
||||
```bash noReport
|
||||
? 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, you’ll need to create a personal access token on GitHub. You can follow [this guide in GitHub’s 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 most of the default values provided by Netlify, except for the following options:
|
||||
|
||||
1. Set build command to `yarn run build`
|
||||
|
||||
```
|
||||
? Your build command (hugo build/yarn run build/etc): yarn run build
|
||||
```
|
||||
|
||||
2. Set deploy directory to `public`
|
||||
|
||||
```
|
||||
? Directory to deploy (blank for current dir): public
|
||||
```
|
||||
|
||||
#### 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 backend.
|
||||
|
||||
:::caution
|
||||
|
||||
If you haven’t deployed your Medusa backend 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 backend.
|
||||
|
||||
:::
|
||||
|
||||
Run the following command to add the environment variable:
|
||||
|
||||
```bash
|
||||
netlify env:set MEDUSA_BACKEND_URL "<YOUR_BACKEND_URL>"
|
||||
```
|
||||
|
||||
Where `<YOUR_BACKEND_URL>` is the URL of your Medusa backend.
|
||||
|
||||
:::note
|
||||
|
||||
In previous versions of the admin, the environment variable name was `GATSBY_MEDUSA_BACKEND_URL` or `GATSBY_STORE_URL` instead. The admin remains backwards compatible, so if you've used this an older version you can keep the same environment variables. However, it's highly recommended you change it to `MEDUSA_BACKEND_URL`.
|
||||
|
||||
:::
|
||||
|
||||
#### 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.
|
||||
|
||||
|
||||
|
||||
Before you can use Medusa Admin, you must add the URL as an environment variable on your deployed Medusa backend.
|
||||
|
||||
---
|
||||
|
||||
## Configure CORS Variable on the Medusa Backend
|
||||
|
||||
To send requests to the Medusa backend from the Medusa Admin, you must set the `ADMIN_CORS` environment variable on your backend to the Medusa Admin’s 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 [Netlify’s 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 backend, 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 backend. Once the backend is running again, you can log in to the Medusa Admin and use it.
|
||||
|
||||
---
|
||||
|
||||
## See Also
|
||||
|
||||
- [Deploy storefront](../storefront/index.mdx)
|
||||
- [Configure Medusa backend](../../development/backend/configurations.md)
|
||||
@@ -0,0 +1,197 @@
|
||||
---
|
||||
description: 'Learn step-by-step.'
|
||||
addHowToData: true
|
||||
---
|
||||
|
||||
# Deploy Admin to Vercel
|
||||
|
||||
In this document, you’ll learn how to deploy the admin dashboard to Vercel.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Medusa Components
|
||||
|
||||
You must have a [Medusa backend](../../development/backend/install.mdx) installed along with an [admin dashboard plugin](../../admin/quickstart.mdx).
|
||||
|
||||
### Required Accounts
|
||||
|
||||
- [Vercel Account](https://vercel.com/)
|
||||
- [GitHub Account](https://github.com/): Only required if you’re deploying through the Vercel website.
|
||||
|
||||
:::note
|
||||
|
||||
If you want to use another Git Provider, 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 CLI](../../development/backend/prepare-environment.mdx#git): Only required if you’re deploying through the Vercel website.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Create GitHub Repository
|
||||
|
||||
:::note
|
||||
|
||||
This step is only required if you’re deploying from the Vercel website. However, it’s highly recommended to connect your Vercel project to a Git repository for a better developer experience.
|
||||
|
||||
:::
|
||||
|
||||
Before you can deploy your admin dashboard, you need to create a GitHub repository and push the code base to it. To do that:
|
||||
|
||||
1. On GitHub, click the plus icon at the top right, then click New Repository.
|
||||
2. You’ll then be redirected to a new page with a form. In the form, enter the Repository Name.
|
||||
3. 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 2: Configure Build Script
|
||||
|
||||
In the `package.json` of the Medusa backend, add or change a build script for the admin:
|
||||
|
||||
```json
|
||||
"scripts": {
|
||||
// other scripts
|
||||
"build:admin": "medusa-admin build --deployment",
|
||||
}
|
||||
```
|
||||
|
||||
### Additional Build Options
|
||||
|
||||
Aside from `--deployment`, you can use the following options when building your admin for deployment:
|
||||
|
||||
- `--backend` or `-b`: a string specifying the URL of the Medusa backend. The default here is the value of the environment variable `MEDUSA_BACKEND_URL`. If this options is added, the value you set for `MEDUSA_BACKEND_URL` in Vercel will no longer have an effect. For example, `medusa-admin build --deployment --backend example.com`
|
||||
- `--out-dir` or `-o`: a string specifying a custom path to output the build files to. By default, it will be the `build` directory. For example, `medusa-admin --deployment --out-dir public`.
|
||||
- `--include` or `-i`: a list of strings of paths to files you want to include in the build output. It can be useful if you want to inject files that are relevant to your hosting. For example, `medusa-admin --deployment --include 200.html`
|
||||
- `--include-dist` or `-d`: a string specifying the path to copy the files specified in `--include` to. By default, the files are coopied to the root of the build directory. You can use this option to change that. For example, `medusa-admin --deployment --include 200.html --include-dist static`.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Add Vercel Configurations
|
||||
|
||||
In the root directory of the Medusa backend, create a new file `vercel.json` with the following content:
|
||||
|
||||
```json
|
||||
{
|
||||
"rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Push Changes to GitHub
|
||||
|
||||
After making all the previous changes, push them to GitHub before starting the deployment on Vercel:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "prepare repository for deployment"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Deploy to Vercel
|
||||
|
||||
This section covers how to deploy the admin, either using the Vercel website or using Vercel’s CLI tool.
|
||||
|
||||
### Option 1: Using the Vercel Website
|
||||
|
||||
This section explains how to deploy the admin using the Vercel website:
|
||||
|
||||
1. Open the [Vercel dashboard](https://vercel.com/dashboard) after logging in.
|
||||
2. Click on the “Add New…” button next to the search bar.
|
||||
3. Choose Project from the dropdown.
|
||||
4. In the new page that opens, find the Git repository that holds your medusa backend and click on the Import button. If you haven’t connected your Vercel account to any Git provider, you must do that first.
|
||||
5. In the Configure Project form:
|
||||
1. Set the Framework Preset to Vite.
|
||||
2. Open the Build and Output Settings collapsible, and set the Build Command to `yarn build:admin` and the Output Directory to `build`. If you’ve configured the admin to use a different output directory, then change it to that directory.
|
||||
3. Open the Environment Variables collapsible, and add an environment variable with the name `MEDUSA_BACKEND_URL` with the value being the URL to your deployed Medusa backend.
|
||||
4. You can optionally edit the Project Name.
|
||||
6. Once you’re done, click on the “Deploy” button.
|
||||
|
||||
This will start the deployment of the admin. Once it’s done, you’ll be redirected to the main dashboard of your new project.
|
||||
|
||||
:::note
|
||||
|
||||
At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section.
|
||||
|
||||
:::
|
||||
|
||||
### Option 2: Using Vercel’s CLI Tool
|
||||
|
||||
This section explains how to deploy the admin using the Vercel CLI tool. You should have the CLI tool installed first, as explained in [Vercel’s documentation](https://vercel.com/docs/cli).
|
||||
|
||||
In the directory of your Medusa backend, run the following command to deploy your admin:
|
||||
|
||||
```bash
|
||||
vercel --build-env MEDUSA_BACKEND_URL=<YOUR_BACKEND_URL>
|
||||
```
|
||||
|
||||
Where `<YOUR_BACKEND_URL>` is the URL of your deployed Medusa backend.
|
||||
|
||||
You’ll then be asked to log in if you haven’t already, and to choose the scope to deploy your project to. You can also decide to link the admin to an existing project, or change the project’s name.
|
||||
|
||||
When asked, ”In which directory is your code located?”, keep the default `./` and just press Enter.
|
||||
|
||||
The project setup will then start. When asked if you want to modify the settings, answer `y`. You’ll then be asked a series of questions:
|
||||
|
||||
1. “Which settings would you like to overwrite”: select Build Command and Output Directory using the space bar, then press Enter.
|
||||
2. “What's your **Build Command**?”: enter `yarn build:admin`.
|
||||
3. “What's your **Output Directory**?”: enter `build`.
|
||||
|
||||
After that, it will take a couple of minutes for the deployment to finish. The link to the admin will be shown in the final output of the command.
|
||||
|
||||
:::note
|
||||
|
||||
At this point, when you visit the admin, you will face errors related to Cross-Origin Resource Sharing (CORS) while using the admin. Before you start using the admin, follow along the [Configure CORS on the Medusa Backend](#step-6-configure-cors-on-the-medusa-backend) section.
|
||||
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Configure CORS on the Medusa Backend
|
||||
|
||||
To send requests to the Medusa backend from the admin dashboard, you must set the `ADMIN_CORS` environment variable on your backend to the admin’s URL.
|
||||
|
||||
:::note
|
||||
|
||||
If you want to set a custom domain to your admin dashboard on Vercel, make sure to do it before this step. You can refer to this guide on [Vercel’s documentation](https://vercel.com/docs/concepts/projects/domains/add-a-domain).
|
||||
|
||||
:::
|
||||
|
||||
On your Medusa backend, add the following environment variable:
|
||||
|
||||
```bash
|
||||
ADMIN_CORS=<ADMIN_URL>
|
||||
```
|
||||
|
||||
Where `<ADMIN_URL>` is the URL of your admin dashboard that you just deployed.
|
||||
|
||||
Then, restart your Medusa backend. Once the backend is running again, you can use your admin dashboard.
|
||||
Reference in New Issue
Block a user