Welcome to static comments

I put some “why” questions here so as to keep focus on the technical setup of the GitLab repo and the optional Staticman API server.

Why static blogs instead of dynamic ones?

• quicker loading time
• better reliability (can handle more request)
• no database needed
• greater control on content, styles and layout

Why static comments?

• allow feedback from visitors
• site owner owns the comment locally (unlike WordPress, Facebook, Disqus, etc)
  • no remote database needed, so no need to worry server errors from third-party commenting services.
  • greater control over the rendering of the comments (allow additional features such as Markdown syntax, and $\KaTeX$ support)
  • more accessible since static comments are incorporated as HTML elements into the post. No JavaScript is required to retrieve the comments, contrary to most third-party commenting services.

Before Staticman’s deployment, another commenting system called Pecosys was already available. However, it’s less convenient to handle visitor’s requests as emails.

The site IRZ (in French) has been migrated from WordPress to Jekyll+Staticman for two main reasons: save time and money.

• each dynamic page took 10 s to load, and he/she had 3500 articles! vs faster static pages
• annual hosting cost of 43€ for WP vs free GitHub Pages hosting

Why GitLab instead of GitHub?

• GitLab CE, as a software, is open source, whereas GitHub is proprietary.
• GitLab has native CI/CD support, which enables automated package builds on the remote server.
• GitLab, as a remote Git host, allows unlimited private repo for every user; GitHub allows this for paid users only.

Why is the significance of Staticman’s GitLab support?

In the past, Staticman was known to support GitHub only. As a result, it’s not entirely independent of proprietary technologies. As one sees in issue #22, such technical restraint stops users from adopting this great commenting system.

With pull request #219, Staticman v3 is now capable of shipping HTML form data to GitLab in the name of a GitLab bot. Since GitLab community edition (CE) is open source, it is, in principle, possible to run an instance of Staticman depending entirely on free software.

Is Staticman secure?

Some users are worried about the security of Staticman.

1. With user’s authorization, it collects only HTML form data and sends a merge request containing the form data in YML format to user’s repo. User’s approval is required as long as moderation: true in staticman.yml.
2. One can set integrate third-party services like Akismet and reCAPTCHA to stop bots and spam.
3. Critical secrets (e.g. OAuth App secret) in config files are encrypted with RSA by a GET request to the /encrypt endpoint, which only do the math and return the result.
4. Under Staticman’s open authentication (OAuth) flow, users’ secrets are never stored nor leaked. The entire project is open source, meaning that anyone can verify the code.
   1. Potential commentators are redirected to GitLab’s site, who actually gets the passwords from them.
   2. In order to post comments, they have to grant the OAuth app some rights (read_user and api) for legitimate reasons:
      • read_user: enable the bot to retrieve GitLab user profile
      • api: for accessing GitLab user profile through API
   3. The OAuth app then responds with a redirect URI, which
      • points back to the static site, and
      • contains a code parameter at the end of the URL.
   4. The static site sends a GET request to /encrypt code as oauth-token.
   5. The static site includes the oauth-token in the form data.
5. Git repo owner has total control over the comments just like the posts. He/she can remove whatever he/she dislikes.

Since the oauth-token never expires, client-side browser settings need to

N.B.: In this section, “Staticman” refers to the Node.js app (available for download on GitHub) rather than the public API instance, which is exclusively accessible to the package owner himself. In case of concerns over the server, I suggest running your own API instance to ensure freedom.

Why did I write my own guide?

Simple reason: I couldn’t find a simple and comprehensible guide for users who don’t know Node.js. Therefore, I decided to write my own guide targeting at end users to give them a general idea about

1. the client-side repo setup
2. the server-side Staticman v3 API setup

Until now, Staticman’s project owner, who has set up the public development instance of Staticman v3 API server didn’t inform users of the details of the GitLab bot. Nicholas Tsim, who developed Staticman’s GitLab support, simply said “it can be any user”. However, after setting up my own user, I encountered difficulties in understanding the whole setup, especially the role played by the GitLab bot and its raison d’être.

Moreover, unlike the official documentation on Staticman’s site, Nicholas Tsim’s setup guide has mixed up GitLab repo config with API server config in one section. On one hand, this serves as an informative first-hand source of information for other developers. On the other hand, users might find it a bit difficult to get an overall idea about the whole setup.

Despite the errors encountered while I was following his guide, I was indebted to his assistance over these few weeks.