Shahed Nasser
348 lines
9.1 KiB
Plaintext
348 lines
9.1 KiB
Plaintext
import S3BucketAcl from "../../../troubleshooting/_sections/s3/aws-bucket-acl.mdx"
|
|
import { Table, Tabs, TabsList, TabsContent, TabsContentWrapper, TabsTrigger, DetailsList } from "docs-ui"
|
|
|
|
export const metadata = {
|
|
title: `S3 File Module Provider`,
|
|
}
|
|
|
|
# {metadata.title}
|
|
|
|
The S3 File Module Provider integrates Amazon S3 and services following a compatible API (such as MinIO or DigitalOcean Spaces) to store files uploaded to your Medusa application.
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
<Tabs defaultValue="aws">
|
|
<TabsList>
|
|
<TabsTrigger value="aws">AWS S3</TabsTrigger>
|
|
<TabsTrigger value="minio">MinIO</TabsTrigger>
|
|
<TabsTrigger value="spaces">DigitalOcean Spaces</TabsTrigger>
|
|
</TabsList>
|
|
<TabsContentWrapper>
|
|
<TabsContent value="aws">
|
|
|
|
- [AWS account](https://console.aws.amazon.com/console/home?nc2=h_ct&src=header-signin).
|
|
- Create [AWS user with AmazonS3FullAccess permissions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-create-and-attach-iam-policy.html).
|
|
- Create [AWS user access key ID and secret access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html#Using_CreateAccessKey).
|
|
- Create [S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) with the "Public Access setting" enabled:
|
|
1. On your bucket's dashboard, click on the Permissions tab.
|
|
2. Click on the Edit button of the Block public access (bucket settings) section.
|
|
3. In the form that opens, don't toggle any checkboxes and click the "Save changes" button.
|
|
4. Confirm saving the changes by entering `confirm` in the pop-up that shows.
|
|
5. Back on the Permissions page, scroll to the Object Ownership section and click the Edit button.
|
|
6. In the form that opens:
|
|
- Choose the "ACLs enabled" card.
|
|
- Click on the "Save changes" button.
|
|
7. Back on the Permissions page, scroll to the "Access Control List (ACL)" section and click on the Edit button.
|
|
8. In the form that opens, enable the Read permission for "Everyone (public access)".
|
|
9. Check the "I understand the effects of these changes on my objects and buckets." checkbox.
|
|
10. Click on the "Save changes" button.
|
|
|
|
</TabsContent>
|
|
<TabsContent value="minio">
|
|
|
|
- [Install MinIO](https://min.io/docs/minio/linux/index.html).
|
|
- Change port to `9001` using the [console address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-console-address) and [address](https://min.io/docs/minio/linux/reference/minio-server/minio-server.html#minio.server.-address) CLI options.
|
|
- Create [MinIO access and secret access key](https://min.io/docs/minio/linux/administration/console/security-and-access.html#id1).
|
|
- Create a [MinIO bucket](https://min.io/docs/minio/linux/administration/console/managing-objects.html#creating-buckets) with public access policy:
|
|
- Go to the bucket's dashboard.
|
|
- Under the Summary section, click on the pencil icon next to Access Policy.
|
|
- In the pop-up, choose Custom from the dropdown.
|
|
- In the editor, enter the following:
|
|
|
|
```json highlights={[["15", "{bucketname}", "Replace with the bucket's name."]]}
|
|
{
|
|
"Version": "2012-10-17",
|
|
"Statement": [
|
|
{
|
|
"Action": [
|
|
"s3:GetObject"
|
|
],
|
|
"Effect": "Allow",
|
|
"Principal": {
|
|
"AWS": [
|
|
"*"
|
|
]
|
|
},
|
|
"Resource": [
|
|
"arn:aws:s3:::{bucketname}/*"
|
|
]
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
Make sure to replace `{bucket_name}` with the name of the bucket you created. You can edit the access policy under the Summary section of your bucket's dashboard.
|
|
|
|
</TabsContent>
|
|
<TabsContent value="spaces">
|
|
|
|
- Create [DigitalOcean account](https://cloud.digitalocean.com/registrations/new).
|
|
- Create [DigitalOcean Spaces bucket](https://docs.digitalocean.com/products/spaces/how-to/create/).
|
|
- Create [DigitalOcean Spaces access and secret access keys](https://docs.digitalocean.com/products/spaces/how-to/manage-access/#access-keys).
|
|
|
|
</TabsContent>
|
|
</TabsContentWrapper>
|
|
</Tabs>
|
|
|
|
---
|
|
|
|
## Install the S3 File Module
|
|
|
|
To install the S3 File Module Provider, run the following command in the directory of your Medusa application:
|
|
|
|
```bash npm2yarn
|
|
npm install @medusajs/file-s3@preview
|
|
```
|
|
|
|
Next, add the module into the `providers` array of the File Module:
|
|
|
|
<Note>
|
|
|
|
The File Module accepts one provider only.
|
|
|
|
</Note>
|
|
|
|
```js title="medusa-config.js"
|
|
import { Modules } from "@medusajs/utils"
|
|
|
|
// ...
|
|
|
|
module.exports = {
|
|
// ...
|
|
modules: {
|
|
// ...
|
|
[Modules.FILE]: {
|
|
resolve: "@medusajs/file",
|
|
options: {
|
|
providers: [
|
|
{
|
|
resolve: "@medusajs/file-s3",
|
|
id: "s3",
|
|
options: {
|
|
file_url: process.env.S3_FILE_URL,
|
|
access_key_id: process.env.S3_ACCESS_KEY_ID,
|
|
secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
|
|
region: process.env.S3_REGION,
|
|
bucket: process.env.S3_BUCKET,
|
|
endpoint: process.env.S3_ENDPOINT,
|
|
// other options...
|
|
},
|
|
},
|
|
],
|
|
},
|
|
},
|
|
},
|
|
}
|
|
```
|
|
|
|
### S3 File Module Options
|
|
|
|
<Table>
|
|
<Table.Header>
|
|
<Table.Row>
|
|
<Table.HeaderCell>Option</Table.HeaderCell>
|
|
<Table.HeaderCell>Description</Table.HeaderCell>
|
|
<Table.HeaderCell>Default</Table.HeaderCell>
|
|
</Table.Row>
|
|
</Table.Header>
|
|
<Table.Body>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`file_url`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The base URL to upload files to.
|
|
|
|
- For AWS S3, the endpoint is of the format `https://{bucket}.s3.{region}.amazonaws.com`
|
|
- For MinIO, it's the URL to the MinIO server with the bucket's name. For example, `https://{server-domain}/{bucket}`.
|
|
- For DigitalOcean Spaces, it's either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`access_key_id`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The AWS or (S3 compatible) user's access key ID.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`secret_access_key`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The AWS or (S3 compatible) user's secret access key.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`region`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The bucket's region code.
|
|
|
|
For MinIO, use `us-east-1`.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`bucket`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The bucket's name.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`endpoint`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
The URL to the AWS S3 (or compatible S3 API) server.
|
|
|
|
- For AWS S3, the endpoint is of the format `https://s3.{region}.amazonaws.com`
|
|
- For MinIO, it's the URL to the MinIO server.
|
|
- For DigitalOcean Spaces, it's the Spaces Origin Endpoint.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`prefix`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
A string to prefix each uploaded file's name.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`cache_control`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
A string indicating how long objects remain in the AWS S3 (or compatible S3 API) cache.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
`public, max-age=31536000`
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`download_file_duration`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
A number indicating the expiry time of presigned URLs in seconds.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
`3600` (An hour)
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
<Table.Row>
|
|
<Table.Cell>
|
|
|
|
`additional_client_config`
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
Any additional configurations to pass to the S3 client.
|
|
|
|
Refer to [this AWS API reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Config.html) for a full list of accepted configuration.
|
|
|
|
</Table.Cell>
|
|
<Table.Cell>
|
|
|
|
\-
|
|
|
|
</Table.Cell>
|
|
</Table.Row>
|
|
</Table.Body>
|
|
</Table>
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
<DetailsList
|
|
sections={[
|
|
{
|
|
title: "AWS: The bucket does not allow ACLs (Enabling public access to bucket)",
|
|
content: <S3BucketAcl />
|
|
}
|
|
]}
|
|
/>
|