diff --git a/docs/content/how-to/deploying-admin-on-netlify.md b/docs/content/how-to/deploying-admin-on-netlify.md new file mode 100644 index 0000000000..22cd735a5d --- /dev/null +++ b/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). diff --git a/docs/content/how-to/deploying-on-heroku.md b/docs/content/how-to/deploying-on-heroku.md new file mode 100644 index 0000000000..888c092f1b --- /dev/null +++ b/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) diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js index 20fd3988f7..efe1ee8235 100644 --- a/www/docs/sidebars.js +++ b/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", + }, ], }, ],