Website hosting using Amazon’s S3

This site is generated by Sphinx, and hosted on Amazon S3. These are the steps I used to create the S3 bucket.

Amazon AWS CLI

I used Amazon’s AWS command-line interface (see: AWS Command Link Interface User Guide for more information). I used Homebrew to install it as follows:

$ brew install aws

Bucket Configuration

In order to use an S3 bucket to serve web pages, you need to create the bucket and then provide a website configuration. At a minimum, the configuration file identifies the primary index document, and an error document to use.

Create the bucket:

$ aws s3api create-bucket --bucket <bucket-name> --region us-east-1

Configure the bucket:

$ aws s3api put-bucket-website --bucket <bucket-name> \
> --website-configuration file://config/website.json

Here is the content of the website.json file:

{
    "IndexDocument": {
        "Suffix": "index.html"
    },
    "ErrorDocument": {
        "Key": "error.html"
    }
}

Bucket Policy

Next, I need to make the contents of the bucket readable by everyone. The following command sets the policy on the bucket:

$ aws s3api put-bucket-policy --bucket <bucket-name> \
> --policy file://config/bucket-policy.json

The following policy JSON file shows how to make the bucket readable by the world:

{
    "Version": "2018-10-09",
    "Statement": [
        {
            "Sid": "PublicReadGetObject",
            "Effect": "Allow",
            "Principal": "*",
            "Action": "s3:GetObject",
            "Resource": "arn:aws:s3:::<bucket-name>/*"
        }
    ]
}

Uploading Site

The aws sync command is the best way to upload a collection of files to S3. The keys for the S3 objects are based on the relative path to the file from the root directory. In this case, I was in the build directory where Sphinx places the processed files. The following command copies all of the files to S3:

$ cd ./build
$ aws s3 sync ./ s3://<bucket-name>

Website Location

Amazon assigns a default URL based on the bucket name, as follows:

http://<bucket-name>.s3-website-us-east-1.amazonaws.com

To use a custom domain, you need to create a CNAME record and point the host to the Amazon bucket identifier. The name of the bucket MUST match the name of the host. In other words, if I want to host a website at the mark.choate.info host, then the bucket MUST be named mark.choate.info.