Documentation

Quick Start Guide

Introduction

This guide aims to help you start offloading your Media Library to an S3 bucket with WP Offload S3 as quickly as possible. The article covers the following steps:

  1. Create an Amazon Web Services (AWS) User
  2. Saving the AWS User’s access details for WP Offload S3 to use
  3. Update the AWS User’s permissions to allow usage of S3
  4. Configure WP Offload S3 to offload newly uploaded media to an S3 bucket
  5. Offload Your Existing Media Library
  6. Next steps for setting up WP Offload S3 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:

  1. Navigate to the IAM Users page in the AWS Console
  2. Click the Add user button
  3. 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 (-).
  4. Under Access type select the checkbox for Programmatic access.
  5. Click the Next: Permissions button
  6. Click the Next: Review button at the bottom of the page
  7. Click the Create user button (We will set permissions in just a moment)
  8. 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 copy them somewhere safe, or download them as a .csv file. 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.

Define Your Access Keys

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

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

define( 'AS3CF_AWS_ACCESS_KEY_ID', '********************' );
define( 'AS3CF_AWS_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');

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

Alternatively, you can enter your access keys into the form on the Settings tab inside WP Offload S3. This will save them to the database, which is less secure than defining them in your wp-config.php.

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.

Continue with the following steps to grant access for the new user to your bucket.

Grant IAM User Permissions to S3

When you create a new IAM user, by default it has no permissions at all. We need to give our new user access to S3:

  1. Navigate to the IAM Users page in the AWS Console (you now should see a list of all users in your AWS account)
  2. Click on the new user you just created
  3. The Permissions tab should already be active, click + Add inline policy in the lower right of the tab’s content
  4. Select the JSON tab
  5. Copy the policy below and paste it into the editor
  6. Click the Review policy button
  7. Enter a name for the policy (e.g. S3Access)
  8. Click the Create policy button
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:DeleteObject",
                "s3:Put*",
                "s3:Get*",
                "s3:List*"
            ],
            "Resource": [
                "arn:aws:s3:::*"
            ]
        }
    ]
}

This policy allows the user to create buckets, delete files (not buckets), upload files, download files, and list files and buckets. This is the basic level of permissions the plugin requires to function.

Bucket Restrictions

This policy can be further tightened to restrict the user access to a specific bucket. Simply replace the ‘Resource’ section with the following:

"Resource": [
    "arn:aws:s3:::mybucket",
    "arn:aws:s3:::mybucket/*"
]

It’s important to note that if you do restrict access like this, the plugin will give you an Access Denied error when trying to select a bucket. The user does not have permission to list all the buckets in your account. Fortunately you can simply type in the bucket name.

You can read more about IAM policies here and AWS can generate one for you here.

Make Sure Cron is Set Up

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

Configure WP Offload S3

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

Go to WP Offload S3’s settings page in the WordPress admin dashboard, it can be found under the “Settings” menu. If you have followed the steps above then you should see something like the following.

WP Offload S3 What Bucket

If you have already created the S3 bucket you want to offload your media to then you can simply 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 S3 Create Bucket

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

WP Offload S3 Select Bucket

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

WP Offload S3 Bucket Saved

Offload Your Existing Media Library

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

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

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

WP Offload S3 Upload Now

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

WP Offload S3 Upload Remaining Now

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

WP Offload S3 Uploading

The upload progresses in small batches of media to keep things performant. You need to keep the browser window or tab open on that page until the upload to S3 completes.

WP Offload S3 Upload Complete

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

WP Offload S3 100 Percent Uploaded

Using a Content Delivery Network (CDN)

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

http://s3-eu-west-1.amazonaws.com/wicked-awesome-bucket-name/wp-content/uploads/…

Not only is this an ugly URL, but this URL is also bad for SEO. Google likes to see your media on a subdomain of your main domain. Also, 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 S3 bucket as its origin, and shows how to update WP Offload S3’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 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.