I’ve written that Jekyll, the ultrahip static site generator, is a great way to make academic Web sites. But once you’ve built your site with a static site generator, you’ll need a nice way to automatically update your public-facing site whenever you make changes. This is doubly true if you’re making a site with multiple authors: a research group site, say, or page for a course or seminar.
GitHub Pages is a nifty idea: it builds and updates your site every time you git push to GitHub. But it uses GitHub’s own servers. For many reasons, you probably want to host your academic site on your own department’s Web server.
I wrote Hooknook as a way to get slick GitHub-Pages-like automatic updating on your own server.
How it Works
It’s easy to automate the deployment of a Jekyll site. I usually write a Makefile target, called deploy, that builds my site and rsyncs it to my department’s servers. It looks like this:
deploy: clean site
rsync --compress --recursive --checksum --itemize-changes \
--delete -e ssh _site/ $(CSEHOST):public_html/home
At this point, I can just type make deploy to upload my site to the servers. But that’s no fun, and it’s unlikely to fly with technology-adverse advisors who might also need to edit the site. They probably can’t even be coaxed to install Jekyll. That’s where Hooknook comes in.
Hooknook works by running a small, special-purpose server that listens for messages from GitHub. For me, this is an otherwise-useless Mac mini sitting under my officemate’s desk. If you don’t have a little utility server like this, ask around: someone you know probably does.
Point a GitHub Webhook for your site’s repository at your Hooknook instance. Every time you push to the repository, Hooknook will pull from it and run make deploy. Magical!
See the README for more details about how to set up your own Hooknook server.
Getting Fancy
As anyone who’s ever debugged a cron job knows, running background tasks “automatically” can be maddeningly opaque. To help with diagnosis, Hooknook keeps the output of every deployment in a timestamped log file under ~/.hooknook/log/. Check in there if something goes wrong.
Hooknook can even show you these logs in a convenient Web interface. You configure Hooknook to allow a whitelist of GitHub usernames. Any of these users can then head to the server in a browser, log in with their GitHub credentials, and see a list of logs for the most recent deployments.
It’s so easy that even a professor could do it!