5 min read

Putting It All Together

May 8, 2017

Documentation tends to focus on “how” and often misses the “why”.

Jonathan Palardy puts it very well.

there’s a README.md in each repo now… but maybe we need a documentary.mp4 instead. Interviews about how the code evolved.

At work, I update a collection of essays every few months which explain the “why” for decisions/projects/technology-choices. This provides a more holistic experience compared to reading various tickets, searching emails and the typical institutional/tribal knowledge.

With that said, I want to do the same for the state of this blog.

Content

Hugo generates the site using the Lithium theme from a collection of markdown documents. I use (mac)vim to write on a Macbook Pro.

Why vim?

  • I have been using Vim for many years and want to take my skills to the next level
  • Vim is everywhere. Any place I SSH to, will most likely have Vim available. If not, then a simple apt-get or yum install will make it available. Compare this to Eclipse or Sublime :)

Why a static site generator?

  • KISS - Keep It Simple Stupid
  • Anything “fancy” can be done with client side Javascript
  • Runs locally, truly WYSIWYG
  • I own everything vs exporting from WordPress, Tumblr, BlogSpot etc
  • It’s a simple personal blog

Why not Jekyll?

  • Ruby. Installation is always a pain. You never know which gem is “in-vogue”
  • I work in Ops. I fight installation/configuration for a living, I prefer not to do that when I have an occasional 40 minute slot before I go to bed.
  • Hugo comes as a single Go-binary available via Brew

Managing Source

Git, of course :)

I have two repositories:

  1. The markdown of the posts, hugo configs and theme
  2. Generated website

I keep the generated website in a separate repo as it lets me easily compare changes/do rollbacks. And I could try a new version of Hugo and compare the diffs if any in the resulting code.

Hosting the content

Repository #2 above ends up in a git repo on GitHub, where it is rendered using GitHub Pages.

Why GitHub?

I could have used AWS S3 for static content. However GitHub stores my generated source in a repo and renders it at the same time. This is convenient. It’s also free!

Why not run a server on EC2 or Digital Ocean or Linode?

  • Glibc, DirtyCow, ImageTragick, Heartbleed, and so many others
  • Configuration of a webserver
  • SSL certs - Lets Encrypt makes it easy, but another setup I need to manage. Getting an A/A+ on SSL is always a dark art
  • I would have to maintain SSH keys to my server + credentials for the cloud provider
  • For a small setup such as a personal blog, a server is an overkill
  • What if one day I make HackerNews frontpage :), my little server will suffer a DDOS

Aren’t you better off on Tumblr/Wordpress/Medium etc for all these reasons?

Yes and No. Yes I wouldn’t need to worry about ‘server-ops’ on a blogging platform. But my previous reasons to generate a static site trump everything else. I mostly focus on Operations/Backend work. Having Hugo do all the FrontEnd work is fascinating and it gives me a chance to look at how all the rendering magic happens.

Domain, DNS, HTTPs

Domain was purchased via Google Domains. Other registrars are ok, but Google already has my credit card information and their G-suite is phenomenal.

DNS

Initially I used Google’s Nameservers and pointed blog.manasg.com to Github Pages' IP addresses. This is the simplest possible setup. However it did not have HTTPs since Github does not support HTTPs on custom domains (as of Spring 2017), but https://manasg.github.io/ is available over HTTPs.

Going HTTPs

Why HTTPs?

Everything should run on TLS :)

How?

I really respect and admire the work CloudFlare is doing. So they were my first choice over Akamai and other providers.

  1. CloudFlare Nameservers for my domain
  2. blog.manasg.com at DNS level goes to manasg.github.io (also use CloudFlare as a caching proxy)
  3. http -> https enforcement enabled by using PageRules at CloudFlare

Bonus

  1. manasg.com at DNS level goes to blog.manasg.com so that it hits CloudFlare servers
  2. Page rule sends a HTTP redirect for manasg.com to blog.manasg.com to enforce HTTPs + modify Host Header

For the Naked Domain redirect, I was tempted to use AWS Lambda, but I prefer having my DNS and HTTP-routing rules in one place.

The CloudFlare free account was sufficient for all of the above. Relevant posts

Why not Google Firebase for HTTPs?

Requires me to install the toolchain written in Node.js via npm. Sorry.

Monitoring

Pingdom’s free account lets me watch uptime for one site.

Logging

This is tricky, as I can’t get plain old HTTP Access logs with my setup. S3 does have an option of storing access logs in a separate bucket.

However, access logs by themselves would not be very helpful for a simple site like mine. The value lies in Analytics.

  • User Focussed - I use Google Analytics free tier
  • Infrastructure - CloudFlare gives excellent breakdown of traffic/threats/cache-hit-miss-ratio etc

Conclusion

Setting up a site is still fun outside work :)

I took a shortcut for a few things so I could spend time exploring others. There is nothing wrong with platforms like Medium, Wordpress, Tumblr, but I wanted to try something else and did not want to setup up my own server.