Introduction

Welcome! My name is Michael Ford, and as of this writing, I am a Principal Solutions Architect at Red Hat. I spend my work hours talking to my clients about how to deploy applications with cloud-native platforms and tools, and I recently decided to share my learnings with a broader audience. To that end, I’ve been on a journey to choose a blogging platform; this first entry documents how this blog came to be, and how you might start your own.

Values in a blogging platform

When researching blogging platforms, I looked for one that follows the principles of Twelve Factor App development:

  • Minimize time and cost: Use declarative formats for setup automation.
  • Eliminate servers and systems administration: Deploy on modern cloud platforms.
  • Enable continuous deployment: Minimize divergence between development and production.
  • Scale with little additional effort: Use consistent tooling and development practices.

Platform Options

Wordpress

Wordpress is a widely used content management system that has deep roots in blogging. WordPress runs with a server frontend and MySQL database backend, and can be deployed on a Kubernetes cluster which made it appealing as a candidate for my first real-world k8s project.

My research into deploying a k8s cluster for WordPress in AWS environment revealed a high level of complexity and maintenance cost for the smallest workload possible. This tweet illustrates the issue nicely:

Even on the conservative end, the estimated cost comes in at ~$300/month - far too high for a simple blog.

Medium

Medium is a blogging/social journalism website, sometimes thought of as “long-form Twitter.” Publishing on Medium offers several benefits: tracking of readership metrics, the ability for people to reach you on your other social media platforms, SEO advantages if you use medium’s domain (although use of custom domains is allowed with a paid membership).

I may decide to publish content here at some point, but I still wanted to implement blogging-as-a-service with tooling similar to what I use for my work. I also noticed a lack of theme choices with Medium.

HUGO

Hugo is a static site generator, meaning the site has no database backend to manage, and less avenues for security threats. Hugo uses content written in Markdown format, supplementing shortcodes where Markdown falls short. Configurations for how your site is generated can be written in YAML, and the site can be deployed to just about anywhere you can think of (AWS S3, Google Cloud Storage, Azure Storage, Github Pages, Netlify, etc.). Hugo also has a vast library of themes to choose from, giving your site a more personal feel.

My experience with Github and Ansible meant that the technologies involved (Markdown, YAML, git, AWS S3) were already in my skillset. Furthermore, using a Github repository with S3 would make updates reliable, consistent, and inexpensive.

Blog setup instructions

The above image illustrates the architecture of how this blog is generated/uploaded to S3, and how end users retrieve it. My local machine has git and Hugo installed, which allows me to make changes and see them in my local browser. When changes are completed, I push them to the cloud-based repository at Github.com. The push triggers a Github Action, which takes the Markdown content, converts it to HTML, and then deploys it to my S3 bucket. The S3 bucket hosts a static site, but when an end user navigates to https://mford.io, they are in fact resolving to a CloudFront CDN Edge location, which handles HTTPS traffic and uses the S3 bucket as its point of Origin. The steps to configure this are detailed in the subsequent sections.

Install git and Hugo

Instructions for installing Hugo are here, and git is here. If you are using a Mac, I recommend using Homebrew as it is a great all-around package manager (use it to install git, and Hugo). Instructions to install Homebrew for the Mac are here. Afterward, verify installation by running hugo version and git version:

$ hugo version
hugo v0.82.0+extended darwin/amd64 BuildDate=unknown

$ git version
git version 2.31.1

Set up S3 and CloudFront

AWS documentation does a great job of walking you through setting up an S3 bucket to host your static site with a custom domain, with a CloudFront Distribution in front of it. Those instructions can be found here. Make sure to note the name of your S3 bucket and CloudFront distribution ID as you will need them in the next step.

Configure AWS access

In order to automate updates from your Github repository to S3, you must provide limited Programmatic AWS Access to your Github repository. The detailed instructions from AWS are here, and guided instructions begin with the first image below.

Starting off in the AWS console, navigate to the IAM (Identity and Access Management) service –> Users, and click on the button marked “Add user”.

Populate a name for the user, and make sure to only select Programmatic access, excluding Console access. Click on the button marked “Next: Permissions”.

On the Set Permissions page, click on the box marked “Attach existing policies directly”. A button marked “Create policy” will then appear; click on it in order to open a new tab and create a custom policy (but do not close this current tab).

In this new tab, you’ll have an option to set policy via the visual editor or JSON - this will determine what level of access an AWS user will have. Choose JSON, and populate the policy field with the following snippet, substituting [CF_DISTRIBUTION_ID] and [BUCKET_NAME] with your real values: Afterward, click on the button marked “Next: Tags”.

If you choose to, you can add tags (key-value pairs applied to AWS resources in order to categorize them); this is not required. Afterward, click on the button marked “Next: Review”.

On the Review page, you’ll be shown a summary of access this policy will grant a user; make sure it only grants access to CloudFront and S3. Give the policy a descriptive name and click on the button marked “Create policy”.

You will then be taken to the Policies page, where a notification will appear that your policy has been created. You can now close this tab and go back to the first one in which you are creating a new user.

Back on the Add user browser tab, click the refresh button (indicated in the above image) to ensure that your newly created policy is selectable. Type in enough of the policy name so that it appears in the list; select it and then click on the button marked “Next: Tags”.

As with the policy, you can add tags for this new user if you wish. Afterward, click on the button marked “Next: Review”.

Review the summary of this new user to make sure the name and policy are correct, and then click on the button marked “Create user”.

You will then be presented with a confirmation page for the user having been added, and the Programmatic credentials (Access Key ID and Secret Access Key) presented to the screen and also downloadable as a .csv file. Make sure you document the credentials before leaving this page they will only be presented to you once.

Set up Github

On your local machine, create a new Hugo site by running the following command, with a name that matches what you want your Github repository to be (not required to be the name of your actual domain):

$ hugo new site my-github-repo

This will generate a new Hugo site directory with the name my-github-repo (you can of course name your site/repository something different).

Next, you can use these instructions to create a Github repository using your local Hugo site directory.

You can add your AWS Programmatic Keys from the previous step to the repository, which will allow you to automate HTML pages to your S3 bucket later via Github Actions. From the web console of your Github Repository, navigate to Settings -> Secrets. Create two new repository secrets, AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY, adding the values you got from AWS. These values will be encrypted automatically.

Deploy HTML to S3

Following from Step 3 in the Hugo Quickstart Guide in your site directory will allow you to install a custom theme, create sample content, and see your static site locally. The Hugo Deploy Guide instructions can then be followed in order to configure deployment to your S3 bucket, specifying a CloudFront Distribution if you chose to set one up.

Automate HTML Deployments

GitHub Actions allow for event-driven automation from you repositories. In the case of Hugo, we want a merge/push to the main branch of the repository (indicating new content going live) to trigger a Hugo deployment of the static blog to the S3 bucket. This happens through use of a workflow YAML file being added to your top level Hugo site directory, which in this example would be at my-github-repo/.github/workflows/deploy_hugo_site.yml. The following is an example of the contents of the workflow:

Note that the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY are taken from the values you added to the repository.

From this point on, a push to your Github repository will automatically trigger an update to your static blog/site on S3!

Cost

As of this writing, potential elements of cost for this blog are:

  • S3
    • for the first 50TB, S3 Standard costs $0.023 per GB
    • HTTP GET requests cost $0.0004 per 1000 requests
  • CloudFront
    • Any HTTP/S requests less than quantity 10,000 per region, per month costs nothing.
    • CDN Invalidations less than quantity 1,000 per month costs nothing.
  • Route 53 Domain

In total, for a personal static site running in S3, you won’t be generating huge amounts of traffic and will incur a total cost of $45 for the entire year.

Conclusion

For a personal blog, deploying a site built with Hugo to a cloud bucket is a great way to apply the 12-factor development method to blogging, for a cost of next-to-nothing and relatively little effort applied after initial setup. Hopefully this entry can get you started on your own.