Last Reviewed: May 19, 2023

AWS S3 Setup for WordPress

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

Edit this page on GitHub Report an issue with this doc

This section provides information on how to integrate Amazon Web Services (AWS) S3 storage with your WordPress Pantheon site.

AWS offers Simple Storage Service (S3) for scalable storage and content distribution that you can integrate with sites running on Pantheon. Pantheon already offers content distribution through our 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:

An existing WordPress site on Pantheon, or create a site.
A local clone of your code repository.
An account with Amazon Web Services (AWS). Amazon offers free access to most of their services for the first year.
Terminus installed on your local computer.

Exports

This process uses Terminus commands. Set the variable $site in your terminal session to match your site name before you begin:

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 Pantheon site.

Create a New AWS S3 Bucket

Open your AWS Console and click S3.
Click Create Bucket.
Enter a bucket name and then select an AWS Region. The bucket name you choose must be unique across all existing bucket names in Amazon S3. You cannot change the name after you create a bucket. Note that the bucket name you choose is visible in the URL that points to the objects stored in the bucket.
Select ACLs enabled and set Object Ownership to Bucket owner preferred in the Object Ownership section.
Uncheck the Block all public access in the Block Public Access settings for this bucket section and then select the checkbox to acknowledge turning off this setting when prompted.
Leave all other settings to default and then click Create bucket.

Configure your AWS Access

Open your Identity and Access Management (IAM) dashboard, select Access Management, select Policies, and then click the Create policy button.

Select JSON and paste the code below under the Policy editor, then change the bucketname to the name you specified in the Create a New AWS S3 Bucket section, and then click Next.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "ObjectLevel",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::bucketname/*"
    },
    {
      "Sid": "BucketLevel",
      "Effect": "Allow",
      "Action": [
        "s3:GetBucketPublicAccessBlock",
        "s3:GetBucketOwnershipControls",
        "s3:ListBucket",
        "s3:GetBucketLocation"
      ],
      "Resource": "arn:aws:s3:::bucketname"
    }
  ]
}

Create AWS S3 access step 2

Enter your policy name in the Policy name field (for example, Pantheons3Access) and then click Create Policy.
Go back to Access Management in the IAM dashboard, select Users, and then click Add users to create a user based on the policy you created.
Enter a name for your user in the User name field (for example, S3-user), and then click Next.
Select Attach policies directly in the Permissions options section, locate the policy that you created in the above steps, and then click Next.
Info:
Note
Steps 1-3 create a custom AWS User policy with read and write permissions to the specific bucket assigned to your site. You can select the AmazonS3FullAccess policy to replace the custom policy that you created if you require higher permissions.
Review the configuration and click Create user. This creates a user profile without programmatic access.
Open your user profile, select the Security credentials tab, and click the Create access key in the Access Keys section.
Select the Application running outside AWS option and click Next.
Set the optional tags if desired and then click Create Access key to finalize the access. Be sure to note the Access Key and Secret Access Key and store them securely.

Integrate S3 with WordPress

You must install a plugin such as S3 Uploads or WP Offload Media to integrate S3 with WordPress.

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 Plugin

Note

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

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:
Warning
Do not add the plugin as a Git submodule. Git submodules are not supported on the platform. Refer to the Git guide for more information.
Rename the extracted folder to remove the version number. For example:
```
mv S3-Uploads-2.0.0/ S3-Uploads
```
Create and/or copy your Access Key ID and Secret Access Key from the My security credentials section of your AWS account to a text editor on your local computer.
Info:
Note
Consider creating a unique user with limited permissions covering this S3 bucket to authenticate the plugin as a standard security measure.
Add the credentials to wp-config.php, as described in the plugin's README file. For increased security, we recommend a service like Lockr or the Terminus Secrets plugin to store and retrieve these credentials securely. Refer to Secret Management Techniques for more secure methods to store your keys.
Commit and push the new plugin and your wp-config.php file updates to the Dev environment, then switch to SFTP mode and activate the plugin:
```
terminus wp $site.dev plugin activate S3-Uploads
```
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.

URL Rewriting

URLs saved in the database use S3's provided URL (for example, https://bucketname.s3.amazonaws.com/uploads/2023/01/image.jpg) by default. You can use Advanced Global CDN to mask the URLs to match your site's domain for SEO purposes. Contact sales if you do not have AGCDN or open a support ticket to request help with Domain Masking if you have AGCDN.

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 to install and deploy WP Offload Media. No specialized configuration is required for this plugin to run on Pantheon.