# 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](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html)
for more information). I used [Homebrew](https://brew.sh) to install it as follows:

```shell
$ 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:

```bash
$ aws s3api create-bucket --bucket <bucket-name> --region us-east-1
```
Configure the bucket:
```bash
$ aws s3api put-bucket-website --bucket <bucket-name> \
> --website-configuration file://config/website.json
```
Here is the content of the `website.json` file:
```json
{
    "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:

```bash
$ 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:

```json
{
    "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:

```bash
$ 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`.