Use selfhosted Staticman with GitLab: Part 1

Static Site Generators, also known as SSG, are trending at the moment. Why? Because you can pre-render a static HTML page with ease. For example I use for each blog post a simple markdown file which then gets rendered into a HTML page. It's like a CMS, only faster and more secure. Since no code runs on the server-side (because there is no such thing in the SSG-universe), no one can hack your site. At least not through your static site 😁

This post is divided in five Parts.

• Part 1 deals with the resources needed and the initial Setup with GitLab
• Part 2 I talk about how to test your staticman-configuration.
• Part 3: Add OAuth, Mailgun, Recaptcha, Antispam (to be written)
• Part 4: Deploy it on your server (to be written)
• Part 5: Integrate it with your Static-Site-Generator (to be written)

Part 1: Selfhosted Staticman

Before we start, I just recapitulate which decisions I took and what the staticman-service is doing for us.

GatsbyJs, Staticman, GitHub, GitLab & Co

I am using GatsbyJs as my Static Site Generator. Feel free to do the same - you might as well chose another solution, for example Hugo. It really does not matter

But what static sites are lacking, you guessed it, are dynamic contents - such as comments for example.

There are some solutions to this, one of them we will talk about today. It's Staticman - the principle behind staticman is very simple.

You host your site on a _GitHub _repository. (Yes I know, the title says GitLab - we'll come to GitLab later.)

• You add the Staticman Bot to your GitHub repository
• You send comments as POST requests to the official Staticman server
• The Server then pushes your comment into your repository
• Your CI/CD Pipeline should do the rest (or you do it manually)
• Optionally an email can be sent as well (to you or the author)

You might wonder how this works and how you can achieve this? Well when you use the official staticman server you would only have to follow the offical documentation. If you want to self host you take a look at its official repository. But as the title suggests, we want to do this with GitLab.

Why GitLab? Well, opposed to GitHub, you can have lots of unlimited private repositories. And you can utilize GitLabs sophisticated CI/CD pipeline. Well and since GitHub has been acquisitioned by Microsoft, some prefer their git without the Microsoft-flavour

At this point you might begin to wonder why you should selfhost staticman when you wanted to ditch serverside code execution in the first place. Granted, that would'nt make much sense but I'm sure you have your reasons!

The Setup

You want to selfhost your commentary system? Then I have a checklist for you:

1) Create a GitLab Account

If you don't have already an account, you should create one. With this account you'll host your repository. I guess you could also selfhost your GitLab - would not make much of a difference.

2) Create another GitLab Account

This one will be your Staticman-Bot.

3) Create your blog-repository

Now create your repository where you want your blog and your comments to be stored. In the root of your repository you need a file called staticman.yml. In that link you'll find an example. We'll cover the gitlabAuth property in step 7.

Now invite your bot into your repository. You'll find that setting in https://gitlab.com/<your username>/<your repository>/project_members. Give him developer access.

You need to unprotect your repository in GitLab, so that your bot can push into the master branch - do it here https://gitlab.com/<your username>/<your repository>/settings/repository under Protected branches.

4) Create a Personal Access Token for your GitLab Bot

Visit your Access Tokens page while being logged in your GitLab Bot and create a new access token:

Name it however you wish, add the scopes api and read_repository and save it. You'll get an access token displayed - note it somewhere, because afterwards you can't view it again. This access token is your gitlabToken.

5) Clone the staticman's repository dev-branch and install it

You'll find the staticman repository here. On the current master branch you would find version 2.0 of staticman. For GitLab compatibility we need v3.0.

So go to your desired location and run:

git clone -b dev https://github.com/eduardoboucas/staticman

This will clone the dev branch of staticman.

Consider hosting your staticman-instance on your localhost first, for testing purposes.

Once you've cloned the repository, you can install it with npm install. I prefer yarn install, tho.

6) Create a RSA privatekey and fill config.json

Staticman requires you to create a privatekey in order to later encrypt stuff like GitLabs application ID and its secret.

Create it with openssl genrsa -out key.pem. You have to copy the content of the resulted key into the config-file of your staticman application (The one you just cloned and installed) - but since its a JSON file, you need to replace every linebreak with a \n - how cumbersome!

Luckily we can utilize awk: awk '{printf "%s\\n", $0}' key.pem > key_json.pem - what happens is, that awk takes each line of a file and appends a \n and puts it out without the linefeed. We then pipe the output into key_json.pem.

We take the content of key_json.pem and put it into config.development.json as the rsaPrivateKey-value. If you dont have that file yet, just copy config.sample.json and rename it accordingly. Remember your gitlabToken ? Put it as the gitlabToken-value.

7) Create a GitLab application ID

This one is optionally, but I would recommend to do that step anyway, since I cannot guarantee that everything will work if you omit this step.

Go to your GitLab account (not your bot account!) and request an ApplicationID. As the callback Url you can enter http://localhost:8000 (depending on where you host your blog). Write down the two strings representing your ApplicationID and your Secret. You'll need them in Part two.

You're ready for part 2

On your journey you've prepared everything for testing your staticman instance. On your inventory you should have:

• A GitLab Account with

• ApplicationID

• Secret

• Another GitLab Bot Account

• A repository for your blog

• With the staticman.yml in the root directory

• In there there should be your gitlabToken and your privatekey

When you're ready, then let's move on to Part 2!

Add a comment