docs: improved s3 documentation (#1965)
This commit is contained in:
Shahed Nasser
+118
-56
@@ -1,109 +1,171 @@
|
||||
# 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.
|
||||
In this document, you’ll learn how to install the [S3 plugin](https://github.com/medusajs/medusa/tree/master/packages/medusa-file-s3) on your Medusa server and use it for storage.
|
||||
|
||||
### Before you start
|
||||
## Overview
|
||||
|
||||
At this point, you should have an instance of our store engine running. If not, we have a [full guide](https://docs.medusajs.com/tutorial/set-up-your-development-environment) for setting up your local environment.
|
||||
To manage images in Medusa, you need a file service plugin responsible for hosting the images. Without a file service plugin, you will face issues while working with Medusa, such as when uploading images for products.
|
||||
|
||||
### Set up AWS
|
||||
Medusa provides three different options to handle your file storage. This document focuses on using [S3](https://aws.amazon.com/s3/) to store your Medusa server’s images.
|
||||
|
||||
#### Create an S3 bucket
|
||||
## Prerequisites
|
||||
|
||||
In the AWS console navigate to S3 and create a bucket for your images. Make sure to uncheck "Block _all_ public access".
|
||||
### Medusa Server
|
||||
|
||||
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:
|
||||
A Medusa server is required to be set up before following along with this document. You can follow the [quickstart guide](../quickstart/quick-start.md) to get started in minutes.
|
||||
|
||||
```shell=
|
||||
### Required Accounts
|
||||
|
||||
You need to [create an AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin) to follow along with this documentation.
|
||||
|
||||
## Create S3 Bucket
|
||||
|
||||
On your AWS Console, search for S3 in the search box at the top. Then, choose the first result you see which should be S3 under the Services category.
|
||||
|
||||
|
||||
|
||||
Then, on the new page that opens, click on Create Bucket button at the top right of the Buckets table.
|
||||
|
||||
|
||||
|
||||
The Create Bucket form will open. In the General Configuration section enter a name for the bucket and choose a region for the bucket. Both of the values of these fields are important as you’ll use them throughout the documentation.
|
||||
|
||||
|
||||
|
||||
Next, in the Object Ownership section, choose ACLs enabled. Then, 2 radio buttons will show below it. Choose Bucket owner preferred.
|
||||
|
||||
|
||||
|
||||
Then, in the “Block Public Access settings for this bucket” section, uncheck the “Block all public access” checkbox. This shows a warning message at the bottom of the section with another checkbox. Check the checkbox to ensure you understand that objects in the bucket are publicly accessible.
|
||||
|
||||
|
||||
|
||||
You can leave the rest of the fields in the form as is and scroll down to the end of the page. Then, click on the Create Bucket button.
|
||||
|
||||
## Manage Bucket Policies
|
||||
|
||||
On the page of the bucket you just created, click on the Permissions tab. Then, scroll down until you find the Bucket policy section. Click on Edit in that section.
|
||||
|
||||
|
||||
|
||||
In the Edit Bucket Policy page, enter the following in the field:
|
||||
|
||||
```json
|
||||
{
|
||||
"Version": "2012-10-17",
|
||||
"Id": "Policy1397632521960",
|
||||
"Statement": [
|
||||
{
|
||||
"Sid": "Stmt1397633323327",
|
||||
"Action": [
|
||||
"s3:GetObject"
|
||||
],
|
||||
"Effect": "Allow",
|
||||
"Resource": "arn:aws:s3:::YOUR-BUCKET-NAME/*",
|
||||
"Principal": {
|
||||
"AWS": [
|
||||
"*"
|
||||
]
|
||||
}
|
||||
"AWS": "*"
|
||||
},
|
||||
"Action": "s3:GetObject",
|
||||
"Resource": "arn:aws:s3:::<YOUR_BUCKET_NAME>/*"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Be aware, that this will allow for anyone to acces your bucket. Avoid storing sensitive data.
|
||||
Make sure to replace `<YOUR_BUCKET_NAME>` with the name of the bucket you created.
|
||||
|
||||
#### Generate access keys
|
||||
Once you’re done, scroll down and click on the Save changes button.
|
||||
|
||||
Navigate to the IAM section of your AWS console and perform the following steps:
|
||||
### User Permissions
|
||||
|
||||
- Add a new user with programmatic access
|
||||
- Add the existing **AmazonS3FullAccess** policy to the user
|
||||
- Submit the details
|
||||
Your user must have the `AmazonS3FullAccess` policy attached to it. You can refer to [this guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html) to learn how to add a policy if necessary.
|
||||
|
||||
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.
|
||||
### Obtain Access Keys
|
||||
|
||||
### Installation
|
||||
You must obtain access keys for your user as you’ll use them to integrate the S3 plugin in Medusa with your bucket. To obtain the Access Key ID and the Secret Access Key, check out [this guide](https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys).
|
||||
|
||||
First, install the plugin using your preferred package manager:
|
||||
## Install the S3 Plugin
|
||||
|
||||
In the directory of your Medusa server, run the following command to install the S3 Plugin:
|
||||
|
||||
```bash npm2yarn
|
||||
npm install medusa-file-s3
|
||||
```
|
||||
|
||||
Then configure your `medusa-config.js` to include the plugin alongside the required options:
|
||||
Then, add the following environment variables:
|
||||
|
||||
```=javascript
|
||||
{
|
||||
```bash
|
||||
S3_URL=<YOUR_BUCKET_URL>
|
||||
S3_BUCKET=<YOUR_BUCKET_NAME>
|
||||
S3_REGION=<YOUR_BUCKET_REGION>
|
||||
S3_ACCESS_KEY_ID=<YOUR_ACCESS_KEY_ID>
|
||||
S3_SECRET_ACCESS_KEY=<YOUR_SECRET_ACCESS_KEY>
|
||||
```
|
||||
|
||||
Where:
|
||||
|
||||
1. `<YOUR_BUCKET_URL>` is the URL to your bucket. It’s in the form `https://<BUCKET_NAME>.s3.<REGION>.amazonaws.com`, where `<BUCKET_NAME>` is the name of the bucket and the `<REGION>` is the region the bucket is created in. If you’re not sure which region, on your bucket’s page on S3 click on Properties. You can then find the region under AWS Region. Make sure to only copy the code (for example, `us-east-1`).
|
||||
2. `<YOUR_BUCKET_NAME>` is the name of the bucket you created.
|
||||
3. `<YOUR_BUCKET_REGION>` is the region code of your bucket. For example, `us-east-1`.
|
||||
4. `<YOUR_ACCESS_KEY_ID>` is the Access Key ID that you created for your user.
|
||||
5. `<YOUR_SECRET_ACCESS_KEY>` is the Secret Access Key that you created for your user.
|
||||
|
||||
Finally, in `medusa-config.js`, add to the `plugins` array the following new item:
|
||||
|
||||
```jsx
|
||||
const plugins = [
|
||||
//...
|
||||
{
|
||||
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",
|
||||
s3_url: process.env.S3_URL,
|
||||
bucket: process.env.S3_BUCKET,
|
||||
region: process.env.S3_REGION,
|
||||
access_key_id: process.env.S3_ACCESS_KEY_ID,
|
||||
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
|
||||
},
|
||||
},
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
In the above options, an `s3_url` is included. The url has the following format:
|
||||
## Test the S3 Plugin
|
||||
|
||||
```shell=
|
||||
https://[bucket].s3.[region].amazonaws.com
|
||||
Run your Medusa server with the following command:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run start
|
||||
```
|
||||
|
||||
The two access keys in the options are the ones created in the previous section.
|
||||
Then, you can either test the plugin using the [REST APIs](https://docs.medusajs.com/api/store) or using the [Medusa Admin](../admin/quickstart.md).
|
||||
|
||||
:::tip
|
||||
On the Medusa Admin, create a new product and, in the Images section, upload an image then click Save. If the integration was successful, the product image will be uploaded successfully.
|
||||
|
||||
Make sure to use an environment variable for the secret key in a live environment.
|
||||
|
||||
|
||||
:::
|
||||
You can also check that the image was uploaded on the S3 bucket’s page.
|
||||
|
||||
:::caution
|
||||
|
||||
|
||||
If you have multiple storage plugins configured, the last plugin declared in the `medusa-config.js` file will be used.
|
||||
## Next.js Storefront Configuration
|
||||
|
||||
:::
|
||||
If you’re using a [Next.js](../starters/nextjs-medusa-starter.md storefront, you need to add an additional configuration that adds the S3 bucket domain name into the configured images’ domain names. This is because all URLs of product images will be from the S3 bucket.
|
||||
|
||||
### Try it out
|
||||
If this configuration is not added, you’ll receive the error ["next/image Un-configured Host”](https://nextjs.org/docs/messages/next-image-unconfigured-host).
|
||||
|
||||
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.
|
||||
In `next.config.js` add the following option in the exported object:
|
||||
|
||||
### Troubleshoot Errors
|
||||
```jsx
|
||||
module.exports = withStoreConfig({
|
||||
//...
|
||||
images: {
|
||||
domains: [
|
||||
//...
|
||||
"<BUCKET_NAME>.s3.amazonaws.com"
|
||||
],
|
||||
},
|
||||
})
|
||||
```
|
||||
|
||||
#### The bucket does not allow ACLs
|
||||
Where `<BUCKET_NAME>` is the name of the S3 bucket you’re using.
|
||||
|
||||
If the backend file upload fails with this message then you need to enable ACLs on your S3 bucket.
|
||||
## What’s Next 🚀
|
||||
|
||||
To do this,
|
||||
- Go to the `Bucket -> Permissions` tab
|
||||
- Scroll to `Object Ownership` and click `edit`
|
||||
- Select `ACLs enabled` and `Bucket owner preferred`
|
||||
- Click the `Save Changes`
|
||||
|
||||
File uploads should now work.
|
||||
- Check out [more plugins](https://github.com/medusajs/medusa/tree/master/packages) you can add to your store.
|
||||
- Learn how to [deploy the Medusa server](../deployments/server/index.mdx).
|
||||
- Learn about the [Next.js](../starters/nextjs-medusa-starter.md) and [Gatsby](../starters/gatsby-medusa-starter.md) storefronts.
|
||||
|
||||
Reference in New Issue
Block a user