One-click deploy to Heroku, no installation needed

[VincentTam]

Originally posted in https://github.com/pacollins/hugo-future-imperfect-slim/wiki/staticman.yml, credits to @pacollins for reviewing and organizing my guide with headers for readability.

Setting up your own Staticman API instance on Heroku

1. Open a Heroku account.
2. Click the "deploy to Heroku" button in Staticman's README: https://github.com/eduardoboucas/staticman/.
3. Input your own app name, so that the URL for your app would be yourapp dot herokuapp dot com.
4. 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.

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.

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.

   

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)

To store a multi-line RSA private key, you may first input the environment variable name. Then click the pen icon 🖊️ 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.

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

[lionxlife]

Hey, thanks for this guide. It's been more helpful than the official docs, however it's still really confusing. I will point out the issues, hopefully they can be clarified to the benefit of future users, thanks.

(1): Webhook URL: I tried <your-api>/v1/webhook. Where does <your-api> come from? It appears to me that this should be: https://mystaticmaninstance.herokuapp.com/v1/webhook, where everything before the /v1/webhook should be same as yourapp dot herokuapp dot com of step 3 under Setting up your own Staticman API instance on Heroku (above)

(2): going to Jan Hajek's article about Staticman v3 is barely useful. There's only some parts of that you need. Perhaps:

• (a) the permissions listed should be done in the app setup? I didn't need to do anything related to GitHub Developer Program (he indicates the permission takes place before app registration? Different things for different times?)
• (b) the app registration, App ID & variables are useful; the multiline stuff is not applicable (probably) if you're doing the 1-click heroku, since he is using Azure.
• (c) the RSA_PRIVATE_KEY variable can be generated in your browser (https://travistidwell.com/jsencrypt/demo/) but where does the PUBLIC part go??

(3): for the config table, I assume you DONT need all 6 variables, just 4 - NODE_ENV, RSA_PRIVATE_KEY, then EITHER the 2 GITHUB one or GITLAB one depending on which you used for Git Provider setup section.

(4): I see Don't forget to install this app to the GitHub repo for your static website after having finished the setup in the next section. mentioned, but this really should be the final section. Big.

[VincentTam]

1. If you deploy it to Heroku, <your-api> would be https://{your_app_name}.heroku.com. Note that there're other node.js app hosts, like M$ Azure, DG Ocean, etc.
2. I'm sorry to hear that. His article inspired this post though. If possible, generate any cryptographic keys with locally installed free (as in "freedom") software. It's hard to know the technical details behind the scripts on a site in a browser.
3. That's why I added a pair of parenthesis "(for ...)" for GIT**B_*. I use both GitHub and GitLab for person & demo purposes (for personal math blog and demo). The above table is the minimum of the API environment variables needed for deploying on Heroku with different Git providers.
4. Thanks for suggestion. I put that (installation of your (private) GitHub App to your GitHub repo) at the end of the section for GitHub setup since
   • GitLab Pages users aren't concerned about that
   • I separate front-end & back-end setup for a clear content organization.