Staticman GitHub App support

[wini3d]

More on a feature request. I was wondering if you are planning to have this supported or if it is already, is there a doc?

https://github.com/apps/staticman-net

Also, any guide on how to setup your own heroku staticmanlab instance?

[daattali]

Static man is already supported for comments. What feature exactly are you requesting? I try not to bloat this theme with too much info specific to one small feature in it (that is - I prefer not to have huge docs sections dedicated to staticman)

[wini3d]

Yes, using the staticman github app v3 instead of the staticmanlab collaborator v2 which I read has lesser quota.

[daattali]

I'll defer to @VincentTam - he brought in staticman and would understand the question better

[VincentTam]

Yes, using the staticman github app v3 instead of the @staticmanlab collaborator v2 which I read has lesser quota.

@wini3d Since I ported Staticman Integration from Minimal Mistakes in #440, this theme has been using Staticman v3 API scheme, which has been merged in eduardoboucas/staticman#219. After several months, the action URL was moved into JS in #521 to avoid spam bots.

beautiful-jekyll/js/staticman.js

Line 14 in c74b503

var endpoint = '{{ sm.endpoint | default: "https://staticman3.herokuapp.com/v3/entry/github/" }}';

Since I've (and I'll) never used GitHub Apps (for reasons listed in my earlier comment eduardoboucas/staticman#299 (comment).), I'll leave interested users to write the instructions for using GitHub Apps. Be aware that

1. One can use this theme for either the new GitHub Apps or the legacy authentication method. (See the explanations in the following paragraph.)
2. The official production and development API instances aren't always stable, as reported in 503 error using v3 endpoint eduardoboucas/staticman#307.

Whether the app version is used or not, the v3 API scheme and the input and output data format has not been altered by eduardoboucas/staticman#255. As a static blog theme, it doesn't care the actual functioning of the API server—that's a Staticman (as a node.js app) issue. Instead, we handle data files received from the API server, and render them into HTML elements to be displayed. Staticman's support for GitHub Apps eduardoboucas/staticman#255 has neither changed the input/output data structure nor the POST URL structure introduced in eduardoboucas/staticman#219, based on which #440 was made. Therefore, I see no need to modify our Jekyll-HTML template in view of eduardoboucas/staticman#255.

My bot @staticmanlab, forked from the dev branch after eduardoboucas/staticman#219 was merged, supports both v2 and v3. That's in line of the app's author's original intention in eduardoboucas/staticman#243 (comment).

Also, any guide on how to setup your own heroku staticmanlab instance?

That's off-topic here, for the reason I've explained above. You may go to the official Staticman repo to start an issue there—you've done that in eduardoboucas/staticman#310, or leave a comment under my blog article Staticman API Hosting 2018.

---

⚠️ Remarks:

🚫 Staticman v2 no longer works on official production instance, as reported in eduardoboucas/staticman#306.
ℹ️ PR eduardoboucas/staticman#255, whose aim is to resolve feature request eduardoboucas/staticman#243 and to the API limits reported in issues eduardoboucas/staticman#222 and eduardoboucas/staticman#227, isn't scalable as the spam problem reported in eduardoboucas/staticman#298 still concerns the GitHub Apps version. (See the part about @zinefer's repo.) Since the real source (spam) that sucks up the API quota has not been resolved by the adoption of the GitHub Apps technology, I don't see any rationale to break the existing legacy authentication support in favor of this proprietary service, as a GitLab user.

[wini3d]

My bot @staticmanlab, forked from the dev branch after eduardoboucas/staticman#219 was merged, supports both v2 and v3. That's in line of the app's author's original intention in eduardoboucas/staticman#243 (comment).

Thank you. So are you suggesting to fork the merge from eduardoboucas/staticman#219 to have the same exact copy that your staticmanlab herokuapp is using?

[VincentTam]

In my linked guide for setting up Staticman API, there's a comparison between my deploy branch and the dev branch: eduardoboucas/staticman@dev...VincentTam:deploy. I'll update that because I meant the dev branch by the moment of writing the post: eduardoboucas/staticman@55d1430...VincentTam:deploy. This comparison summarises my customization of Staticman's code last year.

The great thing about a Git branch is that it gives a short reference name to a feature/modification, so that you can easily make comparisons. You don't need to follow every step in my post, like

echo "web: npm start" > Procfile

Braching against the deploy branch will do. You might try eduardoboucas/staticman#301 if you want.

[wini3d]

Thanks @VincentTam . I just tried your deploy branch, the invite went successfully but getting 500 Internal Server Error when posting comments. I just changed the form action url from your staticman3 to my heroku url.

eduardoboucas/staticman#311

[daattali]

I'm going to close this issue because it's not relevant to beautifuljekyll - feel free to continue this discussion privately or in another repository where it makes sense :)

[VincentTam]

Thank you. So are you suggesting to fork the merge from eduardoboucas/staticman#219 to have the same exact copy that your staticmanlab herokuapp is using?

@wini3d I had lost my concentration for a few seconds browsing various issues. I should have answered your question in a GitHub issue under Statimcan's repo since that's a question about Staticman's API rather than this theme's Staticman integration.

To understand what type of questions about Staticman is on-topic here, you may think about an ATM. Staticman's API is like the ATM's interface. A static blog theme deals with stuff "in front of" the interface (e.g. conversion of HTML form data into an appropriate POST request), and it doesn't care about what's "behind the ATM's interface" (e.g. how the POST request is converted to a Git commit object).

[wini3d]

Thanks, I understand that and I have updated some findings here. We can move this discussion now to that issue.

[VincentTam]

I'm going to close this issue because it's not relevant to beautifuljekyll - feel free to continue this discussion privately or in another repository where it makes sense :)

@daattali Documentation request/questions for setting up a site using this theme with an existing Staticman v3 API is on-topic here, since there's some theme-specific parameters in each theme with Staticman support. Here's the right place to place to ask questions/discussions about these parameters.

beautiful-jekyll/_config.yml

Lines 130 to 138 in 96c2508

	staticman:
	repository : # GitHub username/repository eg. "daattali/beautiful-jekyll"
	branch : master # If you're not using `master` branch, then you also need to update the `branch` parameter in `staticman.yml`
	endpoint : # URL of your own deployment, with a trailing slash (will fallback to a public GitLab instance) eg. https://<your-api>/v3/entry/github/
	reCaptcha:
	# reCaptcha for Staticman (OPTIONAL, but recommended for spam protection)
	# If you use reCaptcha, you must also set these parameters in staticman.yml
	siteKey : # Use your own site key, you need to apply for one on Google
	secret : # ENCRYPT your password by going to https://staticman3.herokuapp.com/v3/encrypt/<your-site-secret>

I interpret the question on the top in this way: "Does the above parameters support the GitHub Apps version of Staticman? Does this repo's README cover this?". That's surely on-topic here. Since this repo's README doesn't cover the GitHub Apps version of Staticman, a normal user of this theme might be in doubt of this theme's capability to support that. As a result, it would be good to see some volunteer updating the README regarding the the GitHub Apps version of Staticman. I've never used that, so I have to leave that to others.

More on a feature request. I was wondering if you are planning to have this supported or if it is already, is there a doc?

https://github.com/apps/staticman-net

Since the request for README update has not yet been addressed, it would be better to re-open this until the README says clearly that the GitHub Apps version of Staticman is supported by this theme.

The only off-topic part here is the question about setting up own API instance. I've pointed that out in my previous comment.

My bot @staticmanlab, forked from the dev branch after eduardoboucas/staticman#219 was merged, supports both v2 and v3. That's in line of the app's author's original intention in eduardoboucas/staticman#243 (comment).

I wrote the above paragraph in my previous comment in order to clarify the following claim, which is not entirely valid. I wasn't aware that would trigger another question.

Yes, using the staticman github app v3 instead of the staticmanlab collaborator v2 which I read has lesser quota.

[daattali]

@VincentTam do you know if there are any updates on staticman? I just checked https://staticman.net/ and there is no mention at all of a v3 API, only v2. If v3 isn't official or recommended yet, I'd like to close this issue

[daattali]

As far as I understand, v3 that was discussed here is not an official recommendation. Due to lack of response here, I'm closing this issue. If someone wants to raise this issue again with more information, please do

[VincentTam]

@VincentTam do you know if there are any updates on staticman? I just checked https://staticman.net/ and there is no mention at all of a v3 API, only v2. If v3 isn't official or recommended yet, I'd like to close this issue

@daattali I'm sorry for my lack of response. I suffered from game addiction during the lockdown. Learning C# now, I'm a little bit more active on Git* than before.

As far as I know (about the node.js app one year ago), the idea of a public instance isn't scalable. When everybody uses it, the it can get "congested". It's true that the official website has no mention about the newly introduced API variables in v3. The file config.js in the node.js app lists some server-side API variables. I personally learnt everything from the PR supporting GitLab.

Regarding the question on "recommendation", here's one from the project's maintainer.

This has been resolved with # 319. We are dropping support for the public Staticman instance and are recommending that all users host their own instance. The simplest way to do this is to click the "Deploy to Heroku" button in the README which will allow you to host your own instance for free without the reliability concerns of using a singular public instance. The public instance will remain running for the time being, though I strongly recommend everyone move away from it.
https://github.com/eduardoboucas/staticman/issues/317#issuecomment-565250060

I believe that he, as the maintainer, would recommend a version of the app with recent bug fixes. Documenting recent changes takes time. If the maintainer/owner doesn't have the time and effort to do it, and a 3rd-party person doesn't have the energy to test all the features, it's hard for him/her to come up with an encyclopedia-like "documentation".

[daattali]

I understand those concerns, but I still would be a little hesitant to use a new version that isn't at all mentioned on the official site whatsoever.

[VincentTam]

@wini3d @daattali Sorry I'm eating my words again. Due to the quoted comment from the app's maintainer, I'm going to submit a PR for a README update about the GitHub App setup on a custom Heroku app instance.

I've found the motivation to try out the GitHub App, thanks to a clearly-written blog article https://hajekj.net/2020/04/15/staticman-setup-in-app-service/. Here's some screenshots showing my successful setup.

---

Staticman's README : https://github.com/eduardoboucas/staticman

Click the deploy button inside , and configure the necessary variables in the popped up Heroku page in order to start Staticman with no installation.

Screenshot of the RSA_RPIVATE_KEY variable.

Successful example: VincentTam/TestStaticmanLab#95

---

Remarks: If you're using Heroku's online dashboard, simple copy-and-paste the RSA private keys for the config variables RSA_PRIVATE_KEY and GITHUB_PRIVATE_KEY would do. There's no need to do the manual replacement of the newline character \n with the two-character string "\n". I tried that in following the linked article and I ran into an InvalidAsn1Error.

After removing all "\n" as shown in the screenshot of the text area for RSA_PRIVATE_KEY in Heroku's online dashboard, I got pass this error. The RSA_PRIVATE_KEY config vars ...following the green time09:21:01.49and the line containingpath="/v3/encrypt/nimportquoi"` at the bottom show that I've successfully fixed the error.