From 337fc16c38fe90c2b985f5434fe62da758ba3f59 Mon Sep 17 00:00:00 2001
From: Oliver Windall Juhl <59018053+olivermrbl@users.noreply.github.com>
Date: Fri, 1 Oct 2021 12:58:44 +0200
Subject: [PATCH] docs: Add fileservice guides for S3 and Spaces (#430)

* docs: Add fileservice guides for S3 and Spaces

* fix: remove we in s3 guide

* fix: typos in spaces guide
---
 docs/content/how-to/uploading-images-to-s3.md | 85 +++++++++++++++++++
 .../how-to/uploading-images-to-spaces.md      | 36 ++++++++
 packages/medusa-file-s3/README.md             | 15 ++++
 packages/medusa-file-spaces/README.md         | 15 ++++
 www/docs/sidebars.js                          | 18 ++++
 5 files changed, 169 insertions(+)
 create mode 100644 docs/content/how-to/uploading-images-to-s3.md
 create mode 100644 docs/content/how-to/uploading-images-to-spaces.md
 create mode 100644 packages/medusa-file-s3/README.md
 create mode 100644 packages/medusa-file-spaces/README.md

diff --git a/docs/content/how-to/uploading-images-to-s3.md b/docs/content/how-to/uploading-images-to-s3.md
new file mode 100644
index 0000000000..bc71a22736
--- /dev/null
+++ b/docs/content/how-to/uploading-images-to-s3.md
@@ -0,0 +1,85 @@
+# Uploading images to S3
+
+In order to work with images in Medusa, you need a file service plugin responsible for hosting. Following this guide will allow you to upload images to AWS S3.
+
+### Before you start
+
+At this point, you should have an instance of our store engine running. If not, we have a [full guide](https://docs.medusa-commerce.com/tutorial/set-up-your-development-environment) for setting up your local environment.
+
+### Set up up AWS
+
+#### Create an S3 bucket
+
+In the AWS console navigate to S3 and create a bucket for your images. Make sure to uncheck "Block _all_ public access".
+
+Additionally, you need to add a policy to your bucket, that will allow public access to objects that are uploaded. Navigate to the permissions tab of your bucket and add the following policy:
+
+```shell=
+{
+  "Id": "Policy1397632521960",
+  "Statement": [
+    {
+      "Sid": "Stmt1397633323327",
+      "Action": [
+        "s3:GetObject"
+      ],
+      "Effect": "Allow",
+      "Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*",
+      "Principal": {
+        "AWS": [
+          "*"
+        ]
+      }
+    }
+  ]
+}
+```
+
+Be aware, that this will allow for anyone to acces your bucket. Avoid storing sensitive data.
+
+#### Generate access keys
+
+Navigate to the IAM section of your AWS console and perform the following steps:
+
+- Add a new user with programmatic access
+- Add the existing **AmazonS3FullAccess** policy to the user
+- Submit the details
+
+Upon successfull creation of the user, you are presented with an **Access key ID** and a **Secret access key**. Note both of them down for later use.
+
+### Installation
+
+First, install the plugin using your preferred package manager:
+
+```
+yarn add medusa-file-s3
+```
+
+Then configure your `medusa-config.js` to include the plugin alongside the required options:
+
+```=javascript
+{
+    resolve: `medusa-file-s3`,
+    options: {
+        s3_url: "https://s3-guide-test.s3.eu-west-1.amazonaws.com",
+        bucket: "test",
+        region: "eu-west-1"
+        access_key_id: "YOUR-ACCESS-KEY",
+        secret_access_key: "YOUR-SECRET-KEY",
+    },
+},
+```
+
+In the above options, an `s3_url` is included. The url has the following format:
+
+```shell=
+https://[bucket].s3.[region].amazonaws.com
+```
+
+The two access keys in the options are the ones created in the previous section.
+
+> Make sure to use an environment variable for the secret key in a live environment.
+
+### Try it out
+
+Finally, run your Medusa server alongside our admin system to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in an AWS S3 bucket.
diff --git a/docs/content/how-to/uploading-images-to-spaces.md b/docs/content/how-to/uploading-images-to-spaces.md
new file mode 100644
index 0000000000..976b077dd6
--- /dev/null
+++ b/docs/content/how-to/uploading-images-to-spaces.md
@@ -0,0 +1,36 @@
+# Uploading images to Spaces
+In order to work with images in Medusa, you need a file service plugin responsible for hosting. Following this guide will allow you to upload images to DigitalOcean Spaces.
+
+### Before you start
+At this point, you should have an instance of our store engine running. If not, we have a [full guide](https://docs.medusa-commerce.com/tutorial/set-up-your-development-environment) for setting up your local environment.
+
+### Set up up DigitalOcean
+#### Create a Space
+Create an account on DigitalOcean and navigate to Spaces. Create a new Space with the default settings.
+
+#### Generate access keys
+Navigate to API in the left sidebar. Generate a new Spaces access key. This should provide you with an access key id and a secret key. Note them both down.
+
+### Installation
+First, install the plugin using your preferred package manager:
+```
+yarn add medusa-file-spaces
+```
+Then configure your `medusa-config.js` to include the plugin alongside the required options:
+```=javascript
+{
+    resolve: `medusa-file-spaces`,
+    options: {
+        spaces_url: "https://test.fra1.digitaloceanspaces.com",
+        bucket: "test",
+        endpoint: "fra1.digitaloceanspaces.com",
+        access_key_id: "YOUR-ACCESS-KEY",
+        secret_access_key: "YOUR-SECRET-KEY",
+    },
+},
+```
+In the above options, a `spaces_url` is included. This can be found in your Space overview. The `bucket` should point to the name you gave your Space. The `endpoint` identifies the region in which you created the Space. And finally the two keys are the ones created in the previous section.
+> Make sure to use an environment variable for the secret key in a live environment.
+
+### Try it out!
+Finally, run your Medusa server alongside our admin system to try out your new file service. Upon editing or creating products, you can now upload thumbnails and images, that are stored in DigitalOcean Spaces.
diff --git a/packages/medusa-file-s3/README.md b/packages/medusa-file-s3/README.md
new file mode 100644
index 0000000000..e5ea97a571
--- /dev/null
+++ b/packages/medusa-file-s3/README.md
@@ -0,0 +1,15 @@
+# medusa-file-s3
+
+Upload files to an AWS S3 bucket.
+
+## Options
+
+```
+  s3_url: [url of your s3 bucket],
+  access_key_id: [access-key],
+  secret_access_key: [secret-access-key],
+  bucket: [name of your bucket],
+  region: [region of your bucket],
+```
+
+Follow [this guide](https://docs.medusa-commerce.com/how-to/uploading-images-to-s3) to configure the plugin.
diff --git a/packages/medusa-file-spaces/README.md b/packages/medusa-file-spaces/README.md
new file mode 100644
index 0000000000..f756dc1cde
--- /dev/null
+++ b/packages/medusa-file-spaces/README.md
@@ -0,0 +1,15 @@
+# medusa-file-spaces
+
+Upload files to a DigitalOcean Space.
+
+## Options
+
+```
+  spaces_url: [url of your DigitalOcean space],
+  access_key_id: [access-key],
+  secret_access_key: [secret-access-key],
+  bucket: [name of your bucket],
+  endpoint: [endpoint of you DigitalOcean space],
+```
+
+Follow [this guide](https://docs.medusa-commerce.com/how-to/uploading-images-to-spaces) to configure the plugin.
diff --git a/www/docs/sidebars.js b/www/docs/sidebars.js
index b8fadb9968..20fd3988f7 100644
--- a/www/docs/sidebars.js
+++ b/www/docs/sidebars.js
@@ -79,6 +79,14 @@ module.exports = {
           type: "doc",
           id: "how-to/create-medusa-app",
         },
+        {
+          type: "doc",
+          id: "how-to/uploading-images-to-spaces",
+        },
+        {
+          type: "doc",
+          id: "how-to/uploading-images-to-s3",
+        },
       ],
     },
     {
@@ -99,5 +107,15 @@ module.exports = {
         },
       ],
     },
+    {
+      type: "category",
+      label: "Deploy",
+      items: [
+        {
+          type: "doc",
+          id: "how-to/deploying-on-heroku",
+        },
+      ],
+    },
   ],
 }