asyavee/medusa-store
1
0 Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: improved documentation for gatsby deploy (#1758)

Browse Source
This commit is contained in:
Shahed Nasser authored and GitHub committed 2022-06-30 20:29:28 +03:00
1 parent 109afa45c1
commit 835327b378
2 files changed
+266 -31
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/content/deployments/storefront/deploying-gatsby-on-netlify.md
+260 -31
View File
@@ -1,71 +1,300 @@
--- # Deploy Gatsby Storefront on Netlify
title: "Deploying your Gatsby storefront on Netlify"
---
# Deploying your Gatsby storefront on Netlify In this document, you’ll learn how to deploy the Gatsby Storefront on [Netlify](https://www.netlify.com/).
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. <!-- Alternatively, you can use this button to deploy the Gatsby Storefront to Netlify directly:
> 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. [![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/medusajs/gatsby-starter-medusa) -->
### 1. Install the Netlify CLI ## Prerequisites
Install Netlify CLI on your machine using npm: ### Medusa Components
```bash npm2yarn Before proceeding with this documentation, it is assumed you already have the Gatsby storefront installed locally. If not, please go through the [quickstart guide](../../starters/gatsby-medusa-starter.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 Gatsby storefront. If you don’t have one, you can create one on [Netlify’s website](https://app.netlify.com/signup).
Additionally, you need a GitHub account where you will host the repository for the Gatsby storefront. You can create it on [GitHub’s website](https://github.com/signup).
:::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 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 Gatsby storefront 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)
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.
![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, 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.
![GitHub Repository URL](https://i.imgur.com/pHfSTuT.png)
Copy the link. Then, open your terminal in the directory that holds your Gatsby storefront 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”.
:::
![Create a new website](https://i.imgur.com/IUUOzoW.png)
You’ll then be asked to connect to a Git provider.
![Connect Git Provider](https://i.imgur.com/T6lZPDi.png)
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.
![Choose Repository](https://i.imgur.com/SRI3r1Y.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 haven’t deployed your Medusa server yet, you can leave the value blank for now and add it later. However, the build process for the Gatsby storefront will fail.
:::
![Environment Variable](https://i.imgur.com/DnutZfT.png)
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.
![Site Deployment Progress](https://i.imgur.com/PUDjjnL.png)
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.
:::tip
If you haven’t added any products to your Medusa server, the build process might fail. It’s recommended to add some products to the server first in that case.
Alternatively, you can seed the server with demo data by running this command in the root directory of the server:
```bash
medusa seed -f data/seed.json
```
:::
![Deployment Complete](https://i.imgur.com/dPF9HvF.png)
If you click on it, you’ll be redirected to the deployed storefront website.
![Gatsby Storefront](https://i.imgur.com/l08cBSA.png)
:::caution
At this point, you will face errors related to CORS while using the storefront. Before you start using the storefront, follow along the [Configure CORS on the Medusa Server section](#configure-cors-variable-on-the-medusa-server).
:::
### Option 2: Using Netlify’s CLI Tool
In this section, you’ll deploy the Gatsby storefront 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 npm install netlify-cli -g
``` ```
### 2. Login to your Netlify account #### Login to Netlify
Connect to your Netlify account from your terminal: Then, run the following command to log in to Netlify in your terminal:
```bash ```bash
netlify login netlify login
``` ```
Follow the instructions in your terminal. This opens a page to log in on your browser. You’ll be asked to authorize the Netlify CLI tool.
### 3. Netlify setup ![Authorize Application](https://i.imgur.com/JDUdqSE.png)
In order to deploy the project to Netlify, you need to create a new site, link the storefront Git repository to the site and configure environment variables. Click on Authorize. Then, you can go back to your terminal and see that you’ve successfully logged in.
The Netlify CLI is used to achieve this. ![Authorized Message](https://i.imgur.com/L13Yqhp.png)
#### Create a new site #### Initialize Netlify Website
In your terminal, run the following command:
```bash ```bash
netlify init netlify init
``` ```
Follow the instructions in your terminal to authorize and connect your Git repository. You’ll have to follow 5 steps for the initialization:
The default build and deploy settings fit the needs of a Gatsby application, so leave these as is. ##### Step 1: Create Netlify Website
#### Add an environment variable 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 ```bash
netlify env:set GATSBY_MEDUSA_BACKEND_URL "https://your-medusa-server.com" ? What would you like to do?
⇄ Connect this directory to an existing Netlify site
❯ + Create & configure a new site
``` ```
The above environment variable should point to your Medusa server. ##### Step 2: Choose Netlify Team
### 4. Push and deploy Choose the team you want to create the website in if you have multiple teams.
Finally to deploy the storefront, commit and push your changes to the repository connected in step 3. ##### 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 ```bash
git add . ? Netlify CLI needs access to your GitHub account to configure Webhooks and Depl
git commit -m "Deploy Medusa Admin on Netlify" oy Keys. What would you like to do? (Use arrow keys)
git push origin main ❯ Authorize with GitHub through app.netlify.com
Authorize with a GitHub personal access token
``` ```
Within a couple of minutes, your Gatsby storefront is up and running on Netlify. 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 experience CORS issues in your new setup, you might need to add your storefront url as part of the STORE_CORS environment variable in your server setup. 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.
### What's next? ##### Last Step: Steps with Default Values
If you haven't deployed your Medusa server to use with your new storefront, check out our guide [Deploying on Heroku](https://docs.medusajs.com/how-to/deploying-on-heroku). 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.
Gatsby is not your thing? Check out our [Next.js storefront starter](https://github.com/medusajs/nextjs-starter-medusa). #### 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 haven’t deployed your Medusa server yet, you can leave the value blank for now and add it later. However, the build process for the Gatsby storefront will fail.
:::
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.
:::tip
If you haven’t added any products to your Medusa server, the build process might fail. It’s recommended to add some products to the server first in that case.
Alternatively, you can seed the server with demo data by running this command in the root directory of the server:
```bash
medusa seed -f data/seed.json
```
:::
#### Open the Gatsby storefront Website
To open the Gatsby storefront website, either use the URL shown to you or run the following command:
```bash
netlify open:site
```
The Gatsby storefront will then open in your browser.
![Gatsby Storefront](https://i.imgur.com/l08cBSA.png)
Before you can use the Gatsby storefront, 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 Gatsby storefront, you must set the `STORE_CORS` environment variable on your server to the Gatsby storefront’s URL.
:::caution
If you want to set a custom domain to your Gatsby storefront 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 server, add the following environment variable:
```bash
STORE_CORS=<STOREFRONT_URL>
```
Where `<STOREFRONT_URL>` is the URL of your Gatsby storefront that you just deployed.
Then, restart your Medusa server. Once the server is running again, you can use your Gatsby storefront.
## What’s Next 🚀
- Learn how to [deploy the Medusa Admin](../admin/index.mdx).
- Learn more about [Medusa’s configurations](../../usage/configurations.md).
docs/content/starters/gatsby-medusa-starter.md
+6
View File
@@ -14,6 +14,12 @@ You should also have the Gatsby CLI installed:
npm install gatsby-cli -g npm install gatsby-cli -g
``` ```
<!-- ## Instant Deployment to Netlify
Instead of manually following this guide to install then later deploy the Gatsby Storefront, you can deploy the Gatsby Storefront 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/gatsby-starter-medusa) -->
## Installation ## Installation
1\. Create a new Gatsby project using the [Medusa starter template](https://github.com/medusajs/gatsby-starter-medusa): 1\. Create a new Gatsby project using the [Medusa starter template](https://github.com/medusajs/gatsby-starter-medusa):