Amazon S3 Quick Start Guide


This guide aims to help you start offloading your WordPress Media Library to an Amazon S3 bucket with WP Offload Media as quickly as possible.

We also have Quick Start Guides for other storage providers.

This article covers the following steps:

  1. Login to the AWS Console
  2. Create an Amazon Web Services (AWS) User
  3. Saving the AWS User’s access details for WP Offload Media to use
  4. Activate Your WP Offload Media License
  5. Configure WP Offload Media to offload newly uploaded media to an Amazon S3 bucket
  6. Offload Your Existing Media Library
  7. Next steps for setting up WP Offload Media to use a CDN

Login to the AWS Console

Already have an Amazon Web Services (AWS) account? Sign in here.

If you don’t have an AWS account yet, you will need to sign up here.

Create an IAM User

Once you have logged into the console, you will need to create a new IAM user:

Navigate to the IAM Users page in the AWS Console, click the Add user button.

Enter a name for the user in the User name field.

Names are case insensitive and must be unique within your AWS account. User names can be a combination of up to 64 letters, digits, and these characters: plus (+), equal (=), comma (,), period (.), at sign (@), and hyphen (-).

Under Access type select the checkbox for Programmatic access, then click the Next: Permissions button.

IAM Management Console - Add User - Set user name

To allow the new user to manage buckets and objects in the S3 service, you need to grant it specific permissions.

Click the “Attach existing policies directly” button, and then enter “s3” in the filter policies input box.

Select the “AmazonS3FullAccess” policy, then click the Next: Review button at the bottom of the page.

IAM Management Console - Add User - Attach Permissions

If everything looks good, click the Create user button.

IAM Management Console - Add User - Review

You will be shown the security credentials for the user, which consists of an Access Key ID and a Secret Access Key. Amazon will not show these again so please download them as a .csv and also copy them somewhere safe. If you lose them, you can always create a new set of keys from the console but you cannot retrieve the secret key again later.

IAM Management Console - Add User - Complete

Define Your Access Keys

Now that you have your AWS Access Keys, you need to add them to your site so that WP Offload Media can use them to work with the Amazon S3 service.

For better security, we recommend defining your access keys in your wp-config.php:

define( 'AS3CF_SETTINGS', serialize( array(
    'provider' => 'aws',
    'access-key-id' => '********************',
    'secret-access-key' => '**************************************',
) ) );

These should be placed before the following block of code in your wp-config.php:

/* That's all, stop editing! Happy blogging. */

/** Absolute path to the WordPress directory. */
if ( !defined('ABSPATH') )
    define('ABSPATH', dirname(__FILE__) . '/');

/** Sets up WordPress vars and included files. */
require_once(ABSPATH . 'wp-settings.php');

Warning: If you define your access keys after this block of code, WP Offload Media will not be able to read them.

Alternatively, you can enter your access keys into the form on the Storage Provider page inside WP Offload Media, the first page shown when no keys are defined. This will save them to the database, which is less secure than defining them in your wp-config.php.

WP Offload Media Save Amazon S3 Keys In Database

IAM Roles

If you’re running your site on an Amazon EC2 instance, you might like to use an IAM Role instead. This is even more secure than defining your access keys in wp-config.php.

Make Sure Cron Is Set Up

We highly recommend that you configure a proper cron job on your server as WP Offload Media relies heavily on background processing. See our Cron Setup doc for details on how to accomplish this.

Activate Your WP Offload Media License

Now’s a good time to activate your WP Offload Media license so that (once configured) you can instantly take advantage of all its goodies.

Go to WP Offload Media’s settings page in the WordPress admin dashboard, found under the “Settings” menu.

Then click on the “License” tab, enter your license key in the input box, and click the “Activate License” button.

WP Offload Media - Enter License

Configure WP Offload Media

To start offloading newly uploaded media to Amazon S3 you need to first tell WP Offload Media which bucket it should use. If you have not already created a bucket to use with WP Offload Media, it can be created for you from WP Offload Media’s Settings page.

Go to the “Media Library” tab of WP Offload Media’s Settings page in the WordPress admin dashboard. If you have followed the steps above then you should see something like the following.

WP Offload Media What Bucket - S3

If you have already created the bucket you want to offload your media to, then you can enter the bucket name in the above input and click the “Save Bucket” button.

If you haven’t created the bucket yet, then you can click the “Create new bucket” link to get a form where you can specify the new bucket’s name and region.

WP Offload Media Create Bucket - S3

As long as you haven’t restricted your IAM User’s access to list buckets then you can also “Browse existing buckets.”

WP Offload Media Select Bucket - S3

Regardless of how you specify the bucket, once saved, WP Offload Media will be set up to offload newly-uploaded media to the bucket with some recommended default settings.

WP Offload Media Bucket Saved - S3

Access Denied to Bucket

If you see an “Access Denied to Bucket” error notice after selecting a bucket created in the AWS Console, the chances are you have “Public Access Settings” enabled for the bucket. You can tell by selecting the bucket in the AWS Console’s list of buckets and looking at the “Public access settings” option within the “Permissions” section of the pop-over panel.

Public Access Settings In Bucket Permissions

WP Offload Media needs to be able to make objects in the bucket public readable (not editable) so that your site visitors can see them, this is safe to do as it is on a per object basis and is different from making the bucket public. Even if you’re only going to use WP Offload Media to offload “private” objects for WooCommerce, Easy Digital Downloads or similar, it still needs to be able to change the permissions on individual objects in the bucket.

If “Public access settings” does not say “Disabled“, click the “Permissions” section link in the pop-over panel and click “Edit”.

Edit public access settings

Uncheck all of the settings and save the changes, you’ll need to confirm the change if asked.

Uncheck and save public access settings

Refresh WP Offload Media’s settings page and the “Access Denied to Bucket” error should disappear.

IMPORTANT: There is also a Block public access (account settings) page that can be accessed from the Amazon S3 sidebar that can also be used to disable public access to objects in all existing and new buckets. If the AWS account is relatively new, or someone has visited this settings page and turned on the blocking of public access, you may need to visit the page, click “Edit”, clear the “Block all public access” checkbox, and then save the changes.

Offload Your Existing Media Library

Now that your site is configured to offload newly-uploaded media to Amazon S3, you might want to offload any existing media to the bucket too.

In the right-hand sidebar of WP Offload Media’s “Media Library” tab you should see what we call the “Offload Tool”, this can be used to offload existing media to the bucket.

If you have not offloaded anything yet, then you’ll see a “Your Media Library needs to be offloaded” message in the Offload Tool with an “Offload Now” button.

WP Offload Media Offload Now

If you have already offloaded a few items, then you might see a message like “66% of your Media Library has been offloaded” in the Offload Tool, with an “Offload Remaining Now” button.

WP Offload Media Offload Remaining

Either way, clicking the Offload Tool’s button will start an upload to the bucket of all existing media yet to be offloaded.

WP Offload Media background offload in progress

The media offload progresses in small batches in the background to keep things efficient. You can close the tab and just forget about it, when the tool finishes its job, you’ll get a notice in the WordPress dashboard, or you can monitor progress from WP Offload Media’s settings page.

Once complete, the Offload Tool displays a “100% of your Media Library has been offloaded, congratulations!” message and the “Download all files from bucket to server” and “Remove all files from bucket” tools are made available.

WP Offload Media Offload 100 Percent

Next Steps: Using a Content Delivery Network (CDN)

Now that your media is offloaded to Amazon S3, your next step if you’re concerned about performance (i.e. load time and SEO), is to configure a Content Delivery Network (CDN).

By default WP Offload Media is configured to use raw Amazon S3 URLs when serving offloaded media. Your media URLs might look something like this:…

Not only is this an ugly URL, but this URL is also bad for SEO as Google likes to see your media on your own domain. Also, Amazon S3 is primarily a storage platform and is not optimized for high speed delivery of media. Faster media is obviously better for user experience but also better for SEO. For these reasons, we strongly recommend configuring CloudFront or another CDN for delivering your media. For more details about the benefits of CloudFront and other CDNs, please read our Why Use a CDN? doc.

We have two guides for setting up CloudFront as your CDN. The first you should follow is our CloudFront Setup guide. It gets you up and running with CloudFront properly configured to use your Amazon S3 bucket as its origin, and shows how to update WP Offload Media’s settings to use it.

The second guide builds on the first, showing how to Configure a Custom Domain For CloudFront With HTTPS. This allows you to switch from serving your media from a default CloudFront domain to using a subdomain of your site’s domain.

If you’re planning to set up the Assets Pull addon as well, you will most likely want to use the same domain name for both your media and assets with CloudFront. Check out our guide to accomplish that.

If you don’t want to use CloudFront for your CDN, you can also use any other CDN. We have a guide for setting up MaxCDN as well as Cloudflare.