Evan X. Merz

For the last few years, I had been running this blog using Gatsby. In general, I liked Gatsby. I liked that it was so simple up front, but had such deep complexity under the hood. I liked that it supported React out of the box. I liked that it could generate websites in so many different ways.

I liked it enough that I made my own minimalist blog starter called Empress, which was a fully featured blog based on the tutorial but with several key features added. I used that for this blog for several years and I liked it.

But man, the leadership of Gatsby was bad. They took it in such weird directions. They tried and failed at so many weird features that the documentation, and the product itself just became a dumping ground.

It really went off the rails when they created Gatsby "themes" that had nothing to do with the colloquial use of "themes". Themes were really more like plugins, but they were already using that term, too. So it was a hot mess, and soon enough the feature seemed to disappear from the docs and from existence.

Then they were bought by Next. I still don't understand that acquisition. Next.js is a good product with sensible leadership. I liked using it at my prior job, and I considered using it for this site, but it was just overkill.

So when I could no longer navigate the crazy web of dependencies to upgrade my blog to the latest version of Gatsby, I essentially stopped writing. I was just so frustrated with it.

Until this weekend, when I decided it was time to change.

Hello, Eleventy!

I decided to switch to Eleventy mostly because it's the static site generator with the most hype right now. Sometimes it's good to try the tech that is currently being hyped. It's good to stay up to date and have that line on your resume.

But also, Eleventy is a good product. I planned on spending a few weekends getting my blog switched over, but it only took me a few hours on Saturday, Sunday, and Monday to get it 95% switched over. There are still a few minor bugs here and there - don't check the title tags on tag pages, and ignore the reverse chronological sorting in some places - but in general the switch was very easy.

I've been around web programming since the 1990s, and Eleventy feels like a return to an older way of working, but with some of the good infrastructural tech we picked up along the way. Like now I'm writing in markdown, and I don't need to run MySQL on my server, nor do I even need to run a traditional "server". I can just host my static site on S3, and use GitHub Actions to deploy it, just like with Gatsby.

And I've heard some of the blowback against Jamstack architecture sites in the last few years. It's why I briefly considered using Next for this. But I still think JavaScript + API is the best/fastest/cleanest way to run a website, whether it's a blog or something more complex. I don't have an API for this site, but I feel like I could attach one without too much trouble if the need arose.

I do wish that I could use React. I saw some people try to get Eleventy working with React experimentally, but I didn't see any updated package to do it. Nunjuks and markdown are okay for the basics, but I do think that a true component-based architecture is ultimately a cleaner way to build UIs than a template based architecture.

Until next time...

So I'm going to give Eleventy a shot for now.

But we all know that those of us who still quixotically maintain personal blogs in 2024 are on a perpetual upgrade cycle. We all know that no "upgrade" is the final upgrade.

I wonder what I'll "upgrade" to in a few years? Maybe Wordpress will come back around?

I love GitHub Actions. It is my favorite platform for continuous integration and deployment by far. It takes most of the concepts from tools like Jenkins and TeamCity, and packages them into a tight, easy to use framework.

Plus, GitHub Actions has a wonderful free plan. So I use GitHub for hosting the repository for my blog, and I use a simple GitHub Actions script to build and deploy it to AWS.

In this article, I'm not going to show you how to set up AWS to host your static site. I'm just going to give you a basic overview of the setup that I use, and give you the simple example script that I use to build and deploy my blog.

Requirements

This is the simplest and cheapest way that I've found to host a static website on AWS. There are definitely cheaper blog platforms out there, but this way gives you full control over every aspect your site, and leaves you the flexibility to evolve your site in the future.

Here are the prerequisites for using this deploy script on GitHub Actions.

1. An 11ty website
2. A GitHub repository that contains your website
3. An AWS S3 bucket that is configured to host publicly available files
4. An AWS cloudfront distribution that serves as a cache for the content on S3
5. AWS access credentials that can update the S3 bucket and CloudFront distribution that have been saved into secrets on your GitHub repository called AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY.

The CloudFront distribution is necessary for caching, and for applying an SSL certificate to your site so that you can safely use the secure https protocol.

You need to set up each of those things before you can use this script.

Modifying the example script

First you should copy this code into a file that is saved into ".github/workflows/main.yaml", where the ".github" folder is in the root directory of your repository.

Then you will then need to modify the example script below in several ways.

If you're using a static site generator other than 11ty, then you need to modify the part of the example script where it says "Build the website". That script will depend on the framework you are using.

Where it says "<YOUR_S3_BUCKET>", you will need to replace that with the name of your S3 bucket.

You will also need to replace "<YOUR_FOLDER_TO_IGNORE>" in the section "Upload files to s3 with AWS CLI" if there are any files in your S3 bucket that the script shouldn't delete. I have folders for images and documents that I want to stay in the same place no matter what is in the repository. So that part of the script ensures that those folders aren't touched.

Finally, you will need to replace "<YOUR_CLOUDFRONT_DISTRIBUTION_ID>" with the string ID of your actual CloudFront distribution.

Then all you will need to do is push that script to your master branch on github. It should handle the rest.

Example script to deploy an 11ty static site to AWS S3 using GitHub Actions

name: Build and push to s3
on: [push]
jobs:
  build_deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@master

      - name: Build the website
        run: npx @11ty/eleventy

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v1
        with:
          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws-region: us-west-1

      - name: Upload files to s3 with AWS CLI
        run: aws s3 sync _site/ s3://<YOUR_S3_BUCKET> --delete --exclude "images/*" --exclude "<YOUR_FOLDER_TO_IGNORE>"

      # Invalidate Cloudfront. Based on https://community.ops.io/jei/deploy-a-web-app-to-s3-with-cloudfront-invalidation-via-github-actions-4433
      - name: Issue Cloudfront invalidation
        uses: chetan/invalidate-cloudfront-action@master
        env:
          DISTRIBUTION: '<YOUR_CLOUDFRONT_DISTRIBUTION_ID>'
          PATHS: '/*'
          AWS_REGION: 'us-west-1'
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}