Test Case: Deploying a Hugo App to Heroku

Test Case: Deploying a Hugo App to Heroku


I wrote this article as part of a blog that I am migrating to bellebookandcode.com, hence the earlier post date. I can’t guarantee that everything will be up-to-date, but at least it was when I wrote it!


I have run numerous WordPress sites in the past, and I have also cleaned up my fair share of malware associated with the inevitable vulnerabilities, which WordPress is best known for within the security community. I have also deployed a static WordPress instance to Google AppEngine, using CloudSQL for a backend, which was unexpectedly successful – but I will document that in another test case.

I have recently been hearing about Hugo and how easy it is to manage for blogs and such (it uses/renders Markdown), and ever since I heard about Heroku’s free tier, I’ve been wanting to give it a shot. This article will be documenting how I went about doing both, and this site itself is a testament to its success. I am considering this format for possibly the longhaul, simply because of the ease of use factor.

Setup/Install Git, Heroku, and Hugo

For this tutorial, I will be working in OS X, but all applications are available across all platforms:

You’ll want to go ahead and sign up for Heroku, which doesn’t require a credit card (unlike AWS or Google AppEngine) unless you want to use the extended free features:

  • Custom domains for every free app
  • 100 free apps (as opposed to 5 for unverified accounts)

Installing Git, Hugo, and Heroku-CLI on OS X with Homebrew is as easy as running the one-liner below.

brew update && brew install git hugo heroku && heroku update

^ Feel free to remove any of the 3 packages from the command if you already have them installed.

Create a Hugo site

Pop open that command line (GUI editors are for true development and suckers), and kick off the command below, making sure to replace /path/to/heroku.blog with the actual path where you want it to live on the file system. I’m not sure if the command creates non-existing directories, but I’m sure you’ll find out soon enough if you need to mkdir -p /path/to before hugo can create heroku.blog.

hugo new site /path/to/heroku.blog
cd /path/to/heroku.blog

For a fool-proof way, just cd to the subdirectory where you want your site to live, and execute hugo new site heroku.blog.

Install a theme

Hugo doesn’t ship with themes, but you’re gonna need one. I am using a slightly modified version of hugo-theme-nix by Lord Mathis. I quickly read through the Hugo documentation, but was still having trouble overriding some of the theme’s features, so I uploaded a fork to my own GitHub repo, which I will outline later when I cover adding syntax highlighting. I will cover the steps that I used to override this theme, but first, let’s set it up as the default.

mkdir themes
cd themes
git clone https://github.com/LordMathis/hugo-theme-nix.git

Finally, add the line theme = "hugo-theme-nix" to your config.toml file, which will tell Hugo to look for and use this theme on startup.

View your site

At this point, you can actually view your site on localhost:1313 by moving back into the main directory and running hugo server.

A feature that I love about this is being able to see your updates in realtime upon Save.

cd ..
hugo server --buildDrafts

Deploy to Heroku

In order for Heroku to be able to run the app correctly, you’ll need to create a file that will tell Heroku to pull the latest version of the theme every time you deploy:

echo 'https://github.com/LordMathis/hugo-theme-nix/' > .hugotheme

The easiest/best way to deploy your app to Heroku is using Git using this buildpack by roperzh:

git init
git add -A
git commit -m 'Initial commit'
heroku login
heroku create --buildpack https://github.com/roperzh/heroku-buildpack-hugo.git
git push heroku master
heroku open

If this fails for some reason, you can manually-specify the buildpack to use in your application’s Heroku dashboard.

…and that’s pretty much it.

Futher customization

Let’s say you already created an empty Heroku app called heroku-app-1, and when you run the heroku create command, it creates a new application called heroku-app-2. If you want to change git repos to point to heroku-app-1, you would simply run the following:

heroku git:remote -a heroku-app-1
git add -A
git commit -m 'initial commit'
git push heroku master

…and now your repo is attached and synced to the correct application, and can delete the other app from your Heroku dashboard.

Fork your own theme

Note: this requires a free GitHub account and some basic knowledge of GitHub.

I wanted to make some changes to the existing theme and decided to reference my own fork of that theme rather than continuing to fail at overriding the existing theme via the methods in the Hugo documentation. In addition to changing github.com to gists.github.com in index.html (which I was actually able to override the normal way), I also wanted to add syntax highlighting to my code using Highlight.js.

Below, I have outlined the steps I took in order to implement Highlight.js and to get slightly-customized theme working properly and deployed to Heroku:

First, I added a new repo called hugo-theme-nix to my GitHub account.

Next, I added the following lines to themes/hugo-theme-nix/layouts/partials/header.html:

<!-- Highlight.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"></script>
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/styles/atom-one-dark.min.css" type="text/css" media="all" />

^ Note that if you don’t include https in the URLs, the script won’t load out of the box, and Chrome will give a very hard-to-see user prompt to “Allow loading of unsafe scripts”.

I then needed to remove all references to the initial theme repo and add my own:

cd themes/hugo-theme-nix
rm -rf .git
git init
git add -A
git commit -m 'initial commit'
git remote add origin https://github.com/oldjamey/hugo-theme-nix
git push --force origin master
cd ../..
echo 'https://github.com/oldjamey/hugo-theme-nix.git' > .hugotheme

Finally, I synced my changes with the Heroku repo and re-deployed my app:

git add -A
git commit -m 'added custom git repo'
git push heroku master

…and bingo-bango. Syntax highlighting and a newly-customizable theme.

Credits – this was a basic amalgamation of the following resources, combined with my own experience:

Leave a Reply