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
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
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.
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
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
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
<!-- Highlight.js --> <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.9.0/highlight.min.js"></script> <script>hljs.initHighlightingOnLoad();</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: