medusa-store/www/apps/resources/app/architectural-modules/file/s3/page.mdx

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>
    <TabsTrigger value="supabase">Supabase S3 Storage</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>
    <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>
  </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>

```js title="medusa-config.js"
const { Modules } = require("@medusajs/framework/utils")

// ...

module.exports = {
  // ...
  modules: {
    // ...
    [Modules.FILE]: {
      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...
            },
          },
        ],
      },
    },
  },
}
```

### 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.
      - 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.
      
      </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.
      - 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).
      
      </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>

## 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:

```js title="medusa-config.js"
module.exports = defineConfig({
  // ...
  modules: {
    [Modules.FILE]: {
      resolve: "@medusajs/medusa/file",
      options: {
        providers: [
          {
            resolve: "@medusajs/medusa/file-s3",
            id: "s3",
            options: {
              // ...
              additional_client_config: {
                forcePathStyle: true,
              },
            },
          },
        ],
      },
    },
  },
})
```
---


## Troubleshooting

<DetailsList
  sections={[
    {
      title: "AWS: The bucket does not allow ACLs (Enabling public access to bucket)",
      content: <S3BucketAcl />
    }
  ]}
/>