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

Author: Mark Munyaka

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 using one of the starters provided by the Strapi Team. 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.

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 you can use 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:

A. Knowledge Prerequisites:

• Javascript
• Node.js
• Shell (Bash)
• Strapi, follow the Quick Start Guide to familiarize yourself with Strapi.
• Git

B. Software Prerequisites:

• Operating System (Any of the following are supported):

  • Ubuntu >= 18.04 (LTS-Only)
  • Debian >= 9.x
  • CentOS/RHEL >= 8
  • macOS Mojave or newer (ARM not supported)
  • Windows 10 or 11
  • Docker - docker repo I used Ubuntu 20.04 LTS for this tutorial.

• Node v14.x.x or v16.x.x Odd-number releases of Node are not supported (e.g. v13, v15). Download Node from the Download | Node.js page. I used Node v16.14.2.

• 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.3.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 using one of the templates provided by the Strapi Team.

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

We will use the blog template. The template is installed using npm.

1. Open up your terminal and navigate to your home folder.

    $ cd ~

1. Create a directory to store your project, name it strapi-aws-s3.

    ~$ mkdir strapi-aws-s3

1. Change the directory to the newly created directory, strapi-aws-s3.

    ~$ cd strapi-aws-s3

1. Enable source control for your project by initializing a git repository.

    ~/strapi-aws-s3 $ git init

1. Create your Strapi app using the blog template.

    ~/strapi-aws-s3 $ npx create-strapi-app backend --quickstart --template @strapi/template-blog@1.0.0 blog

    # OR

    ~/strapi-aws-s3 $ yarn create strapi-app backend --quickstart --template @strapi/template-blog@1.0.0 blog

This command creates your Strapi app in the folder named backend. The --quickstart flag sets up your Strapi app with an SQLite database. The --template flag retrieves the specific template to install in your app. In this case, we retrieved the template-blog version 1.0.0, hosted by strapi on GitHub.

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

    ~/strapi-aws-s3 $ tree -L 2 -a
    .
    ├── 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

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

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

    ~/strapi-aws-s3 $ cd backend

    ~/strapi-aws-s3/backend $ npm run develop 
    # OR
    ~/strapi-aws-s3/backend $ yarn develop

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.

The blog template for our Strapi project comes preloaded with the following:

• Content-Type Builder Plugin
  • 4 Collection types (Article, Category, User and Writer)
  • 2 Single types (Global and Homepage)
  • 2 Components (Sections and Shared)
• Media Library Plugin
  • 10 image assets
• User-Permissions Plugin (Public Roles)
  • The permissions for the Collection-types and Single-types are already configured to allow READ access to any Public unauthenticated user.

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. Select Media Library to see the image assets loaded with the blog template.

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 '@strapi/provider-upload-aws-s3' Plugin

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

    ~/strapi-aws-s3/backend $ npm install @strapi/provider-upload-aws-s3 --save
    # OR
    ~/strapi-aws-s3/backend $ yarn add @strapi/provider-upload-aws-s3

Configure Plugin

A. Provider Configuration

Create a file named plugins.js in your config folder

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

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: {
              Bucket: env('AWS_BUCKET'),
            },
          },
          actionOptions: {
            upload: {},
            uploadStream: {},
            delete: {},
          },
        },
      },
    });

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.

B. 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',
    ];

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

A. Set User Details:

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

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

• Click on Users in the left-hand menu and select Add User.

• 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 up Permissions for Amazon S3

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.

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

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'

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

B. Take note of the credentials related to your account: If you do not do these steps, you will have to 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.

• 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.

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

Click on Create bucket in the Amazon S3 console.

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

For Object Ownership, select ACLs enabled to enable access to the S3 bucket from your Strapi backend. Select Bucket owner preferred for the plugin to work.

Under Block Public Access settings for this bucket, do the following:

• Uncheck Block all public access and set the permissions as follows:
  • Uncheck Block public access to buckets and objects granted through new access control lists (ACLs) (Recommended)
  • Uncheck Block public access to buckets and objects granted through any access control lists (ACLs)
  • Check Block public access to buckets and objects granted through new public bucket policies
  • Check Block public and cross-account access to buckets and objects through any public bucket policies
• Check I acknowledge that the current settings might result in this bucket and the objects within becoming public under the Turning off block all public access might result in this bucket and the objects within becoming public warning.

Leave the rest of the settings as is and click Create bucket. Your new bucket should now be listed in the Amazon S3 Console.

Test Demo App

The next stage involves testing the demo app.

Update Strapi Backend

Update your Strapi backend with new credentials from your newly created S3 bucket. Update .env with the following:

    /* ~/strapi-aws-s3/backend/.env */
    /* Add this after the last line */

    AWS_ACCESS_KEY_ID=<Access Key ID>
    AWS_ACCESS_SECRET=<Secret access key>
    AWS_REGION=eu-west-2
    AWS_BUCKET=strapi-aws-s3-images-bucket

NOTE: Replace and with the credentials in the .csv file you downloaded after creating an IAM role for your S3 bucket. For AWS_REGION input the region where your bucket is hosted. My bucket is hosted at eu-west-2.

Update the middlewares.js file in your config folder by replacing yourBucketName.s3.yourRegion.amazonaws.com with the link to your S3 bucket. In my case the link becomes strapi-aws-s3-images-bucket.s3.eu-west-2.amazonaws.com like so:

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

    module.exports = [
      'strapi::errors',
      {
        name: 'strapi::security',
        config: {
          contentSecurityPolicy: {
            useDefaults: true,
            directives: {
              'connect-src': ["'self'", 'https:'],
              'img-src': [
                "'self'",
                'data:',
                'blob:',
                'dl.airtable.com',
                'strapi-aws-s3-images-bucket.s3.eu-west-2.amazonaws.com', // change here
              ],
              'media-src': [
                "'self'",
                'data:',
                'blob:',
                'dl.airtable.com',
                'strapi-aws-s3-images-bucket.s3.eu-west-2.amazonaws.com', // change here
              ],
              upgradeInsecureRequests: null,
            },
          },
        },
      },
      'strapi::cors',
      'strapi::poweredBy',
      'strapi::logger',
      'strapi::query',
      'strapi::body',
      'strapi::session',
      'strapi::favicon',
      'strapi::public',
    ];

Build your backend and start your server.

    ~/strapi-aws-s3/backend $ npm run build
    ~/strapi-aws-s3/backend $ npm run develop

    #OR

    ~/strapi-aws-s3/backend $ yarn build
    ~/strapi-aws-s3/backend $ yarn develop

Upload An Image

Visit the Media Library plugin page, localhost:1337/admin/plugins/upload. Click + Add new assets. Browse for an image you want to add from your computer and select Upload 1 asset to the library and watch the magic happen.

In a few moments, you should see your newly uploaded image in your Media Library as well as your Amazon S3 Bucket.

Visit s3.console.aws.amazon.com/s3/buckets?region= to see the newly uploaded image in your S3 bucket.

Delete an Image

Delete the image from the Media Library. The image is automatically deleted form the Amazon S3 bucket.

Confirm the deletion by refreshing the link to your bucket. The bucket is now empty. Deleting the image from the Strapi Admin Dashboard worked.

You have successfully set up the Amazon S3 Upload Provider Plugin.

Conclusion

In this tutorial, we created a Strapi project from a blog template. With just one command, our backend was already set as a REST API endpoint.

We installed and configured the AWS S3 provider for Strapi uploads (@strapi/provider-upload-aws-s3) plugin in our Strapi project folder. Then, we created an Amazon S3 bucket with the recommended IAM policies to manage it.

Finally, we tested our app and saw the ease with which we can upload and delete images in the Amazon S3 bucket using the Strapi Admin Media Library. Check out the Github project repo.

What Next?

Check out Deploying Strapi to your own VPS and other deployment options to see how you can deploy your app. If you are interested in building a frontend for this app checkout Build a blog with Next (React.js) and Strapi.

I hope this tutorial has provided enough information and insight to help you set up the Amazon S3 provider with full confidence. If you have any issues, feel free to comment. The Strapi community is always available for any issues.