Update docs to cover v3, Heroku, spam handling, email notifications #13

alexwaibel · 2021-01-04T05:45:18Z

I threw together some updated docs:

Removed references to the public instance
Removed broken demo links for now (hopefully we can find time to get this running again later)
Update config references making sure all keys in the schema are documented
Rewrote overview and added a diagram to clarify the purpose of Staticman and general flow
Reworked getting started guide to include v3 and instructions on setting up Heroku instances
Added instructions for spam handling (moderation, reCAPTCHA, Akismet)
Added instructions for email notifications

I'd love some review on this. I'll mention the PR in some of the existing threads requesting updated docs.

I have a corresponding PR going up on Staticman repo with some Heroku app manifest changes that should make Heroku deployments more straightforward for new users as well as some GitHub dependency updates.

alexwaibel · 2021-01-04T06:20:15Z

_sass/base/_reset.scss

@@ -20,7 +20,11 @@ body {
   	line-height: 1;
 }

-ol, ul {
+ol {


Without this change and the above deletes in _list.scss, ordered lists wouldn't show any numbers when generated from the markdown text. Not sure if there's a better way to fix it

LordAmit · 2021-01-05T02:35:03Z

docs/getting-started.md

+
+Forms on your static site should `POST` to:
+
+`{STATICMAN_BASE_URL}/v3/entry/{GIT_PROVIDER}/{GIT_PROVIDER_USERNAME}/{REPO}/{BRANCH}/{property (optional)}`


It is stated that Option 1. Authenticate as a GitHub application* is the recommended approach. It uses /v1 however. In that case, will user use the same format for POST, i.e., replace v3 with v1 or the URL format will also change? This needs some clarification in my humble opinion.

Also, is the GIT_PROVIDER_USERNAME the name of the Bot? Or name of the repository owner?

GIT_PROVIDER_USERNAME is the name of the repository owner, similar to how github links are structured.

LordAmit · 2021-01-05T02:39:23Z

docs/getting-started.md


-You can use the [sample config file](https://github.com/eduardoboucas/staticman/blob/master/staticman.sample.yml) as a starting point and check the [available configuration parameters](/docs/configuration) for more information.
+This is the recommended way to authenticate with GitHub. This method will give the most control over what Staticman can and can't access.


even though this (v1) is the recommended approach, almost all the examples later on in Getting Started are based on v3, which may potentially confuse user. My suggestion: either use v3 examples and make the option 2 recommended, or continue using option 1 as recommended and give examples based on v1.

@LordAmit To clarify this further, v3 is the current API version and is thus the recommended path to use except in the case of the webhook endpoint. It's on my plate to bring the webhook endpoint up to speed with everything else, but for now it's stuck using /v1.

Again, this is only for the webhook callback. All other API calls should be using v3 currently.

LordAmit · 2021-01-05T02:42:42Z

docs/getting-started.md

+  - Pull Requests: `Read & Write` - Necessary to merge pull requests
+  - Subscribe to `Pull request` events
+1. Generate a private key for the app and note it down along with your app ID.
+1. Install the app on your GitHub account. You can limit its access to only the repo from which you host your static site


I use a setup of two repos, one that contains source and the other which contains the deployment. In this case, we are probably referring to the source version, since it will contain _data. Maybe adding a source version of static site will make it more specific.

LordAmit · 2021-01-05T02:45:58Z

docs/getting-started.md

+
+#### **Option 3. Authenticate to GitHub using a personal access token on your main account**
+
+This option is not recommended as it gives Staticman direct and complete access to your primary GitHub account. Simply, create a personal access token on your primary account.


I think we should add more clarification here. How about,

This option is not recommended as it gives Staticman direct and complete access to your primary GitHub account. In the unfortunate incident where your Staticman instance is compromised, it will get full access to all your repositories, private and public alike as well as you account and may result in irreversible damage across repositories and possibly organizational repositories you are member of. If you still want to proceed, start by creating a personal access token on your primary account.

maybe it is supposed to be {GIT_PROVIDER/GIT_PROVIDER_USERNAME} instead of {GIT_PROVIDER_USERNAME} ?

LordAmit · 2021-01-05T02:48:10Z

_data/apiConfig.json

@@ -63,14 +111,14 @@
  {
    "doc": "RSA private key to encrypt sensitive configuration parameters with.",
    "docExample": "rsaPrivateKey: \"-----BEGIN RSA PRIVATE KEY-----\\nkey\\n-----END RSA PRIVATE KEY-----\"",
-    "default": null,
+    "default": "",
    "env": "RSA_PRIVATE_KEY",


For me, this is a bit confusing. User will be creating a rsaprivatekey in heroku deployment, and will provide the private key contents there. What about the RSA_PRIVATE_KEY? Where is it expected to be used?

I'm not quite sure what you mean, but I'll try to clarify. This default empty string is just to avoid an exception. The user is still expected to supply this RSA_PRIVATE_KEY, either as an environment variable (i.e. heroku vars) or in the config json directly.

It's needed when you have encrypted secrets in the site config such as your recaptcha key.

LordAmit · 2021-01-05T02:49:43Z

Hello @alexwaibel ! Fantastic level of detail! I have added some comments based on my understanding. I hope these will be helpful for making the doc even better. Thank you so much for the effort. 😄

VincentTam · 2021-02-10T16:21:52Z

I wonder what is blocking the merge of this PR. An update on the official site will clear a large part of users' doubts.

eduardoboucas

Looks great. Apologies for the delayed response.

alexwaibel · 2021-02-12T09:04:53Z

Thanks for the review folks. I got some free time over the holiday break to get to this finally, but quickly got busy with work afterwards

alexwaibel · 2021-02-12T09:23:27Z

Updating the webhook endpoint to v3 will hopefully clarify a lot of the confusion. hispanic made great progress on that front, but there's still some work to do wrapping up his PR.

VincentTam · 2021-02-12T14:12:20Z

Excuse me I was so excited to see v3 gets into the docs that I forgot to proofread the info. I'm going to raise a few issues about the errors that I've found.

lionxlife · 2021-05-19T03:37:52Z

docs/getting-started.md

-## Step 3. Hook up your forms
+1. <a href="https://docs.github.com/en/free-pro-team@latest/developers/apps/creating-a-github-app" class="cta">Create a new GitHub application</a>. Ensure you use the following:
+  - Homepage: `"https://staticman.net/"`
+  - Webhook URL: `"{STATICMAN_BASE_URL}/v1/webhook"` - e.x. `"https://mystaticmaninstance.herokuapp.com/v1/webhook"`


Thank you for the much needed update to the documentations. I was hoping this would be smooth... but alas it is not to be. So I'm just going through this and it already mentions a heroku instance already set up, but there's nothing about it since this is step 1!

I'm in heroku, which I just setup, but maybe I need to setup something else in heroku as well to get this instance name. Maybe it's in the later steps, but that doesn't make sense since it would be done later, there's no reason why you would have this URL at this point.

Confused.

alexwaibel added 19 commits December 30, 2020 18:11

Add gemfile, update readme info

b23cc84

Update config documentation to match dev branch configs

e09bdf7

Spelling fixes

3a18ba1

Update overview page

a2860ad

Update install instructions

70b261e

Reorder pages

e0fe001

Temporarily remove broken demo

53c02f3

Remove another demo reference

9467ab8

Clarify staticman setup instructions

bf0a203

Rework install instructions into listed steps

c508b8d

Add spam detection docs

80713f4

Add docs for email notifications

9e50791

Remove reference to unused public instance

50c5fb4

Add webhook note to notifications

5c2f6ab

Add opt-in info to notification page

0a600e3

Add further app auth instructions

a1e30c8

Fix link styles in ordered lists

0c799bf

Fix more link formatting

1028925

Fix typo

34a85f4

alexwaibel requested a review from eduardoboucas January 4, 2021 05:45

This was referenced Jan 4, 2021

Update GitHub app auth flow, migrate docs to website eduardoboucas/staticman#400

Open

Fix documentation eduardoboucas/staticman#367

Open

Update Documentation and App Service Status eduardoboucas/staticman#312

Open

alexwaibel commented Jan 4, 2021

View reviewed changes

LordAmit reviewed Jan 5, 2021

View reviewed changes

VincentTam mentioned this pull request Feb 2, 2021

Improve documentation on running self-hosted API eduardoboucas/staticman#110

Closed

eduardoboucas approved these changes Feb 10, 2021

View reviewed changes

alexwaibel merged commit d1174fe into master Feb 12, 2021

alexwaibel deleted the aw-self-hosted-info branch February 12, 2021 09:25

VincentTam mentioned this pull request Feb 19, 2021

Remove all references to official public Staticman API instance. mmistakes/minimal-mistakes#2831

Merged

lionxlife reviewed May 19, 2021

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs to cover v3, Heroku, spam handling, email notifications #13

Update docs to cover v3, Heroku, spam handling, email notifications #13

alexwaibel commented Jan 4, 2021

alexwaibel Jan 4, 2021 •

edited

Loading

LordAmit Jan 5, 2021

LordAmit Jan 5, 2021

alexwaibel Feb 12, 2021

LordAmit Jan 5, 2021

alexwaibel Feb 12, 2021

LordAmit Jan 5, 2021

LordAmit Jan 5, 2021

LordAmit Jan 5, 2021

LordAmit Jan 5, 2021

alexwaibel Feb 12, 2021

LordAmit commented Jan 5, 2021

VincentTam commented Feb 10, 2021

eduardoboucas left a comment

alexwaibel commented Feb 12, 2021 •

edited

Loading

alexwaibel commented Feb 12, 2021

VincentTam commented Feb 12, 2021

lionxlife May 19, 2021


		Forms on your static site should `POST` to:

		`{STATICMAN_BASE_URL}/v3/entry/{GIT_PROVIDER}/{GIT_PROVIDER_USERNAME}/{REPO}/{BRANCH}/{property (optional)}`


		You can use the [sample config file](https://github.com/eduardoboucas/staticman/blob/master/staticman.sample.yml) as a starting point and check the [available configuration parameters](/docs/configuration) for more information.
		This is the recommended way to authenticate with GitHub. This method will give the most control over what Staticman can and can't access.


		#### Option 3. Authenticate to GitHub using a personal access token on your main account

		This option is not recommended as it gives Staticman direct and complete access to your primary GitHub account. Simply, create a personal access token on your primary account.

Update docs to cover v3, Heroku, spam handling, email notifications #13

Update docs to cover v3, Heroku, spam handling, email notifications #13

Conversation

alexwaibel commented Jan 4, 2021

alexwaibel Jan 4, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

LordAmit commented Jan 5, 2021

VincentTam commented Feb 10, 2021

eduardoboucas left a comment

Choose a reason for hiding this comment

alexwaibel commented Feb 12, 2021 • edited Loading

alexwaibel commented Feb 12, 2021

VincentTam commented Feb 12, 2021

Choose a reason for hiding this comment

alexwaibel Jan 4, 2021 •

edited

Loading

alexwaibel commented Feb 12, 2021 •

edited

Loading