merge master

docs/content/how-to/deploying-admin-on-netlify.md

@@ -0,0 +1,69 @@
+---
+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.
+
+> 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](https://docs.medusa-commerce.com/how-to/create-medusa-app) for a small walkthrough.
+
+### 1. Install the Netlify CLI
+
+Install Netlify CLI on your machine using npm:
+
+```shell=
+npm install netlify-cli -g
+```
+
+### 2. Login to your Netlify account
+
+Connect to your Netlify account from your terminal:
+
+```shell=
+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
+
+```shell=
+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
+
+```shell=
+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.
+
+```shell=
+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.
+
+> 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.medusa-commerce.com/how-to/deploying-on-heroku).

docs/content/how-to/deploying-on-heroku.md

@@ -0,0 +1,198 @@
+---
+title: "Deploying on Heroku"
+---
+
+# Deploying on Heroku
+
+This is a guide for deploying a Medusa project on Heroku. Heroku is at PaaS that allows you to easily deploy your applications in the cloud.
+
+> We assume, that you are currently running a local instance of Medusa. If not, check out our [Quickstart](https://docs.medusa-commerce.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](https://docs.medusa-commerce.com/how-to/create-medusa-app) for a small walkthrough. 
+
+### 1. Install the Heroku CLI
+
+Install Heroku on your machine:
+
+**Ubuntu**
+
+```shell=
+sudo snap install --classic heroku
+```
+
+**MacOS**
+
+```shell=
+brew tap heroku/brew && brew install heroku
+```
+
+**Windows**
+
+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)
+
+### 2. Login to Heroku from your CLI
+
+Connect to your Heroku account from your terminal:
+
+```shell=
+heroku login
+```
+
+> Follow the instructions on your terminal
+
+### 3. Create an app on Heroku
+
+In your **Medusa project directory** run the following commands to create an app on Heroku and add it as a remote origin.
+
+```shell=
+heroku create medusa-test-app
+heroku git:remote -a medusa-test-app
+```
+
+### 4. Install Postgresql and Redis on Heroku
+
+Medusa requires a Postgres database and a Redis instance to work. These are added through the Heroku CLI using the following commands.
+
+> In this below example, we initialize the resources on free plans. This is not a valid configuration for a production environment.
+
+#### Postgresql
+
+Add a Postgres addon to your Heroku app
+
+```shell=
+heroku addons:create heroku-postgresql:hobby-dev
+```
+
+You can find more informations, plans and pricing about Heroku Postgres [here](https://elements.heroku.com/addons/heroku-postgresql).
+
+#### Redis To Go
+
+Add a Redis instance to your Heroku app
+
+> The addon `redistogo:nano` is free, but Heroku requires you to add a payment method to proceed.
+
+```shell=
+heroku addons:create redistogo:nano
+```
+
+You can find more informations, plans and pricing about Redis To Go [here](https://elements.heroku.com/addons/redistogo).
+
+### 5. Configure environment variables on Heroku
+
+Medusa requires a set of environment variables. From you project repository run the following commands:.
+```shell=
+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
+```
+> Make sure to use actual secrets in a production environment.
+Additionally, we need to set the buildpack to Node.js
+
+```shell=
+heroku buildpacks:set heroku/nodejs
+```
+
+#### Configure the Redis URL
+
+The library we use for connecting to Redis, does not allow usernames in the connection string. Therefore, we need to perform the following commands to remove it.
+Get the current Redis URL:
+
+```shell=
+heroku config:get REDISTOGO_URL
+```
+
+You should get something like:
+
+```shell=
+redis://redistogo:some_password_123@some.redistogo.com:9660/
+```
+
+Remove the username from the Redis URL:
+
+```shell=
+redis://r̶e̶d̶i̶s̶t̶o̶g̶o̶:some_password_123@sole.redistogo.com:9660/
+```
+
+Set the new environment variable `REDIS_URL`
+
+```shell=
+heroku config:set REDIS_URL=redis://:some_password_123@sole.redistogo.com:9660/
+```
+
+### 6. Configure Medusa
+
+Before jumping into the deployment, we need to configure Medusa.
+
+#### `medusa-config.js`
+
+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: 
+      process.env.NODE_ENV !== "development"
+        ? { ssl: { rejectUnauthorized: false } }
+        : {},
+  },
+  plugins,
+};
+```
+
+#### `package.json`
+
+Update `scripts` to include the following:
+
+```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 you Medusa app
+
+Finally, we need to commit and push our changes to Heroku:
+
+```shell=
+git add .
+git commit -m "Deploy Medusa App on Heroku"
+git push heroku HEAD:master
+```
+
+### 7. Inspect your build logs
+
+You can explore your Heroku app build logs using the following command in your project directory.
+
+```shell=
+heroku logs -n 500000 --remote heroku --tail
+```
+
+### 8. Create a user (optional)
+
+As an optional extra step, we can create a user for you to use when your admin system is up and running.
+
+```shell=
+heroku run -a medusa-test-app -- medusa user -e "some-user@test.com" -p "SuperSecret1234"
+```
+
+### What's next?
+
+You now have a production ready application running on Heroku. 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](https://docs.medusa-commerce.com/how-to/deploying-admin-on-netlify)
+- Deploy Admin on Gatsby Cloud (Coming soon)

www/docs/sidebars.js

@@ -115,6 +115,10 @@ module.exports = {
           type: "doc",
           id: "how-to/deploying-on-heroku",
         },
+        {
+          type: "doc",
+          id: "how-to/deploying-admin-on-netlify",
+        },
       ],
     },
   ],