AWS S3 Setup for WordPress

Add AWS S3 storage integration to a WordPress site on Pantheon.

Contributors: Sarah German.

Discuss in our Forum Discuss in Slack

This section provides information on how to integrate AWS S3 storage with your WordPress Pantheon site.

Amazon Web Services (AWS) offers Simple Storage Service (S3) for scalable storage and content distribution, which can be integrated with sites running on Pantheon. Pantheon already offers content distribution through the Global CDN, but S3 is a good option for addressing issues with highly populated directories or serving large files.

Before You Begin

Be sure that you have:

 Exports

This process uses Terminus commands. Before we begin, set the variable $site in your terminal session to match your site name:

export site=yoursitename
export env=dev

Configure S3 within the AWS Console

You must configure the service within your AWS Management Console before integrating S3 with your site.

Create a New AWS S3 Bucket

If you do not have an existing bucket for your site, create one:

  1. Open your AWS Console and click S3.

  2. Click Create Bucket.

  3. Enter a bucket name. The bucket name you choose must be unique across all existing bucket names in Amazon S3, and after you create a bucket, you cannot change its name. Note that the bucket name you choose is visible in the URL that points to the objects stored in the bucket.

  4. Select a region and click Create.

  5. Configure the Set properties section and click Next when complete. You can configure these options now, or wait and configure later.

  6. Open the Permissions tab, select the boxes for Read and Write access for both Objects and Permissions, then click Next.

  7. Review your settings, and then click Create bucket.

Integrate S3 with WordPress

You must install a plugin such as S3 Uploads or WP Offload Media.

WP Offload Media requires a paid license but is configurable in the WordPress admin UI and offers a number of options and features, including multisite support. S3 Uploads is open-source but does not include an admin UI and requires Terminus and WP-CLI for setup and migration.

Install and Deploy S3 Uploads

 Note

This plugin has known multisite issues. If you need an alternative plugin with premium support and a multisite version, consider WP Offload Media.

  1. Download the latest plugin release from Github and extract it to wp-content/plugins/. Note that our documentation has been tested for version 2.0.0.

     Warning

    Do not add the plugin as a Git submodule. Git submodules are not supported on the platform (more info).

  2. Rename the extracted folder to remove the version number. For example:

    mv S3-Uploads-2.0.0/ S3-Uploads
  3. Create and/or copy your Access Key ID key and Secret Access Key from the My security credentials section of your AWS account to a text editor on your local computer.

     Note

    As a standard security measure, consider creating a unique user with limited permissions covering this S3 bucket to authenticate the plugin.

  4. Add the credentials to wp-config.php, as described in the plugin's README file. For security, we recommend a service like Lockr or the Terminus Secrets plugin to store and retrieve these credentials securely.

  5. Commit and push the new plugin and your wp-config.php updates to the Dev environment, then switch to SFTP mode and activate the plugin:

    terminus wp $site.dev plugin activate S3-Uploads
  6. Use WP-CLI to verify your AWS setup.

    terminus wp $site.dev s3-uploads verify

Migrate existing media with S3 Uploads and WP-CLI

You can migrate existing media files to S3 with the following command:

terminus wp $site.dev -- s3-uploads migrate-attachments

Optionally, add the --delete-local flag to remove the local copies of the media files.

This command will also provide a search/replace command for your database to update references to the newly-migrated files when completed. Note that you must run this on all Pantheon environments (Dev, Test, and Live).

Multisite Compatibility

WP Offload Media plugin is supported.

Refer to the WP Offload Media documentation for more information.

Additional Configuration

Check out the plugin's README file for information on advanced configuration, such as cache control, URL rewriting, and offline development.

Install and Deploy WP Offload Media

Follow documentation from DeliciousBrains. No specialized configuration is required for this plugin to run on Pantheon.

More Resources