docs: rename Architectural Modules to Infrastructure Modules (#12212)
* docs: rename Architectural Modules to Infrastructure Modules * generate again
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,427 @@
|
||||
import S3BucketAcl from "../../../troubleshooting/_sections/s3/aws-bucket-acl.mdx"
|
||||
import CloudflareChecksum from "../../../troubleshooting/_sections/s3/cloudflare-checksum.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>
|
||||
<TabsTrigger value="supabase">Supabase S3 Storage</TabsTrigger>
|
||||
<TabsTrigger value="cloudflare">Cloudflare R2</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:
|
||||
- Go to User -> Access Keys
|
||||
- Click on the Create Access Keys button.
|
||||
- Click on the Create button.
|
||||
- Copy the keys of the pop-up. Make sure to copy the secret key as it won't be shown again.
|
||||
- Create a [MinIO bucket](https://min.io/docs/minio/linux/administration/console/managing-objects.html#creating-buckets) with public access policy. To add the policy:
|
||||
- Go to the bucket's dashboard from Administrator -> Buckets.
|
||||
- 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>
|
||||
<TabsContent value="supabase">
|
||||
|
||||
- [Supabase account](https://supabase.com/dashboard/sign-in) with a project.
|
||||
- Create [New Public S3 bucket](https://supabase.com/docs/guides/storage/buckets/creating-buckets?queryGroups=language&language=dashboard).
|
||||
- Create [New S3 Access Keys](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys).
|
||||
- Create [Storage Policy](https://supabase.com/docs/guides/storage/security/access-control).
|
||||
1. On your bucket's dashboard, click on Policies under the Configuration sidebar.
|
||||
2. Click on New Policy under "Other policies under storage.objects".
|
||||
3. Click get started quickly, choose "insert access for authenticated users only", and click the "Use this template" button.
|
||||
4. Click ALL for "Allowed Operations", click the "Review" button, then the "Save policy" button.
|
||||
|
||||
</TabsContent>
|
||||
<TabsContent value="cloudflare">
|
||||
1. Create a [Cloudflare account](https://dash.cloudflare.com/sign-up).
|
||||
2. Set up your R2 bucket:
|
||||
- Navigate to R2 Object Storage in your dashboard. You may need to provide your credit-card information.
|
||||
- Click "Create bucket"
|
||||
- Enter a unique bucket name
|
||||
- Select "Automatic" for location
|
||||
- Choose "Standard" for storage class
|
||||
- Confirm by clicking "Create bucket"
|
||||
3. Configure public access:
|
||||
- On your bucket's dashboard, click on the Settings tab.
|
||||
- Scroll down to the Public Access section, and click on "Allow Access" in the "R2.dev subdomain" card.
|
||||
- Type 'allow' to confirm
|
||||
- Copy the Public R2.dev Bucket URL for your `S3_FILE_URL`
|
||||
4. Retrieve credentials:
|
||||
- [Go to API tokens page](https://dash.cloudflare.com/?to=/:account/r2/api-tokens):
|
||||
- Select "Create API token"
|
||||
- Edit the "R2 Token" name
|
||||
- Under Permissions, select Object Read & Write permission types
|
||||
- You can optionally specify the buckets that this API token has access to under the "Specify bucket(s)" section.
|
||||
- Once done, click the "Create API Token" button.
|
||||
- You'll receive an access key ID and a secret access key. Save them to use them later for the `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` environment variables.
|
||||
|
||||
</TabsContent>
|
||||
</TabsContentWrapper>
|
||||
</Tabs>
|
||||
|
||||
---
|
||||
|
||||
## Register the S3 File Module
|
||||
|
||||
Add the module into the `providers` array of the File Module:
|
||||
|
||||
<Note>
|
||||
|
||||
The File Module accepts one provider only.
|
||||
|
||||
</Note>
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
import { Modules } from "@medusajs/framework/utils"
|
||||
|
||||
// ...
|
||||
|
||||
module.exports = {
|
||||
// ...
|
||||
modules: [
|
||||
// ...
|
||||
{
|
||||
resolve: "@medusajs/medusa/file",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/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...
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
### Additional Configuration for MinIO and Supabase
|
||||
|
||||
If you're using MinIO or Supabase, set `forcePathStyle` to `true` in the `additional_client_config` object.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="medusa-config.ts"
|
||||
module.exports = defineConfig({
|
||||
// ...
|
||||
modules: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/file",
|
||||
options: {
|
||||
providers: [
|
||||
{
|
||||
resolve: "@medusajs/medusa/file-s3",
|
||||
id: "s3",
|
||||
options: {
|
||||
// ...
|
||||
additional_client_config: {
|
||||
forcePathStyle: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
],
|
||||
})
|
||||
```
|
||||
|
||||
### 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}`. Locally, it may be something like `http://192.168.0.123:9001/{bucket}`.
|
||||
- For DigitalOcean Spaces, it's either the Origin Endpoint or the CDN endpoint of your Spaces Object Storage bucket.
|
||||
- for Supabase, it's `https://{uniqueID}.supabase.co/storage/v1/object/public/{bucket}`. You can retrieve the `uniqueID` from [Storage Settings](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys) page in the Endpoint URL.
|
||||
- For Cloudflare R2, it's `Public R2.dev Bucket URL`.
|
||||
|
||||
</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`.
|
||||
|
||||
For Cloudflare, use `auto`.
|
||||
|
||||
</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 example, locally, it may be something like `http://192.168.0.123:9001`.
|
||||
- For DigitalOcean Spaces, it's the Spaces Origin Endpoint of the format `https://{region}.digitaloceanspaces.com`.
|
||||
- For Supabase, it's the Endpoint URL in the [Storage Settings](https://supabase.com/docs/guides/storage/s3/authentication?queryGroups=language&language=javascript#s3-access-keys).
|
||||
- For Cloudflare, it's `https://{your-account-id}.r2.cloudflarestorage.com`.
|
||||
|
||||
</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 />
|
||||
},
|
||||
{
|
||||
title: "Cloudflare: Checksum error",
|
||||
content: <CloudflareChecksum />
|
||||
}
|
||||
]}
|
||||
/>
|
||||
Reference in New Issue
Block a user