A few people have been asking how I maintain such a fast blog without running a database or dedicated web server. I use a variety of tools and services to host Route1337.com and I’ve decided that I’m going to share how I set it all up.
I’m going to assume some familiarity with the technologies below and focus on the specific setup of Route1337.com instead of a “how to” for each service.
Tools and services used:
I use the following services to host the site’s code and content:
- Amazon Web Services - S3
- Amazon Web Services - CloudFront
- Amazon Web Services - Route53
- GitHub Private Repository
- GitHub Actions
Color coding used in this Article:
I’m using the following syntax highlighting in this article:
- Variables you need to change are in red.
- Field names you need to look for are in teal.
- Special instructions relating to variables are in orange.
- Variables you must copy exactly are in purple.
- Code blocks have a grey background and the color scheme is a language syntax instead of the above rules.
Step 1: Configuring AWS S3
S3 is wonderfully simple to configure. First we’ll start with creating the two buckets we need for our site.
- In your AWS account create buckets for example.com and www.example.com
- For the example.com bucket, turn on Static Website Hosting and Redirect all requests to another host name.
- Set the host name to www.example.com.
- For the www.example.com bucket, turn on Static Website Hosting and Enable website hosting.
- Set Index Document to index.html and set Error Document to 404.html
- Since the www.example.com bucket will contain our actual site we need to set a bucket policy on it. Set the below bucket policy:
The above code only allows the “Amazon CloudFront” user agent to view our site. That is intentional since we want to avoid the duplicate content penalty.1
Step 2: Configuring AWS CloudFront
Despite being a CDN, CloudFront works well as a way to load balance a static website globally and is also the only way to get SSL on an S3 hosted static site.
- In your AWS account create a CloudFront Web distribution with the following settings:
- Origin Domain Name: www.example.com.s3-website-us-east-1.amazonaws.com2
- Origin Path: LEAVE BLANK
- Origin ID: You can make up a descriptive name here
- Origin SSL Protocol: TLSv1.2, TLSv1.1, TLSv1
- Origin Protocol Policy: HTTP Only
- Viewer Protocol Policy: Redirect HTTP to HTTPS
- Allowed HTTP Methods: GET, HEAD
- Object Caching: Use Origin Cache Headers
- Forward Cookies: None (Improves Caching)
- Forward Query Strings: No (Improves Caching)
- Smooth Streaming: No
- Restrict Viewer Access: No
- Compress Objects Automatically: No
- Price Class: This one is up to you. I use "Use Only US and Europe"
- AWS WAF Web ACL: Also up to you. I have it turned off
- Alternate Domain Names: www.example.com
- SSL Certificate: You can use the "Request an ACM certificate" button for this or use the awscli to upload your own
- Default Root Object: index.html
- Logging: Off
- Comment: Something descriptive for your site
- Distribution State: Enabled
- Now click “Create Distribution”
- Now perform the same steps above for the example.com bucket.
Step 3: Configuring AWS IAM permissions for use with GitHub Actions
IAM needs to be configured so GitHub can perform functions in S3 and CloudFront later. This is one of the simplest things to configure for this type of site deployment.
- Create an IAM user called github-actions and remember to save the IAM keys somewhere safe for later.
- Create an IAM policy called github-actions with the following policy text and assign it to the github-actions user:
Step 4: Configuring Route53
In order to serve CloudFront properly we will use Amazon’s Route53 DNS service. I’m going to assume you have Route53 configured as your DNS provider for example.com already.
- Create an Alias record for example.com and point it at the matching CloudFront CDN (NOT THE S3 BUCKET)
- Now create an Alias record for www.example.com and point it at the matching CloudFront CDN (NOT THE S3 BUCKET)
Step 5: Configuring GitHub
Here is how you can configure GitHub for automatic deployments.
- Move your Jekyll code into a folder called SourceCode in the root of the repo
- Create a folder in the repo root called BuildAdditions
- Create a JSON file in BuildAdditions called CloudFront-Invalidate.json with the following contents (USE YOUR ACTUAL DISTRIBUTION ID BUT LEAVE COMMIT_HASH EXACTLY AS SHOWN):
Step 6: Configuring GitHub Actions
GitHub Actions is going to do the actual automated deployment once it is triggered by a merge or push to the main branch. The setup is pretty simple though.
- In your repository settings create the following under Secrets:
- Create AWS_ACCESS_KEY_ID with the AWS access key for the github-actions user.
- Create AWS_SECRET_ACCESS_KEY with the AWS secret key for the github-actions user.
- Create a folder in your repo called .github/workflows
- Inside the .github/workflows folder create a file called deploy.yml containing
The workflow behind all of this
The workflow behind what was done here is simple. You work on your Jekyll site via a development branch in GitHub. When you are ready to publish changes, merge it into the main branch. This triggers GitHub Actions to check out the repo, build with Jekyll, sync it to S3 and clear the CloudFront cache so the changes appear live. This way you only have to worry about your local text editor and GitHub.
BE WARNED: Make sure you don’t work off the main branch! Every commit or merge to the main branch will trigger a build.