Document configuration of a Github rate limit, FAQ and Github PAT howto as solution (e.g. for improving client UI upgrade experience)

[davidzwa]

Context

FDM Monster calls the GitHub API to do these things:

• check FDM Monster server releases for the latest (purely a piece of info which is output in the logs at startup)
• check FDM Monster client UI releases (for upgrading)

Many users are enjoying the client upgrade feature, but sometimes the releases of Github dont load.

Problem description

The GitHub API has a rate limit. A part of the GitHub documentation describes this as follows:

GitHub limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users.

And more specifically:

The primary rate limit for unauthenticated requests is 60 requests per hour.

FDM Monster is doing unauthenticated requests per default. But if we read further, there are also authenticated requests possible with the Github API given a Personal Access Token (PAT) is provided.

You can use a personal access token to make API requests. Additionally, you can authorize a GitHub App or OAuth app, which can then make API requests on your behalf.

All of these requests count towards your personal rate limit of 5,000 requests per hour.

FDM Monster has not been configured or approved as GitHub App and therefore users must provide their own PAT. The FDM Monster server can be configured with this token. This is what must be documented.

Information to convey

1. We must describe the problem of the GitHub rate limit.
2. We must show the user how FDM Monster should present an error in the UI. Server has reached a rate limit of the Github API. This limit will be reset at .... (in ... minutes). Note to us: I am not sure this mechanic works 😶‍🌫️
3. We must document the process of generating a GitHub PAT from Github. We must state that GitHub has "fine-grained personal access tokens" and "classic personal access tokens". Both work, but we advise users to only generate the fine-grained version.

Step 1 - Click account top right

Step 2 - Click settings option

Step 3 - Scroll down and click Developer settings

Step 4 - Click Personal access tokens

Step 5 - Open Fine-grained tokens (Preview)

Step 6 - Click Generate new token

Step 7 - Login with two-factor authentication (2FA) if this is configured for your account.
Step 8 - Provide all details required and submit with Generate token. Please be aware that the token is only shown to you once. If you close the window and did not write down the token, you will need to redo this step. In that case its best to delete the old token as it will not have any value. For further questions please consult the frequently asked questions (FAQ) below.
Step 9 - Submit the token and copy the shown text value (a fine-grained token starts with ghp_)

4. We must document adjusting the environment variables for FDM Monster. This is complex: the approach for MonsterPi, Docker and self managed install bases all differ. The MonsterPi approach is complex.
   We might be better off adding a feature request to FDM Monster before heading this direction. Therefore this part of the documentation is to be marked very advanced until further notice.

The environment variable is called GITHUB_PAT and adding it to the .env file in the applicable fdm-monster folder is one option. For docker we should instead specify the environment variable as documented elsewhere (avoid duplication). For MonsterPi we should: uninstall the service (uninstall npm script in daemon folder, sudo npm uninstall in /home/pi/fdm-monster-daemon/, adjust the service spec found here or add the .env file (not preferred) and finally run sudo npm install. We could also refer to running the update script as this has "Please run as root" validation.

Concluding: its a mess.

FAQ

• Token name: provide a recognizable name
• Owner: up to the user. A private account often makes most sense.
• Duration: up to the user. If security is important its advised to keep a limited duration for the PAT.
• Description: this is optional.
• Repository access: Public repositories (all other options will work, but are not advised)
• Permissions: No permissions are required as the FDM Monster repository is a publicly accessible repository.

[mkevenaar]

IS this a duplicate of #68 ?