Documentation / Administrator Guide / Deployment / Amazon S3 (or compatible)

Amazon S3 (or compatible)

Introduction

Amazon Web Services (AWS) is a subsidiary of Amazon providing on-demand cloud computing platforms and APIs to individuals, companies, and governments, on a metered pay-as-you-go basis.

The Amazon S3 (or compatible) deployment method allows you to deploy your static site to Amazon S3, or any S3-compatible provider, optionally accelerated by Amazon CloudFront.

This deployment method supports the following features:

  • Deployment to an Amazon S3 bucket or Amazon S3-compatible bucket;
  • Caching and HTTPS termination using Amazon CloudFront;
  • Direct authentication as well as authentication using profiles;
  • Support for HTTP redirects (limited to 301);
  • Support for custom HTTP headers;
  • Support for custom error page;
  • Exclusion of specific pre-existing files in the target bucket;
  • CloudFront cache invalidation.

Preparation

In order to use this deployment method you will need to create an Amazon S3 bucket, or an Amazon S3-compatible bucket with an alternative provider, to store the static version of your site. Optionally you may choose to create an Amazon CloudFront Distribution in order to serve your static site over HTTPS, which is highly recommended.

These instructions apply to the creation of a regular Amazon S3 bucket.

Amazon S3

Note: these instructions are based on the official Configuring a static website walkthrough.

Step 1: Create a bucket

The following instructions provide an overview of how to create your buckets for website hosting. For detailed, step-by-step instructions on creating a bucket, see How Do I Create an S3 Bucket? in the Amazon Simple Storage Service Console User Guide.

To create a bucket

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.
  2. Choose Create bucket.
  3. Enter the Bucket name (for example, example.com).

  4. Choose the Region where you want to create the bucket.

    Choose a Region close to you to minimize latency and costs, or to address regulatory requirements. The Region that you choose determines your Amazon S3 website endpoint. For more information, see Website endpoints.

  5. To accept the default settings and create the bucket, choose Create.

Step 2: Enable static website hosting

After you create a bucket, you can enable static website hosting for your bucket. You can create a new bucket or use an existing bucket.

To enable static website hosting

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.
  2. In the Buckets list, choose the name of the bucket that you want to enable static website hosting for.
  3. Choose Properties.
  4. Under Static website hosting, choose Edit.
  5. Choose Use this bucket to host a website.
  6. Under Static website hosting, choose Enable.

  7. In Index document, enter index.html.

    The index document name is case sensitive and must exactly match the file name of the HTML index document that you plan to upload to your S3 bucket. When you configure a bucket for website hosting, you must specify an index document. Amazon S3 returns this index document when requests are made to the root domain or any of the subfolders. For more information, see Configuring an index document.

  8. To provide your own custom error document for 4XX class errors, in Error document, enter 404_not_found/index.html.

    The error document name is case sensitive and must exactly match the file name of the HTML error document that you plan to upload to your S3 bucket. If you don’t specify a custom error document and an error occurs, Amazon S3 returns a default HTML error document. For more information, see Configuring a custom error document.

  9. Choose Save changes.

    Amazon S3 enables static website hosting for your bucket. At the bottom of the page, under Static website hosting, you see the website endpoint for your bucket.

  10. Under Static website hosting, note the Endpoint.

    The Endpoint is the Amazon S3 website endpoint for your bucket. After you finish configuring your bucket as a static website, you can use this endpoint to test your website.

Step 3: Edit S3 Block Public Access settings

By default, Amazon S3 blocks public access to your account and buckets. If you want to use a bucket to host a static website, you can use these steps to edit your block public access settings.

Note: before you complete this step, review Using Amazon S3 Block Public Access to ensure that you understand and accept the risks involved with allowing public access. When you turn off block public access settings to make your bucket public, anyone on the internet can access your bucket. We recommend that you block all public access to your buckets.

  1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.
  2. Choose the name of the bucket that you have configured as a static website.
  3. Choose Permissions.
  4. Under Block public access (bucket settings), choose Edit.
  5. Clear Block all public access, and choose Save changes.

Step 4: Add a bucket policy that makes your bucket content publicly available

After you edit S3 Block Public Access settings, you can add a bucket policy to grant public read access to your bucket. When you grant public read access, anyone on the internet can access your bucket.

Note: the following policy is an example only and allows full access to the contents of your bucket. Before you proceed with this step, review How can I secure the files in my Amazon S3 bucket? to ensure that you understand the best practices for securing the files in your S3 bucket and risks involved in granting public access.

  1. Under Buckets, choose the name of your bucket.
  2. Choose Permissions.
  3. Under Bucket Policy, choose Edit.
  4. To grant public read access for your website, copy the following bucket policy, and paste it in the Bucket policy editor. 
    {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": [
        "s3:GetObject"
      ],
      "Resource": [
        "arn:aws:s3:::example.com/*"
      ]
    }
  ]
}

  5. Update the Resource to your bucket name.

    In the preceding example bucket policy, example.com is the bucket name. To use this bucket policy with your own bucket, you must update this name to match your bucket name.

  6. Choose Save changes.

    A message appears indicating that the bucket policy has been successfully added.

    If you see an error that says Policy has invalid resource, confirm that the bucket name in the bucket policy matches your bucket name. For information about adding a bucket policy, see How do I add an S3 bucket policy?

    If you get an error message and cannot save the bucket policy, check your account and bucket Block Public Access settings to confirm that you allow public access to the bucket.

Amazon CloudFront

Note: these instructions are based on the official Speeding up your website with Amazon CloudFront walkthrough.

Step 1: Create a CloudFront distribution

First, you create a CloudFront distribution. This makes your website available from data centers around the world.

To create a distribution with an Amazon S3 origin

  1. Open the CloudFront console at https://console.aws.amazon.com/cloudfront/.
  2. Choose Create Distribution.
  3. On the Select a delivery method for your content page, under Web, choose Get Started.
  4. On the Create Distribution page, in the Origin Settings section, for Origin Domain Name, enter the Amazon S3 website endpoint for your bucket, for example, example.com.s3-website.us-west-1.amazonaws.com. CloudFront fills in the Origin ID for you.

  5. For Default Cache Behavior Settings, keep the values set to the defaults.

    With the default settings for Viewer Protocol Policy, you can use HTTPS for your static website. For more information these configuration options, see Values that You Specify When You Create or Update a Web Distribution in the Amazon CloudFront Developer Guide.

  6. For Distribution Settings, do the following:

    1. Leave Price Class set to Use All Edge Locations (Best Performance).

    2. Set Alternate Domain Names (CNAMEs) to the root domain and www subdomain, for example, example.com and www.example.com.

      Note: Prior to performing this step, note the requirements for using alternate domain names, in particular the need for a valid SSL/TLS certificate.

    3. For SSL Certificate, choose Custom SSL Certificate (example.com), and choose the custom certificate that covers the domain and subdomain names.

      For more information, see SSL Certificate in the Amazon CloudFront Developer Guide.

    4. In Default Root Object, enter index.html.

      If the URL used to access the distribution doesn’t contain a file name, the CloudFront distribution returns the index document. The Default Root Object should exactly match the name of the index document for your static website. For more information, see Configuring an index document.

    5. Keep all other settings at their default values.
  7. Choose Create Distribution.

  8. To see the status of the distribution, find the distribution in the console and check the Status column.

    A status of InProgress indicates that the distribution is not yet fully deployed. After your distribution is deployed, you can reference your content with the new CloudFront domain name.

  9. Record the value of Domain Name shown in the CloudFront console, for example, dj4p1rv6mvubz.cloudfront.net.

  10. To verify that your CloudFront distribution is working, enter the domain name of the distribution in a web browser.

    If your website is visible, the CloudFront distribution works. If your website has a custom domain registered with Amazon Route 53, you will need the CloudFront domain name to update the record set in the next step.

Step 2: Update the record sets for your domain and subdomain

Now that you have successfully created a CloudFront distribution, update the alias record in Route 53 to point to the new CloudFront distribution.

To update the alias record to point to a CloudFront distribution

  1. Open the Route 53 console at https://console.aws.amazon.com/route53/.
  2. In the Hosted Zones page, choose the hosted zone that you created for your subdomain.
  3. Choose Go to Record Sets.
  4. Choose the A record that you created for your subdomain, for example, www.example.com.
  5. For Alias Target, choose the CloudFront distribution.
  6. Choose Save Record Set.

  7. To redirect the A record for the root domain to the CloudFront distribution, repeat this procedure.

    The update to the record sets takes effect within 2–48 hours.

  8. To see whether the new A records have taken effect, in a web browser, enter your subdomain URL, for example, http://www.example.com.

    If the browser no longer redirects you to the root domain (for example, http://example.com), the new A records are in place. When the new A record has taken effect, traffic routed by the new A record to the CloudFront distribution is not redirected to the root domain. Any visitors who reference the site by using http://example.com or http://www.example.com are redirected to the nearest CloudFront edge location, where they benefit from faster download times.

Configuration

In order to configure the Amazon S3 (or compatible) deployment method, head over to the WordPress Admin and click Staatic > Settings > Deployment. Choose Amazon S3 (or compatible) as the deployment method and make sure the following fields are entered correctly.

Authentication

You can authenticate with Amazon Web Services (or any compatible S3 provider) either using a credentials file and profile or directly with an Access Key ID and Secrey Access Key.

Note: Authenticating using a credentials file and profile is recommended for security reasons.

Profile

In case you are authenticating using a Credentials File and Credential Profile, enter the name of the credential profile here.

Access Key ID

In case you are using direct authentication, enter your Access Key ID here.

Secret Access Key

In case you are using direct authentication, enter your Secret Access Key here.

S3

Endpoint

Select the name of the S3 provider or choose Custom Endpoint and enter the custom endpoint address (e.g. https://ams3.digitaloceanspaces.com when using DigitalOcean Spaces).

Region

Choose the (AWS) region where your S3 bucket is located.

Bucket

Enter the name of the S3 Bucket that will store the static site’s data.

Prefix

Optionally add a Prefix in order to store the static site’s data within a subdirectory.

Object ACL

Optionally supply a (canned) Object ACL to apply to the uploaded static site’s data, e.g. private or public-read.

Retain Files/Directories

Optionally add file or directory paths (absolute or relative to the bucket prefix) that need to be left intact (one path per line).

Note: files existing in the target bucket that are not part of the build and not in this list will be deleted upon deployment.

Examples: favicon.ico, robots.txt, a Bing/Google/Yahoo/etc. verification file.

CloudFront

Distribution ID

The CloudFront Distribution ID allows cache to be invalidated automatically.

Note: in order to disable CloudFront integration, leave this value empty.

Maximum Invalidation Paths

This defines the the maximum number of invalidation paths (or in other words, the maximum number of paths that have changed due to a publication) before invalidating everything.

By default, Maximum Invalidation Paths is set to 50. Depending on your requirements and budget, this value can be increased or decreased.

Note: above a certain monthly threshold invalidations are charged per path. See CloudFront pricing for more information.

Invalidate Everything Path

This is the path to invalidate when Maximum Invalidation Paths has been exceeded.

By default, Invalidate Everything Path is set to /*. In case your static WordPress site is hosted from a subdirectory (e.g. https://example.com/wordpress/), this value should be adjusted accordingly.