How to set up an AWS S3 bucket for Medusa S3 file plugin.

Medusa requires a file storage plugin to host your store's files like product images. In this tutorial, we'll learn to use AWS S3 as our storage provider by using the medusa-file-s3 plugin.

Prerequisites

To follow along with this tutorial, you need to set up a Medusa server. You can easily set one up by following this quickstart guide from the Medusa docs.

Create an AWS account if you don't already have one.

Create an AWS IAM User and Group

It's a best practice to not use the AWS account root user for any task where it's not required for security reasons.

We need to create an IAM user and user group with AmazonS3FullAccess permission. Follow the steps here to create an IAM admin user and group.

Create new user

Give it Programmatic access and AWS Management Console access, then set a custom password and for simplicity, unselect the required user to create a new password at the next sign-in option. For this tutorial, I named the new user medusa-server-admin.

Create user group

We need to create a user group associated with our newly created user in order to give it permission. Create a new user group and give it AmazonS3FullAccess permission.
For this tutorial, I named the new user group medusa-server-admins

Click Next:Tags > Next:Review > Create User.

Add the newly generated Access key ID and Secret access key to the .env file in the root folder of your Medusa server. For this tutorial, I named the .env keys S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY respectively.

Login as IAM User

To log in to the newly created IAM user, you will need the Account ID of the root user, in addition to the IAM username and password you created earlier. You can get the root user account ID easily by clicking on the username in the top right corner of the AWS console, the account ID will be displayed in the Account ID field.

Sign out of your root AWS account and sign in to the IAM user you just created.

Create S3 Bucket

Go to the AWS S3 console, click on Create bucket

Enter a name for your bucket and select a region. N Virginia and Ohio are typically the cheapest regions. For this guide, I named my bucket medusa-starter-monster-s3 and selected N Virginia as the region.

In the Object Ownership section, select ACLs enabled to enable access to the bucket from your medusa server, then select Bucket owner preferred.

In the Block Public Access section, uncheck the Block all public access checkbox. This will show a warning and a checkbox to confirm your action, check the checkbox.

Scroll to the bottom of the page and click Create bucket.

On the newly created bucket page, click on Permissions and then Bucket Policy. We need to write a policy that allows public read access to the bucket.

You can use the AWS Policy Generator to generate a policy for your bucket. For simplicity, click the Edit button and paste the following policy in the bucket policy field. Replace YOUR_BUCKET_NAME with the name of your bucket. Click Save changes to save the policy.

Add an S3_BUCKET_NAME, S3_BUCKET_REGION, and S3_BUCKET_URL key in the .env file and fill in the values with your bucket name and region and S3 bucket URL. The S3 bucket URL is in the format<https://<YOUR_BUCKET_NAME>.s3>.<REGION>.amazonaws.com. For this tutorial, my S3 bucket URL is<https://medusa-starter-monster-s3.s3.us-east-1.amazonaws.com>.

Install medusa-file-s3

We need to install medusa-file-s3 package in our Medusa server. Navigate to the root of the medusa server and install it.

# using npm
npm install medusa-file-s3

# using yarn
yarn add medusa-file-s3

Finally, add the plugin configs to medusa-config.js file.

const plugins = [
  // other plugins
  {
    resolve: `medusa-file-s3`,
    options: {
      s3_url: process.env.S3_BUCKET_URL,
      bucket: process.env.S3_BUCKET_NAME,
      region: process.env.S3_BUCKET_REGION,
      access_key_id: Sprocess.env.S3_ACCESS_KEY_ID,
      secret_access_key: process.env.S3_SECRET_ACCESS_KEY,
    },
  },
];

module.exports = {
  projectConfig: {
    // project configs
  },
  plugins,
};

Test It Out

Start the medusa server using npm run start or yarn start.

Set up the Medusa Admin if you haven't already. You can follow the quickstart guide to set it up. In the Medusa Admin, add a new product and upload an image for it. If everything is set up correctly, the product image will be uploaded to your S3 bucket successfully.