ozbe

ozbe.io Rises

May 05, 2020

Migrating ozbe.io from vanilla HTML to GatsbyJS.

Background

Several years ago (over 7 years to be more precise) I set up ozbe.github.io as a personal landing page. The landing page contained my name, links to my various service accounts, and a spiffy skeuomorphic background. It was a completely static site, hosted on GitHub Pages. (GH Pages)

I had aspirations to take that landing page and turn it into a blog that I could share what technologies I have been exploring. Aside from updating the site to support the ozbe.io domain, the site has remained dormant and has grown more stale. A few of the links no longer worked, Google+ no longer exists and I had become more strict about what I share on Facebook. Also, the skeuomorphic background was no longer in vogue, I blame iOS 7 (which launched in 2014) for that one.

Overview

I won’t get into my motivations, but now I’m taking the time to turn that landing page into a proper blog. To make that possible, I’m going to make a couple changes to ozbe.github.io.

First, instead of editing HTML by hand, I’m going to use GatsbyJS to generate my static content. It is free, open source, and seems to have a healthy community around it. Gatsby will allow me to take the blog posts I write in Markdown, turn them into HTML, and update the site to make that content accessible. Gatsby offers some other nice features, such as theming, that I hope I will take better advantage of in the future as well.

Secondly, to reduce the friction of getting my changes published in a form ready for GHP Pages, I’m going to use GitHub Actions . GitHub Actions will allow me to automate my publish workflow, for free. Specifically, a GitHub Action will run Gatsby’s build and save that content for GH Pages to present.

Note: Normally I’d prefer to write my requirements out and discuss alternatives when talking about my technologies choices. In this case, I’m going to exclude them for expediency and brevity. Just know that I looked at some alternatives to these technologies.

Gatsby

Gatsby offers a Quick Start | GatsbyJS to help people who haven’t used Gatsby, like myself, get started. That seemed like a sensible place to get started, but after looking at the first few commands…

$ nvm install 10
$ nvm use 10
$ npm install -g gatsby-cli

I quickly nixed that idea. I’m sure that will work and those directions are right for 90+% (made up percentage) of users, but I don’t want to install anything on my machine to work with this blog. I try to minimize what I install on my computer as much as possible. Maybe it was because I’ve been burned too much by computers failing or system bloat or wanting to selectively migrate to a new computer.

I created ozbe/gatsby-docker, a Gatsby Docker image intended to be used for development, to avoid having to install anything on my machine. To use gatsby-cli in a interactive container that will be removed when the container stops, I run the following command:

$ docker run --rm -it ozbe/gatsby

Now I can run any gatsby-cli command , such as help:

# in gastby container
$ gatsby --help

While being able to run gatsby-cli that quickly is nice, I am going to have to make a few changes to support development. First, I am going to have to mount a volume to work on my existing blog and persist changes made instance the container. Secondly, I am going to expose Gatsby’s develop and serve ports to my host machine to access the site from outside the container (say, from a web browser). Those requirements turn our nice simple docker run command from above into:

docker run --rm -it \
-v `pwd`:/site \
-p 9000:9000 -p 8000:8000 \
ozbe/gatsby

Running my Gatsby container, I am going to set up what I need to go through the Gatsby Using a Theme tutorial, which will leave me with a starter blog.

Before going through the tutorial, I need to setup a new Gatsby site with the gatsby-starter-blog-theme.

$ gatsby new my-blog https://github.com/gatsbyjs/gatsby-starter-blog-theme
# include hidden files in mv pattern below
$ shopt -s dotglob
# copy contents from my-blog to current directory
$ mv my-blog/* ./
# remove the now empty my-blog folder
$ rm -r my-blog

Note: If you know of a better better way to install a new Gatsby site in the current working directory or moving the contents, please make a merge request.

Now I have the new site, let me check that the site and container are properly working by running the Gatsby development server and opening Chrome:

$ gatsby develop -H 0.0.0.0
# on host machine, open dev in Chrome
$ open -a "Google Chrome" http://localhost:8000/

Works on my machine. Now I’ll go through Using a Theme | GatsbyJS and have myself a starter blog.

GitHub Actions

Now that I have Gatsby working locally, I need to build the static assets and save those assets in the root path of the master branch of ozbe.github.io. I could do this manually on my local machine with something like:

WARNING: I did not actually test these commands and I’m confident they won’t work:

$ git checkout gatsby
$ gatsby build
$ git checkout master
$ mv -f /public/* ./
$ git commit -a --allow-empty-message -m ''
$ git push

To reduce the friction of having to manually running through these steps (not to mention reducing the errors), I’m going to use GitHub Actions to publish my blog (remember?). Thankfully, I won’t have to work hard to leverage GitHub Actions. enriikke/gatsby-gh-pages-action does exactly what I need.

Using the README, I’ll just copy the Usage snippet into the project at the path ./.github/workflows/publish.yml and change the push branches name from dev to gatsby (the one I’m using for my Gatsby work and may as well continue using into the future).

Now when I push changes to the gatsby branch of the ozbe.github.com repo, the publish workflow will trigger, create a build, and commit the assets to the master branch. That is when GH Pages takes over and serves the assets to those that visit ozbe.io (this is a gross oversimplification, but you get the idea).

Conclusion

After several years, I finally have a blog where I can share my technical explorations. Gatsby does the heavily lifting of generating the static HTML content and GitHub Actions takes the tedium out of publishing my site.

Thanks for following along. I hope this may prove useful to others, it was a little entertaining to read, and that you’ll come back to read more.

If you have any suggestions or see anything that can be improved, please open an Issue or merge request.

Next Steps

Where do I go from here with the blog? I have a few ideas:

  1. I use Bear to write my posts. Currently I manually move the post from Bear to Gatsby. Maybe I can come up with an automated workflow using my project GitHub - ozbe/x-callback-url: A utility for interacting with local macOS applications using x-callback-url http://x-callback-url.com.?
  2. It’d be nice to have some analytics on the blog to see which articles are popular. There are some privacy conscience analytic solutions I can add, like GoatCounter – Website analytics for regular folks?
  3. Analytics or not, I’m sure this site will be wildly popular. </sarcasim> I wonder if I can add comments with something likeStaticman: Static sites with superpowers to enable more engagement from the readers.


Comments


Josh Aaseby
Software Engineer