Setting up Hugo, the static site generator, to build my blog with Microsoft Azure.
Last time on The Quest, we mused about trying to merge blog posts, tweets, and videos into one web site. It’s still on my mind, and you can see some of that experimentation in the form of my weekly video posts. (Those posts are built with a Go program I wrote, a part of my “learning Go in 2021” process.)
But I’ve neglected to post yet about the massive blog overhaul I did at the beginning of 2021, which was something I wanted to document for posterity, because it’s already starting to fade from my memory. It’s a big topic, though, and it takes me roughly seven years to write long blog posts these days.
Way back toward the end of December 2020, I had setup the Hugo static site generator to locally build my web site the way I wanted it. Once the files were built, I could upload the HTML files from my hard drive to a web host through ftp, just like the days of yore, but that’s tedious and slow and generally awful. There’s a reason people stopped making web sites that way.
So I started looking for ways to automate the process. There are several places that host “static web sites” through a continuous integration platform. The Hugo documentation mentions AWS, Netlify, Render, Firebase, GitHub Pages, and several others. They all have pros and cons and various pricing structures. Most don’t let you make a free site bigger than around 1 GB, which is pretty small if your site has any images. (Endgame Viable accumulated over 2GB of images in eight years.)
But I stumbled upon a 2019 blog post at melcher.dev that discussed hosting Hugo static web sites on Azure really cheap, or even free if you can stay below a 5 GB free limit. I also found some useful information from a 2019 Medium post by @kurtmkurtm.
Unfortunately, it turns out that Microsoft’s Static Website Hosting is still in testing, which became a big problem toward the end. So I can’t quite use it to host the site yet, but I was able to set it up to build the site.
At least 50% of the information in those blog posts was already obsolete or didn’t apply to my situation, so I had to go off-script quite a bit. Here’s what I ended up doing, to the best of my memory:
- Create a free Microsoft Azure account. You have to give them a phone number and credit card number.
- Somehow I ended up with a $20/month charge for some developer thing, I don’t know how it happened, but I cancelled it. Otherwise it costs me about 5 cents a month to update my blog.
- Create an Azure DevOps account. Azure DevOps is basically Microsoft’s version of GitHub, a cloud version of TFS.
- Create a DevOps Project, which creates a Git repository. This is where the “source code” for your blog–the Markdown content files and Hugo theme files–will reside. It’s essentially a copy of the files on your local hard drive up in the cloud.
- Run git commands to connect my local Git repository to the Azure DevOps repository (remote add origin).
- Push the contents of my local git repository to the Azure DevOps repository (git push origin).
- Create an Azure Storage account, to hold the static web site files. This is where the final web site files will live, ie. the HTML files that are created by the Hugo static site generator.
- Create a Resource Group to tie everything together, part of the Storage account creation. (I don’t remember why I had to do this but it’s in my notes so I guess I’ll leave it here.)
- Enable Static Website on the Storage account.
- Create a Pipeline in DevOps. These are the build steps that will be triggered when anything is committed to the repository.
- Install the Hugo Build Task from the Visual Studio Marketplace.
- I had to do a lot of fiddling with the Access Control (IAM) settings from the menu on the left to get all the permissions setup to connect everything together.
After all that I could write posts on my local hard drive, commit them to git, push them to Azure and build the web site with one button press. It made a working Azure static website, but the link was https://endgameviable.z13.web.core.windows.net/. If you can live with publishing a link like that to the world, you’d be done. It’d be fine if you were starting a brand new blog I suppose. Unfortunately I had eight years of blog posts with very different-looking permalinks, and I didn’t want anyone to have to change their links.
So I worked on setting up a custom domain for the Azure static website, which turned out to be a major stumbling block. That’s also when it dawned on me that there is no such thing as an .htaccess file with static web hosting, so redirects are out of the question.
Limitations I ran into:
- The biggest one: There is no .htaccess for static web sites which means I had no way to redirect old permalinks to my new Hugo directory structure. Everybody’s old links from the past eight years would break. That’s bad.
- Second biggest one: No “root domain” support for custom domains on Azure static websites yet. So it had to be www.endgameviable.com instead of endgameviable.com. Another big problem for me and my eight years of existing permalinks. There are redirection workarounds (I tried Cloudflare) but it’s janky.
- Only HTTPS traffic is supported on Azure static websites, so there were some further headaches with certificates after redirecting. The certificate that Azure creates for you has their Microsoft domain name in it, but my custom domain name is endgameviable.com. Some web browsers were fussy about that.
- Image storage is a problem with free static hosting. WordPress kept massive amounts of image data for the last eight years: About five copies of every image uploaded. Shrinking that down is an ongoing concern that isn’t complete yet. You may or may not have noticed that many older posts here don’t have their images yet.
In the end, I had to keep my Apache shared hosting site, at least for now. I setup an Azure build task to sftp the completed web site to my shared web host (another fun adventure), where I can use .htaccess and the SSL certificates work properly. (SSL certs were a recent addition to my web host, finally.) That’s the current state of the blog.
Whew. I intended that to be a much more polished post with screenshots and everything, because it’s a massive topic. But this draft has been sitting around for five months now and it’s well past time to move on.
Next time, I hope to talk about moving from Azure to Amazon AWS, where many things will become possible, including a plan I’ve hatched to support comments without resorting to a “normal” comment platform.