How to create an Amazon S3 Filesystem in Craft CMS

A flower that represents Craft CMS with the text "Filesystem" beneath it.

A step by step guide on creating an Amazon S3 Filesystem in Craft CMS.

We recommend checking out the main branch of our open source Craft CMS starter project and following the steps below.

git clone git@github.com:delasign/craft-cms-starter.git

Step One: Go to the Plugin Store

A screenshot of Craft CMS with "Plugin Store" highlighted on the left menu side bar. Press that tab and move on to the next step.

On the left menu side bar, select the Plugin Store tab.

Step Two: Navigate to Amazon S3

A screenshot of the Craft CMS Plugin store with "aws" in the search box. Highlighted on the results grid is "Amazon S3". Select that tile and move on to the next step.

In the Plugin Store, use the search bar to find the Amazon S3 plugin. When it appears, select it.

Step Three: Install Amazon S3

A screenshot of the Amazon S3 plugin in the Craft CMS Plugin Store. Highlighted is the "install" button. Press it and move on to the next step.

In the page that appears, press Install.

This will trigger a process that installs the package through Composer.

A screenshot of what Craft CMS looks like when you are installing a plugin.

Step Four: Add the Environment Variables

A screenshot of VSCode showing the .env file of the Craft CMS.

In your Craft CMS project, in the .env file, add the following AWS variables:

AWS_MEDIALIBRARY_PREFIX - The prefix for the folder that holds all your assets in AWS.
AWS_ACCESS_KEY - The AWS Access Key.
AWS_SECRET_ACCESS_KEY - The AWS Secret Key that allows access to your AWS.

Optionally, if you use a cloudfront:

AWS_CLOUDFRONT_DISTRIBUTION - The cloud front distribution.
AWS_CLOUDFRONT_INVALIDATION - The invalidation path.

Step Five: Restart your server

A screenshot of Terminal showing you how to restart your server using DDEV.

If you're using DDEV, run ddev stop followed by ddev start, in Terminal with the current directory set to that of your Craft CMS project.

This is required so that the environment variables are registered.

Step Five: Select Settings

A screenshot of the Craft CMS plugin store with a highlight on the Settings tab on the left menu sidebar. Press this tab and move on to the next step.

In the left menu side bar of the Craft CMS project, press the Settings tab.

Step Six: Select Filesystems

A screenshot of the Craft CMS settings page with a highlight on the Filesystems tile. Press this tile and move onto the next step.

In the Settings page, select the Filesystems tile under Media.

Step Seven: + New filesystem

A screenshot of the Filesystems Craft CMS page with a highlight on the "+ New Filesystem" button on the top right. Press this button and move on to the next step.

In the Filesystems page, press the + New filesystem button.

Step Eight: Set Amazon S3 Filesystem type

A screenshot of the Create a new Filesystem page in Craft CMS. Highlighted is the open dropdown below Filesystem type demonstrating that you can select Amazon S3. Select Amazon S3 and move on to the next step.

In the Create a new filesystem page, in the Filesystem type dropdown select Amazon S3.

Step Nine: Fill in details

A screenshot of the Create a new Filesystem Craft CMS page with the details filled in for the AWS S3. Particularly important is that you give it a name, handle as well as add the Base Url, Access Key Id and Secret Key.

Fill in the details for your filesystem, using the environment variables where possible.

Please note the Subfolder input is used in the event you want all of the assets in that asset volume to be added to a specific folder within your bucket.

Please note that we recommend that you also set cache duration to 3156000 seconds (Not Shown).

Step Ten: Press Refresh

A screenshot of the Create a new Filesystem page in Craft CMS, with a highlight on the Refresh button under Bucket. Press Refresh and move on to the next step.

Once you have added the Access Key ID and the Secret Access Key, press the Refresh button under Bucket*.

This will load the buckets available to those keys.

Step Eleven: Set Bucket & Save

A screenshot of the Create a new Filesystem Craft CMS page with a highlight on the selected bucket, which is left of the Refresh Button in the former step. We have also highlighted the save button on the top right. Once you have picked the right bucket, press the Save button and move on to the next step.

Names of all the buckets available to your keys should appear next to the Choose... dropdown.

Select the bucket you wish to save assets to and when you're ready, press Save.

Any Questions?

We are actively looking for feedback on how to improve this resource. Please send us a note to inquiries@delasign.com with any thoughts or feedback you may have.