DEV Community

Cover image for How to Set up Amazon S3 Upload Provider Plugin for Your Strapi App
Strapi profile image Mark Munyaka
Mark Munyaka for Strapi

Posted on • Originally published at strapi.io

How to Set up Amazon S3 Upload Provider Plugin for Your Strapi App

#aws #strapi #webdev #cms

In this tutorial, I will show you how to set up the Amazon S3 Upload Provider Plugin for your Strapi App.

You will first set up and configure an S3 storage bucket for your app. Then, you'll create a Strapi App. Next, you will install and configure the Amazon S3 Upload Provider Plugin. Finally, you will test the plugin by uploading some images to your Strapi backend.

By the end of this tutorial, you should be able to use the Amazon S3 Upload Provider Plugin with any Strapi project.

What is Strapi?

Strapi is the leading open-source headless Content Management System (CMS). It is 100% Javascript, based on Node.js, and used to build RESTful APIs and GraphQL. It also has a cloud SAAS, ☁ Strapi Cloud ☁ - a fully managed, composable, and collaborative platform to boost your content velocity!

Strapi enables developers to build projects faster by providing a customizable API out of the box and giving them the freedom to use their favorite tools. Content teams use Strapi to autonomously manage all types of content and distribute it from one CMS to any channel be it websites, mobile apps, or connected devices.

A powerful feature of Strapi is its flexibility and extensibility. This is provided through plugins hosted on the Strapi Market. Plugins help add more functionality to your Strapi app. One of such features is uploading your media assets to a cloud provider using the Strapi dashboard.
Sometimes, you may want to host your app's media files in a different location from where your Strapi app is hosted. This is useful to save on storage, memory, and compute resource usage. Also, you can leverage cloud-based solutions like Content Delivery Networks (CDN) and cloud storage buckets for faster and more reliable loading of your media assets.

What is Amazon S3?

Amazon AWS is the biggest cloud provider. It offers Amazon S3, a cloud storage service to host your media assets. Amazon S3 is scalable, reliable, secure, and performant. The Strapi Team built an Amazon S3 Upload Provider Plugin to help with uploading your media assets to your S3 storage bucket.

Prerequisites

To follow along with this tutorial you need the following:

Knowledge Prerequisites:

Software Prerequisites:

  • Operating System (Any of the following are supported):
    • Ubuntu >= 18.04 (LTS-Only)
    • Debian >= 10.x
    • CentOS/RHEL >= 8
    • macOS >= 10.15
    • Windows 10 or 11
    • I used Ubuntu 20.04 LTS for this tutorial.
  • Node v16.x.x or v18.x.x (LTS Only)
  • Odd-number releases of Node are not supported (e.g. v13, v15). Download Node from the Download | Node.js page. I used Node v18.16.0
  • npm or yarn I used npm v8.5.0. npm ships with your Node installation. If you prefer yarn, install it as an npm package. Check Installation | Yarn.
  • Strapi v4.x.x (I used Strapi v4.10.2. You will install Strapi using npm or yarn.)
  • A text editor of your choice
  • Git for Version control [Download Git from the Git - Downloads page]
  • Git Bash (for Windows users)
  • Git Bash ships with your Git download. The tutorial uses Unix shell commands. Git Bash can run UNIX shell commands in Windows.
  • Web Browser (any Chromium-based browser)

Hardware Prerequisites

  • At least 1 CPU core (Highly recommended at least 2)
  • At least 2GB of RAM (Moderately recommended 4)
  • Minimum required storage space recommended by your OS or 32 GB of free space

Additional Prerequisites

You will also need an AWS Account. A credit card is required to open one. AWS offers a 12-month free trial to test out the Amazon S3 bucket with 5GB of free storage.

Set up Strapi

We will start off by creating a Strapi app.

NOTE: If you prefer testing the ready-made app, you can clone the Github repo.

  • Open up your terminal and navigate to your home folder. 
cd $HOME
Enter fullscreen mode Exit fullscreen mode
  • Create a directory to store your project, name it strapi-aws-s3. 
mkdir strapi-aws-s3
Enter fullscreen mode Exit fullscreen mode
  • Change the directory to the newly created directory, strapi-aws-s3. 
cd strapi-aws-s3
Enter fullscreen mode Exit fullscreen mode
  • Create your Strapi app. 
npx create-strapi-app backend --quickstart
Enter fullscreen mode Exit fullscreen mode

OR

yarn create strapi-app backend --quickstart
Enter fullscreen mode Exit fullscreen mode

This command creates your Strapi app in the folder named backend. The --quickstart flag sets up your Strapi app with an SQLite database.

Your folder structure in strapi-aws-s3 after installing Strapi should look similar to this:

.
├── backend
│   ├── build
│   ├── .cache
│   ├── config
│   ├── data
│   ├── database
│   ├── .editorconfig
│   ├── .env
│   ├── .env.example
│   ├── .eslintignore
│   ├── .eslintrc
│   ├── favicon.ico
│   ├── .gitignore
│   ├── node_modules
│   ├── package.json
│   ├── public
│   ├── README.md
│   ├── src
│   ├── .strapi-updater.json
│   ├── .tmp
│   └── yarn.lock
├── .git
├── LICENSE
└── README.md
Enter fullscreen mode Exit fullscreen mode

After installation, your app should start automatically. Visit http://localhost:1337/admin in your browser and register your details in the Strapi Admin Registration Form.

Strapi Admin Registration

NOTE: If Strapi did not start automatically, run these commands:

cd backend
npm run develop
Enter fullscreen mode Exit fullscreen mode

OR

cd backend
yarn develop
Enter fullscreen mode Exit fullscreen mode

npm run develop starts your Strapi project development server in watch mode. Watch mode changes in your Strapi project will trigger a server restart.

Creating a new user logs you into the Strapi Dashboard.

Strapi Dashboard

The left-hand side of the Strapi dashboard lists the Content Manager containing your content types. The PLUGINS option lists the plugins installed in your project. Content-Type Builder Plugin and Media Library Plugin are installed by default in your Strapi app.

Media Library Upload Plugin

The Media Library Plugin is what you will use to upload images to your Amazon S3 bucket. If the Amazon S3 Upload Provider Plugin is working, images you upload in the Media Library should appear in your S3 bucket automatically.

Install and Configure '@strapi/provider-upload-aws-s3' Plugin

Install AWS S3 Provider

Stop your strapi server by pressing Ctrl+C in your terminal. Install @strapi/provider-upload-aws-s3:

cd backend
npm install @strapi/provider-upload-aws-s3 --save
Enter fullscreen mode Exit fullscreen mode

OR

cd backend
yarn add @strapi/provider-upload-aws-s3
Enter fullscreen mode Exit fullscreen mode

Configure AWS S3 Provider

Create a file named plugins.js in your config folder

touch config/plugins.js
Enter fullscreen mode Exit fullscreen mode

Add this configuration code to plugins.js:

// ~/strapi-aws-s3/backend/config/plugins.js

module.exports = ({ env }) => ({
      upload: {
        config: {
          provider: 'aws-s3',
          providerOptions: {
            accessKeyId: env('AWS_ACCESS_KEY_ID'),
            secretAccessKey: env('AWS_ACCESS_SECRET'),
            region: env('AWS_REGION'),
            params: {
              ACL: env('AWS_ACL', 'public-read'),
              signedUrlExpires: env('AWS_SIGNED_URL_EXPIRES', 15 * 60),
              Bucket: env('AWS_BUCKET'),
            },
          },
          actionOptions: {
            upload: {},
            uploadStream: {},
            delete: {},
          },
        },
      },
});
Enter fullscreen mode Exit fullscreen mode

This enables the plugin to work in your app.

AWS_ACCESS_KEY_ID, AWS_ACCESS_SECRET, AWS_REGION, and AWS_BUCKET are environment variables. You will later assign their values in the .env file for your Strapi project after setting up the Amazon S3 bucket.

Security Middleware Configuration

Due to the default settings in the Strapi Security Middleware, you will need to modify the contentSecurityPolicy settings to properly see thumbnail previews in the Media Library. You should replace strapi::security string with the object below instead as explained in the middleware configuration documentation.

Edit the middlewares.js file in your config folder:

// ~/strapi-aws-s3/backend/config/middlewares.js

module.exports = [
  'strapi::errors',
  /* Replace 'strapi::security', with this snippet */
  /* Beginning of snippet */
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'",
            'data:',
            'blob:',
            'dl.airtable.com',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'dl.airtable.com',
            'yourBucketName.s3.yourRegion.amazonaws.com',
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  /* End of snippet */
  'strapi::cors',
  'strapi::poweredBy',
  'strapi::logger',
  'strapi::query',
  'strapi::body',
  'strapi::session',
  'strapi::favicon',
  'strapi::public',
];
Enter fullscreen mode Exit fullscreen mode

Later you will replace 'yourBucketName.s3.yourRegion.amazonaws.com' with the link to your S3 bucket. Refer to AWS S3 | Strapi Market for more information on configuring the plugin.

Set up AWS

The next step here is to set up AWS as part of our project.

Create AWS Account

Sign up for an AWS account on the AWS Console - Signup page if you don’t have one already. Refer to the Create and activate an AWS account guide for additional information related to the AWS account creation process.

Create Administrator IAM Admin User and Group**

Best practices for using AWS Amazon services state to not use your root account user and to use instead the IAM (AWS Identity and Access Management) service. Your root user is therefore only used for a very few select tasks. For example, for billing, you create an Administrator user and Group for such things. Other routine tasks can also be done with a regular IAM User.

Follow the “Creating your first IAM admin user and user group - AWS Identity and Access Management” guide to create an IAM admin user and user group using your AWS root account in the AWS Management Console.

Create an IAM User for your Strapi App

Set User Details:

  • Sign out of your root user account and sign in to your Administrator user account you just created.
    Sign in as IAM Administrator user

  • Visit the IAM Console by selecting Services then All services, scroll down and select IAM or go here to IAM Console.
    Go to IAM Console

  • Click on Users in the left-hand menu and select Add User.
    Select Add users in Users IAM Console

  • Provide a Username. I used Strapi-Admin.

  • Access Type: Check both Programmatic access and AWS Management Console access.

  • Autogenerate a password or click Custom password and provide one.

  • OPTIONAL: For simplicity, uncheck the Require password reset.

  • Click Next: Permissions.
    Set user details for Strapi Admin

Set up Permissions for Amazon S3

Create Group

Follow the steps below to set up permissions for Amazon S3.

  • Click Create group and name it. Then, choose appropriate policies under Policy Name:
    • Search for s3 and check AmazonS3FullAccess.
    • Click Create group.
  • Click to Add user to group and check the Developers group to add the new user.

  • Click Next: Tags.

    Enable Access to Amazon S3

  • Click Add user to group and check the Developers group to add the new user.

    Check newly added user group

Add Tags

This step is optional and based on your workflow and project scope. To begin, click Next: Review.

Retrieve Credentials 'Access Key ID' and 'Secret Access Key'**

Review the information and ensure it is correct. Use Previous to correct anything. If satisfied, click Create user.

Review User Information

If you do not do these steps, must reset your Access key ID and Secret access key later.

Download the .csv file and store it in a safe place. This contains the username, login link, access key ID and secret access key.

You can decide to keep these details in your password manager.

Retrieve User Credentials

  • Click on the AWS Management Console Access sign-in link. This will log you out of Administrator.

For more information, check out creating a regular user for the creation and management of your Strapi project.

Create Amazon S3 Storage Bucket

Log into your AWS Management Console as the new user you just created Strapi-Admin.

Sign in as Strapi-Admin IAM user

Go to Services, click All services, scroll down, and select S3 Scalable Storage in the Cloud to open up the Amazon S3 Console.

Select S3 in Services Menu

Click on Create bucket in the Amazon S3 console.

Create bucket

Give your bucket a unique name. I named mine strapi-aws-s3-images-bucket. Select the most appropriate region for your bucket.

Name your bucket

For