Setting up a Staticman server for comments on Jekyll and static sites# 31 Dec 2017 by Sean
I’m running Staticman for comments on this blog. If you’re using the main/public instance of the app, this requires you to add Staticman as a collaborator to your site repo, which I decided I’d rather not do… so I’ve run up my own instance of the application, and this is a quick look at how I did it.
There’s one big assumption I’m making about setting this up. I’m lazy and cheap AF, so I run most of my apps on Dokku, which is effectively a privately hosted Heroku replacement without all the limitations on the free tier. This means I can export a few environment variables, set up a subdomain and certificates, and
git push my apps into production.
Kicking the tires locally before deploy
This is probably unnecessary–the app works. But as I was getting ready to push it live, I really wanted to see if I could get it working on my local machine. If you’re hosting your site locally for testing with
hugo server or
jekyll serve and then run up Staticman locally, you can definitely do it, but you’ll still need to follow the setup and requirement steps for Staticman (including creating a GH bot account with a token, and adding it as a collaborator to your repo). Also, don’t forget to change your form’s endpoint and branch if necessary.
The thing that caught me out here was the presence of the
.env file in the repo. For me, that was an indicator that the repo was using dotenv (which is the JS equivalent of the Ruby gem of the same name). Turns out it’s not… that’s there for the Docker stuff. For local development, just follow the instructions and copy
config.development.json and input your secrets there. Just be sure not to track it into git.
You should also create a new Github user account, just for this application (you could use an existing one, but best to keep things clearly separated). I’ve created “flyinggrizzly-staticman” so I know exactly what it is. This is the user you should create a Github token for. Hang on to that token, because you’ll need it here, and also for actual deployment (you can regenerate in between steps if you want). And do yourself a favor and disable all notifications for this user if they’re going into your email inbox. You’ll be friggin bombarded with PR notification before long otherwise.
One last thing–the Staticman docs refer to the SSH key and RSA private key interchangably. They expect you to create it using
ssh-keygen per the Github docs, but the config looks for it under
rsaPrivateKey in the application, or
RSA_PRIVATE_KEY in the environment.
Prep application for deployment
Staticman follows the 12 Factor approach to config, and so stores sensitive keys, etc, in the environment.
If you’re deploying to a Dokku server, here’s the checklist:
- create the app in Dokku (duhh)
- set up a subdomain for it (recommended in case people are poking at your form before using it; make it something sensible like
comments.flyinggrizzly.ioin my case)
- set up SSL for it with Dokku’s self-signed/Let’s Encrypt cert shuffle
- supply all the environment variables (you should supply the RSA key, and Github token, at the very least…)
- push app to production
Hooking up your new instance to your site
When you’re ready, you should do these things:
- invite your new Staticman Github user as a collaborator on your repo
- do NOT go into that user elsewhere and accept the invite manually
- programmatically accept that invite by hitting the Staticman API’s
- if you see “Invitation not found”, either your user isn’t set up, in the app (check the token), you haven’t invited it to collaborate on the repo, or you already accepted the invite manually (this threw me way off)
- update your comments form to use the new endpoint
- post a comment to test!
Ideally, things should be working. If they’re not… not sure. I didn’t have any problems at this point, but if you run into an issue, leave a comment and I’ll help if I can.
Now, it’s time to party!