From 614cb50990134879dad227ebcddc1700a61a1fca Mon Sep 17 00:00:00 2001 From: Simon Lecoq <22963968+lowlighter@users.noreply.github.com> Date: Sun, 11 Apr 2021 10:03:44 +0200 Subject: [PATCH] Update README.md --- .../partials/documentation/contributing.md | 8 +- .../partials/documentation/organizations.md | 32 +----- .../organizations/memberships.md | 12 ++ .../documentation/organizations/setup.md | 25 ++++ .../readme/partials/documentation/plugins.md | 2 +- .github/readme/partials/introduction.md | 2 +- .github/readme/partials/license.md | 3 +- .github/readme/partials/setup/action.md | 98 +--------------- .github/readme/partials/setup/action/setup.md | 99 ++++++++++++++++ .github/readme/partials/setup/shared.md | 9 +- .github/readme/partials/setup/shared/usage.md | 12 ++ .github/readme/partials/setup/web.md | 107 +----------------- .github/readme/partials/setup/web/http.md | 20 ++++ .github/readme/partials/setup/web/setup.md | 89 +++++++++++++++ 14 files changed, 274 insertions(+), 244 deletions(-) create mode 100644 .github/readme/partials/documentation/organizations/memberships.md create mode 100644 .github/readme/partials/documentation/organizations/setup.md create mode 100644 .github/readme/partials/setup/action/setup.md create mode 100644 .github/readme/partials/setup/shared/usage.md create mode 100644 .github/readme/partials/setup/web/http.md create mode 100644 .github/readme/partials/setup/web/setup.md diff --git a/.github/readme/partials/documentation/contributing.md b/.github/readme/partials/documentation/contributing.md index 14c94262..dc8755ea 100644 --- a/.github/readme/partials/documentation/contributing.md +++ b/.github/readme/partials/documentation/contributing.md @@ -3,11 +3,11 @@ Metrics is built to be easily customizable. Fork this repository, switch used action from `lowlighter/metrics@latest` to your fork and start coding! -To report a bug fill an [issue](https://github.com/lowlighter/metrics/issues) describing it. +See [ARCHITECTURE.md](/ARCHITECTURE.md) for more informations about how code is structured. +To report a bug fill an [issue](https://github.com/lowlighter/metrics/issues) describing it. To suggest new features or requesting help to setup metrics, check out [discussions](https://github.com/lowlighter/metrics/discussions). +You can also take a look at issues labeled with [help wanted](https://github.com/lowlighter/metrics/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). If you want to contribute, submit a [pull request](https://github.com/lowlighter/metrics/pulls). -Be sure to read [CONTRIBUTING.md](CONTRIBUTING.md) for more information about this. - -If you don't know where to start, you can also take a look at issues labeled with [help wanted](https://github.com/lowlighter/metrics/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). \ No newline at end of file +Be sure to read [CONTRIBUTING.md](/CONTRIBUTING.md) for more information about this. diff --git a/.github/readme/partials/documentation/organizations.md b/.github/readme/partials/documentation/organizations.md index 8b84fb0d..e66d55e4 100644 --- a/.github/readme/partials/documentation/organizations.md +++ b/.github/readme/partials/documentation/organizations.md @@ -7,41 +7,13 @@ While metrics targets mainly user accounts, it's possible to render metrics for
đŸ’Ŧ Metrics for organizations (click to expand) -Setup is the same as for user accounts, though you'll need to add `read:org` scope, **whether you're member of target organization or not**. - -![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png) - -You'll also need to set `user` option with your organization name. - -If you're encounting errors and your organization is using single sign-on, try to [authorize your personal token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). - -Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests. - -To support private repositories, add full `repo` scope to your personal token. - -#### ℹī¸ Example workflow - -```yaml -- uses: lowlighter/metrics@latest - with: - # ... other options - token: ${{ secrets.METRICS_TOKEN }} # A personal token from an user account with read:org scope - user: organization-name # Organization name -``` +<%- await include(`/partials/documentation/organizations/setup.md`) -%>
đŸ’Ŧ Organizations memberships for user accounts (click to expand) -Only public memberships can be displayed by metrics by default. -You can manage your membership visibility in the `People` tab of your organization: - -![Publish organization membership](/.github/readme/imgs/setup_public_membership_org.png) - -For organization memberships, add `read:org` scope to your personal token. - -![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png) - +<%- await include(`/partials/documentation/organizations/memberships.md`) -%>
diff --git a/.github/readme/partials/documentation/organizations/memberships.md b/.github/readme/partials/documentation/organizations/memberships.md new file mode 100644 index 00000000..d6878079 --- /dev/null +++ b/.github/readme/partials/documentation/organizations/memberships.md @@ -0,0 +1,12 @@ + +#### đŸ’Ŧ Organizations memberships for user accounts + + +Only public memberships can be displayed by metrics by default. +You can manage your membership visibility in the `People` tab of your organization: + +![Publish organization membership](/.github/readme/imgs/setup_public_membership_org.png) + +For organization memberships, add `read:org` scope to your personal token. + +![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png) diff --git a/.github/readme/partials/documentation/organizations/setup.md b/.github/readme/partials/documentation/organizations/setup.md new file mode 100644 index 00000000..94a85fcc --- /dev/null +++ b/.github/readme/partials/documentation/organizations/setup.md @@ -0,0 +1,25 @@ + +#### đŸ’Ŧ Metrics for organizations + + +Setup is the same as for user accounts, though you'll need to add `read:org` scope, **whether you're member of target organization or not**. + +![Add read:org scope to personal token](/.github/readme/imgs/setup_token_org_read_scope.png) + +You'll also need to set `user` option with your organization name. + +If you're encounting errors and your organization is using single sign-on, try to [authorize your personal token](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on). + +Most of plugins supported by user accounts will work with organization accounts, but note that rendering metrics for organizations consume way more APIs requests. + +To support private repositories, add full `repo` scope to your personal token. + +#### ℹī¸ Example workflow + +```yaml +- uses: lowlighter/metrics@latest + with: + # ... other options + token: ${{ secrets.METRICS_TOKEN }} # A personal token from an user account with read:org scope + user: organization-name # Organization name +``` \ No newline at end of file diff --git a/.github/readme/partials/documentation/plugins.md b/.github/readme/partials/documentation/plugins.md index dc3cb78b..56c0461e 100644 --- a/.github/readme/partials/documentation/plugins.md +++ b/.github/readme/partials/documentation/plugins.md @@ -2,7 +2,7 @@ Plugins are features which provide additional content and lets you customize your rendered metrics. See their respective documentation for more informations about how to setup them: -<% { let previous = null; for (const [plugin, {name, categorie}] of Object.entries(plugins).filter(([key, value]) => value)) { %> +<% { let previous = null; for (const [plugin, {name, categorie}] of Object.entries(plugins).filter(([key, value]) => value).sort(([an, a], [bn, b]) => a.categorie === b.categorie ? an.localeCompare(bn) : 0)) { %> <% if (previous !== categorie) { previous = categorie -%> * **<%= `${categorie.charAt(0).toLocaleUpperCase()}${categorie.substring(1)}` %>** <% } -%> diff --git a/.github/readme/partials/introduction.md b/.github/readme/partials/introduction.md index 75c95c88..1a44872c 100644 --- a/.github/readme/partials/introduction.md +++ b/.github/readme/partials/introduction.md @@ -1,7 +1,7 @@ Generate your metrics that you can embed everywhere, including your GitHub profile readme! It works for both user and organization accounts, and even for repositories! <% if (/[.]0-beta$/.test(packaged.version)) { %> -*⚠ī¸ This is the documentation of **v<%= packaged.version.replace(/[.]0-beta$/, "") %>-beta** (`@master` branch) which includes [unreleased features](https://github.com/lowlighter/metrics/compare/latest...master), see documentation of **v<%= (Number(packaged.version.replace(/[.]0-beta$/, ""))-0.1).toFixed(1) %>** (`@latest` branch) [here](https://github.com/lowlighter/metrics/blob/latest/README.md).* +> *⚠ī¸ This is the documentation of **v<%= packaged.version.replace(/[.]0-beta$/, "") %>-beta** (`@master` branch) which includes [unreleased features](https://github.com/lowlighter/metrics/compare/latest...master), see documentation of **v<%= (Number(packaged.version.replace(/[.]0-beta$/, ""))-0.1).toFixed(1) %>** (`@latest` branch) [here](https://github.com/lowlighter/metrics/blob/latest/README.md).* <% } %> diff --git a/.github/readme/partials/license.md b/.github/readme/partials/license.md index d9904e45..051efc7c 100644 --- a/.github/readme/partials/license.md +++ b/.github/readme/partials/license.md @@ -4,10 +4,11 @@ MIT License Copyright (c) 2020-present lowlighter ``` -See full license in [LICENSE.md](/LICENSE.md) ![License details](https://github.com/lowlighter/lowlighter/blob/master/metrics.licenses.svg) +See full license in [LICENSE.md](/LICENSE.md) + ![Sponsors](https://github.com/lowlighter/lowlighter/blob/master/metrics.sponsors.svg) [`â™Ĩī¸ Become a sponsor`](https://www.buymeacoffee.com/lowlighter) diff --git a/.github/readme/partials/setup/action.md b/.github/readme/partials/setup/action.md index 8bfadf94..9894516f 100644 --- a/.github/readme/partials/setup/action.md +++ b/.github/readme/partials/setup/action.md @@ -1,7 +1,7 @@ ## ⚙ī¸ Using GitHub Action on your profile repository (~5 min setup) Setup a GitHub Action which runs periodically and pushes your generated metrics image to your repository. -See all supported options in [action.yml](action.yml). +See all supported options in [action.yml](/action.yml). Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below: @@ -15,100 +15,6 @@ Assuming your username is `my-github-user`, you can then embed rendered metrics
đŸ’Ŧ How to setup? (click to expand) -### 0. Setup your personal repository - -Create a repository with the same name as your GitHub login (if it's not already done). - -![Setup personal repository](/.github/readme/imgs/setup_personal_repository.png) - -Its `README.md` will be displayed on your user profile: - -![GitHub Profile Example](/.github/readme/imgs/example_github_profile.png) - -### 1. Create a GitHub personal token - -From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token. - -No additional scopes are needed for basic metrics, but you may have to grant additional scope depending on what features you're planning to use: -- `public_repo` scope for some plugins -- `read:org` scope for all organizations related metrics -- `repo` scope for all private repositories related metrics - -![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png) - -A scope-less token can still display private contributions by enabling `Include private contributions on my profile` in your account settings: - -![Enable "Include private contributions on my profile`"](/.github/readme/imgs/setup_private_contributions.png) - -If a plugin has not enough scopes to operate (and `plugins_errors_fatal` isn't enabled), it'll be reported in the rendering like below: - -![Plugin error example](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.error.svg) - -### 2. Put your GitHub personal token in your repository secrets - -Go to the `Settings` of your repository to create a new secret and paste your freshly generated GitHub token there. - -![Setup a repository secret](/.github/readme/imgs/setup_repository_secret.png) - -### 3. Create a GitHub Action workflow in your repository - -Create a new workflow from the `Actions` tab of your repository and paste the following: - -```yaml -name: Metrics -on: - # Schedule updates (each hour) - schedule: [{cron: "0 * * * *"}] - # Lines below let you run workflow manually and on each commit (optional) - workflow_dispatch: - push: {branches: ["master", "main"]} -jobs: - github-metrics: - runs-on: ubuntu-latest - steps: - # See action.yml for all options - - uses: lowlighter/metrics@latest - with: - # Your GitHub token - token: ${{ secrets.METRICS_TOKEN }} -``` - -See all supported options in [action.yml](action.yml). - -Rendered metrics will be committed to your repository on each run. - -![Action update example](/.github/readme/imgs/example_action_update.png) - -#### Choosing between `@latest`, `@master` or a fork - -If you wish to use new features as they're being released, you can switch from `@latest` to `@master`. -As the latter is used as a development branch, jobs may fail from time to time (although we try to mitigate this). - -When using a token with additional permissions, it is advised to fork this repository and use it instead to minimize security risks: -```yaml - - uses: my-github-username/metrics@master - # If you make changes on your fork, be sure not leave @latest as tag! -``` - -In this case, please consider watching new releases to stay up-to-date and enjoy latest features! - -`@latest` will be updated on each release soon after [Planned for next release](https://github.com/lowlighter/metrics/projects/1#column-12378679) is emptied. Metrics doesn't introduce breaking changes **from an user point of view** (i.e. your workflows will always be valid) so you can follow release cycles without worrying. - -#### Examples workflows - -Metrics displayed on this page are rendered from this [workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/metrics.yml) so you can check it out for some code examples about plugins usage. - -You can also take a look at this [user workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/personal.yml) if you want. - -### 4. Embed link into your README.md - -Update your README.md to embed your metrics: - -```markdown - -![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg) - -![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg) -``` +<%- await include(`/partials/setup/action/setup.md`) -%>
diff --git a/.github/readme/partials/setup/action/setup.md b/.github/readme/partials/setup/action/setup.md new file mode 100644 index 00000000..2e91f7b4 --- /dev/null +++ b/.github/readme/partials/setup/action/setup.md @@ -0,0 +1,99 @@ + +#### đŸ’Ŧ How to setup? + + +### 0. Setup your personal repository + +Create a repository with the same name as your GitHub login (if it's not already done). + +![Setup personal repository](/.github/readme/imgs/setup_personal_repository.png) + +Its `README.md` will be displayed on your user profile: + +![GitHub Profile Example](/.github/readme/imgs/example_github_profile.png) + +### 1. Create a GitHub personal token + +From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token. + +No additional scopes are needed for basic metrics, but you may have to grant additional scope depending on what features you're planning to use: +- `public_repo` scope for some plugins +- `read:org` scope for all organizations related metrics +- `repo` scope for all private repositories related metrics + +![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png) + +A scope-less token can still display private contributions by enabling `Include private contributions on my profile` in your account settings: + +![Enable "Include private contributions on my profile`"](/.github/readme/imgs/setup_private_contributions.png) + +If a plugin has not enough scopes to operate (and `plugins_errors_fatal` isn't enabled), it'll be reported in the rendering like below: + +![Plugin error example](https://github.com/lowlighter/lowlighter/blob/master/metrics.plugin.error.svg) + +### 2. Put your GitHub personal token in your repository secrets + +Go to the `Settings` of your repository to create a new secret and paste your freshly generated GitHub token there. + +![Setup a repository secret](/.github/readme/imgs/setup_repository_secret.png) + +### 3. Create a GitHub Action workflow in your repository + +Create a new workflow from the `Actions` tab of your repository and paste the following: + +```yaml +name: Metrics +on: + # Schedule updates (each hour) + schedule: [{cron: "0 * * * *"}] + # Lines below let you run workflow manually and on each commit (optional) + workflow_dispatch: + push: {branches: ["master", "main"]} +jobs: + github-metrics: + runs-on: ubuntu-latest + steps: + # See action.yml for all options + - uses: lowlighter/metrics@latest + with: + # Your GitHub token + token: ${{ secrets.METRICS_TOKEN }} +``` + +See all supported options in [action.yml](/action.yml). + +Rendered metrics will be committed to your repository on each run. + +![Action update example](/.github/readme/imgs/example_action_update.png) + +#### Choosing between `@latest`, `@master` or a fork + +If you wish to use new features as they're being released, you can switch from `@latest` to `@master`. +As the latter is used as a development branch, jobs may fail from time to time (although we try to mitigate this). + +When using a token with additional permissions, it is advised to fork this repository and use it instead to minimize security risks: +```yaml + - uses: my-github-username/metrics@master + # If you make changes on your fork, be sure not leave @latest as tag! +``` + +In this case, please consider watching new releases to stay up-to-date and enjoy latest features! + +`@latest` will be updated on each release soon after [Planned for next release](https://github.com/lowlighter/metrics/projects/1#column-12378679) is emptied. Metrics doesn't introduce breaking changes **from an user point of view** (i.e. your workflows will always be valid) so you can follow release cycles without worrying. + +#### Examples workflows + +Metrics displayed on this page are rendered from this [workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/metrics.yml) so you can check it out for some code examples about plugins usage. + +You can also take a look at this [user workflow](https://github.com/lowlighter/lowlighter/blob/master/.github/workflows/personal.yml) if you want. + +### 4. Embed link into your README.md + +Update your README.md to embed your metrics: + +```markdown + +![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg) + +![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg) +``` \ No newline at end of file diff --git a/.github/readme/partials/setup/shared.md b/.github/readme/partials/setup/shared.md index 85fd653c..b40e07ca 100644 --- a/.github/readme/partials/setup/shared.md +++ b/.github/readme/partials/setup/shared.md @@ -12,13 +12,6 @@ Availability is not guaranteed.
đŸ’Ŧ Fair use (click to expand) -To ensure service availability, shared instance has a few limitations: - * Images are cached for 15 minutes - * Rendered metrics **won't be updated** during this time window when queried - * You can manually update rendering againg your metrics on [metrics.lecoq.io](https://metrics.lecoq.io) - * A rate limiter is enabled to prevent denial of service (it doesn't affect already cached metrics) - * Some plugins may not be available - -Service is provided free of charge, so please be gentle with it 🙂 +<%- await include(`/partials/setup/shared/usage.md`) -%>
diff --git a/.github/readme/partials/setup/shared/usage.md b/.github/readme/partials/setup/shared/usage.md new file mode 100644 index 00000000..4e54d5a4 --- /dev/null +++ b/.github/readme/partials/setup/shared/usage.md @@ -0,0 +1,12 @@ + +#### đŸ’Ŧ Fair use + + +To ensure service availability, shared instance has a few limitations: + * Images are cached for 1 hour + * Rendered metrics **won't be updated** during this time window when queried + * You can manually update rendering again your metrics on [metrics.lecoq.io](https://metrics.lecoq.io) + * A rate limiter is enabled to prevent denial of service (it doesn't affect already cached metrics) + * Some plugins may not be available + +Service is provided free of charge, so please be gentle with it 🙂 \ No newline at end of file diff --git a/.github/readme/partials/setup/web.md b/.github/readme/partials/setup/web.md index d67f8a84..7e711783 100644 --- a/.github/readme/partials/setup/web.md +++ b/.github/readme/partials/setup/web.md @@ -2,7 +2,7 @@ Setup a metrics instance on your server if you don't want to use GitHub Actions and [metrics.lecoq.io](https://metrics.lecoq.io). -See all supported options in [settings.example.json](settings.example.json). +See all supported options in [settings.example.json](/settings.example.json). Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below: @@ -13,112 +13,13 @@ Assuming your username is `my-github-user`, you can then embed rendered metrics
đŸ’Ŧ How to setup? (click to expand) -### 0. Prepare your server - -You'll need a server with a recent version [NodeJS](https://nodejs.org) (see used version in [Dockerfile](Dockerfile#L1-L2)). - -### 1. Create a GitHub personal token - -From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token. - -No additional scopes are needed. - -![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png) - -### 2. Install dependencies - -Clone repository, install dependencies and copy configuration example to `settings.json`: - -```shell -git clone https://github.com/lowlighter/metrics.git -cd metrics/ -npm install --only=prod -cp settings.example.json settings.json -``` - -### 3. Configure your instance and start it - -Edit `settings.json` to configure your instance. - -```javascript -{ - //GitHub API token - "token":"GITHUB_TOKEN", - //Other options... -} -``` - -See all supported options in [settings.example.json](settings.example.json). - -If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list. - -Once you've finished configuring metrics, start your instance: - -```shell -npm start -``` - -Access your server with provided port in `setting.json` from your browser to ensure everything is working. - -### 4. Embed link into your README.md - -Edit your repository readme and add your metrics image from your server domain: - -```markdown -![Metrics](https://my-personal-domain.com/my-github-user) -``` - -### 6. (optional) Setup your instance as a service - -To ensure that your instance will restart if it reboots or crashes, you should set it up as a service. -This is described below for Linux-like systems which support *systemd*. - -Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following after editing paths inside: - -```ini -[Unit] -Description=Metrics -After=network-online.target -Wants=network-online.target - -[Service] -Type=simple -WorkingDirectory=/path/to/metrics -ExecStart=/usr/bin/node /path/to/metrics/index.mjs - -[Install] -WantedBy=multi-user.target -``` - -Reload services, enable it, start it and check if it is up and running: - -```shell -systemctl daemon-reload -systemctl enable github_metrics -systemctl start github_metrics -systemctl status github_metrics -``` +<%- await include(`/partials/setup/web/setup.md`) -%>
-🔗 HTTP parameters +🔗 HTTP parameters (click to expand) -Most of options from [action.yml](action.yml) are actually supported by web instance, though syntax is slightly different. -All underscores (`_`) must be replaced by dots (`.`) and `plugin_` prefixes must be dropped. - -For example, to configure pagespeed plugin you'd use the following: -``` -https://my-personal-domain.com/my-github-user?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com -``` - -Note that url parameters must be [encoded](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/encodeURIComponent). - -As for `base` content, which is enabled by default, sections are available through "`base.
`". - -For example, to display only `repositories` section, use: -``` -https://my-personal-domain.com/my-github-user?base=0&base.repositories=1 -``` +<%- await include(`/partials/setup/web/http.md`) -%>
diff --git a/.github/readme/partials/setup/web/http.md b/.github/readme/partials/setup/web/http.md new file mode 100644 index 00000000..65f384df --- /dev/null +++ b/.github/readme/partials/setup/web/http.md @@ -0,0 +1,20 @@ + +#### 🔗 HTTP parameters + + +Most of options from [action.yml](/action.yml) are actually supported by web instance, though syntax is slightly different. +All underscores (`_`) must be replaced by dots (`.`) and `plugin_` prefixes must be dropped. + +For example, to configure pagespeed plugin you'd use the following: +``` +https://my-personal-domain.com/my-github-user?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com +``` + +Note that url parameters must be [encoded](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/encodeURIComponent). + +As for `base` content, which is enabled by default, sections are available through "`base.
`". + +For example, to display only `repositories` section, use: +``` +https://my-personal-domain.com/my-github-user?base=0&base.repositories=1 +``` \ No newline at end of file diff --git a/.github/readme/partials/setup/web/setup.md b/.github/readme/partials/setup/web/setup.md new file mode 100644 index 00000000..110f337f --- /dev/null +++ b/.github/readme/partials/setup/web/setup.md @@ -0,0 +1,89 @@ + +#### đŸ’Ŧ How to setup? + + +### 0. Prepare your server + +You'll need a server with a recent version [NodeJS](https://nodejs.org) (see used version in [Dockerfile](/Dockerfile#L1-L2)). + +### 1. Create a GitHub personal token + +From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token. + +No additional scopes are needed. + +![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png) + +### 2. Install dependencies + +Clone repository, install dependencies and copy configuration example to `settings.json`: + +```shell +git clone https://github.com/lowlighter/metrics.git +cd metrics/ +npm install --only=prod +cp settings.example.json settings.json +``` + +### 3. Configure your instance and start it + +Edit `settings.json` to configure your instance. + +```javascript +{ + //GitHub API token + "token":"GITHUB_TOKEN", + //Other options... +} +``` + +See all supported options in [settings.example.json](/settings.example.json). + +If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list. + +Once you've finished configuring metrics, start your instance: + +```shell +npm start +``` + +Access your server with provided port in `setting.json` from your browser to ensure everything is working. + +### 4. Embed link into your README.md + +Edit your repository readme and add your metrics image from your server domain: + +```markdown +![Metrics](https://my-personal-domain.com/my-github-user) +``` + +### 6. (optional) Setup your instance as a service + +To ensure that your instance will restart if it reboots or crashes, you should set it up as a service. +This is described below for Linux-like systems which support *systemd*. + +Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following after editing paths inside: + +```ini +[Unit] +Description=Metrics +After=network-online.target +Wants=network-online.target + +[Service] +Type=simple +WorkingDirectory=/path/to/metrics +ExecStart=/usr/bin/node /path/to/metrics/index.mjs + +[Install] +WantedBy=multi-user.target +``` + +Reload services, enable it, start it and check if it is up and running: + +```shell +systemctl daemon-reload +systemctl enable github_metrics +systemctl start github_metrics +systemctl status github_metrics +``` \ No newline at end of file