[Staticman](https://staticman.net) is a comment engine for static sites that was
developed by [Eduardo Boucas](https://github.com/eduardoboucas/). Unlike Disqus
and other similar comment engine, all content is hosted directly on your site
rather than on someone else's server.

*Note:* If you need any assistance with Staticman, please don't hesitate to
contact @VincentTam on [GitHub](https://github.com/VincentTam) or [GitLab](https://gitlab.com/VincentTam).
Additionally, check [his blog](https://vincenttam.gitlab.io/) for more ways to
contact him.

<!-- TOC titleSize:2 tabSpaces:2 depthFrom:1 depthTo:6 withLinks:1 updateOnSave:1 orderedList:0 skip:0 title:1 charForUnorderedList:* -->

* [Setting up your own Staticman API instance on Heroku](#setting-up-your-own-staticman-api-instance-on-heroku)
  * [Git Provider setup](#git-provider-setup)
    * [GitHub](#github)
    * [GitLab.com](#gitlabcom)
    * [Framagit](#framagit)
  * [Config variables via Heroku's online dashboard](#config-variables-via-herokus-online-dashboard)
* [Initiate in `config.toml`](#initiate-in-configtoml)
* [Initiate in `staticman.yml`](#initiate-in-staticmanyml)
* [Optional](#optional)
  * [reCAPTCHA](#recaptcha)
  * [Prevent Excess Branches (GitHub Only)](#prevent-excess-branches-github-only)
<!-- /TOC -->

# Setting up your own Staticman API instance on Heroku

1. Open a Heroku account.
1. Click the "deploy to Heroku" button in Staticman's README: https://github.com/eduardoboucas/staticman/.
1. Input your own app name, so that the URL for your app would be `yourapp dot herokuapp dot com`.
1. Leave the Heroku page open, and proceed to the next stage.

## Git Provider setup

Follow either one of the three sub-sections.

### GitHub

Create a GitHub apps: https://docs.github.com/en/developers/apps/creating-a-github-app.  You can leave the default values unchanged, except for the mandatory fields.

- Homepage URL: for display purpose only for your GitHub App page
- Webhook URL: I tried `<your-api>/v1/webhook`.
- Contents: **Read & Write**
- Pull Requests: **Read & Write**

Then generate a RSA keypair at the bottom of the page.  A RSA private key would be automatically downloaded.

I recommend making this app private and personal.

Don't forget to install this app to the GitHub repo for your static website after having finished the setup in the next section.

To know more, you may see [Jan Hajek's article about Staticman v3](https://hajekj.net/2020/04/15/staticman-setup-in-app-service/).

Note: There is no need to hit the `/connect` route in Staticman v3 because we're using a GitHub App instead of a GitHub bot account here.

### GitLab.com

1. Create a GitLab bot account and obtain a personal access token with scopes `api` and `read_repository`.

    ![required scopes for GitLab bot](images/staticman/gitlabBot.png)

2. Add your GitLab bot account as a **developer** to your GitLab repo for your static website.  This can be done by going to your project, then **Settings → Members → Invite member**, and finally searching for your GitLab bot.

Note: There is no need to hit the `/connect` route in Staticman v3 because once a GitLab account is invited to a GitLab repo, it can start committing to the GitLab repo.  Unlike GitHub, there's no need for the invited GitLab account to accept the invitation.

### Framagit

Since Framagit is a fork of GitLab, the overall setup is the same as that for GitLab. The only difference is that you need to add an extra environment variable `GITLAB_BASE_URL` with value `https://framagit.org`.

## Config variables via Heroku's online dashboard

Here're the necessary variables to get the instance running.

| variable | explanation |
| :--- | :--- |
| `NODE_ENV` | `production` |
| `RSA_PRIVATE_KEY` | RSA private key generated by `openssl genrsa -out key.pem` |
| `GITHUB_APP_ID` | GitHub App ID (for v3 with a GitHub App) |
| `GITHUB_PRIVATE_KEY` | RSA private key downloaded from GitHub (for v3 with a GitHub App) |
| `GITLAB_TOKEN` | token of your GitLab bot (for v3 with a GitLab bot) |
| `GITLAB_BASE_URL` | URL of your custom GitLab instance (for v3 with a custom GitLab instance other than GitLab.com) |

![Heroku online dashboard](images/staticman/herokuDashboard.png)

To store a multi-line RSA private key, you may first input the environment variable name.  Then click the pen icon :pen: on the right in order to show a text area for editing.  A simple copy and paste would do, as shown in the screenshot below.

![RSA private key setup](images/staticman/rsaPriv.png)

To know more about the API variables, the best way is to read https://github.com/eduardoboucas/staticman/blob/master/config.js.

# Initiate in `config.toml`

Complete the Staticman parameters within the [`config.toml`](config.toml#paramsstaticman).

```toml
[params.staticman]
  enabled             = false
  api                 = ""  # No Trailing Slash
  gitProvider         = "github"
  username            = ""
  repo                = ""
  branch              = ""

  [params.staticman.recaptcha]
    siteKey           = ""
    encryptedKey      = ""
```

<dl>
	<dt>enabled</dt>
	<dd>Sets whether to use Staticman for comments.</dd>
	<dt>api</dt>
	<dd>Defines link to Staticman API.</dd>
	<dt>gitProvider, username, repo, & branch</dt>
	<dd>Defines the path to post comments to.</dd>
	<dt>siteKey & encryptedKey</dt>
	<dd>Defines the keys required for reCAPTCHA to work.</dd>
</dl>

---

# Initiate in `staticman.yml`

Within the `exampleSite` directory, there is a Staticman config file named
`staticman.yml`. This file should be moved to the root directory of your site
(the same location as your `config.toml`).

<dl>
	<dt>branch</dt>
	<dd>Sets which branch to commit comments to.</dd>
	<dt>moderation</dt>
	<dd>Sets whether to moderate comments through pull requests or not. Default to <code>true</code>.</dd>
	<dt>reCaptcha: enabled</dt>
	<dd>Sets whether to enable reCAPTCHA.</dd>
	<dt>reCaptcha: siteKey & encryptedKey</dt>
	<dd>Defines the keys required for reCAPTCHA to work. Please see the <a href="#recaptcha">Optional: reCAPTCHA</a> below for additional information.</dd>
</dl>

If you are working on GitLab/Framagit and you have set `moderation: false`,
depending on your `branch`, you might need to take these additional steps.

- For protected branches (e.g. `master`), go to **Settings → Repository → Protected Branches** and permit the Staticman bot to push against that branch.
- For unprotected branch (GitHub's default), there are no additional measures needed *no* measures needed.

# Optional

## reCAPTCHA

To prevent spam, please enable [reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html).
As of right now, you should specifically use [reCAPTCHA v2 Checkbox](https://developers.google.com/recaptcha/docs/display).

1. Register a new site for [reCAPTCHA](https://www.google.com/recaptcha/admin/create).
2. Select **reCAPTCHA v2** then **"I'm not a robot" Checkbox**.
3. Add your `baseurl` to **Domains**. If you would like to test locally, add `localhost`.
4. Copy your **Site Key** and paste it into both the `config.toml` and `staticman.yml`.
5. Encrypt your **Secret Key** by hitting the Staticman API at `https://<your-api>/v3/encrypt/<your-site-secret>`. An example using the default endpoint would be `https://<your-api>.herokuapp.com/v3/encrypt/exampleSecretKey`.
6. Copy your newly encrypted secret key and paste it into both the `config.toml` and `staticman.yml`.

:warning: Do **not** push your *Secret Key* to your repository as this is a security risk. You **should** push your *Encrypted Key* from the Staticman API.

## Prevent Excess Branches (GitHub Only)

To prevent excess branches (from comment pull requests) from piling up, please go to your project, then **Settings → Webhooks**.

1. Set **Payload URL** to the endpoint set in your `config.toml`, say `https://<your-api>.herokuapp.com`.
2. Add `/v1/webook` to the end of the **Payload URL**. For example, `https://<your-api>.herokuapp.com/v1/webhook`.
3. Set **Content type** to **application/json**.
4. Select **Let me select individual events.** and then select **Pull Requests**.
5. Ensure **Active** is checked.

For further reference, check the [Staticman documentation for webhooks](https://staticman.net/docs/webhooks).

*Note:* This is unnecessary with GitLab and Framagit as there is a checkbox for deleting the source branch next to the **Merge** button in each pull request.