sudacode/metrics
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

docs: improve overall documentation

Browse Source
This commit is contained in:
lowlighter
2022-01-15 00:12:18 -05:00
parent ee1abadf9a
commit c0f4cf42ad
21 changed files with 162 additions and 236 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
.github/readme/partials/documentation/setup/action.md vendored Normal file
View File

@@ -0,0 +1,115 @@
# ⚙️ Using GitHub Action on a profile repository (~10 min setup)
Setup a GitHub Action which runs periodically and pushes generated images to a repository.
Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below:
```markdown
<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)
```
## 💬 How to setup?
### 0. Setup a 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
- `read:user` scope may also be required for some 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).
For convenience, it is possible to use `@main` instead of `@master`.
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. 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
<!-- If you're using "master" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg)
<!-- If you're using "main" as default branch -->
![Metrics](https://github.com/my-github-user/my-github-user/blob/main/github-metrics.svg)
<!-- If you're using the "columns" display mode -->
<img src="https://github.com/my-github-user/my-github-user/blob/master/github-metrics.svg" alt="Metrics" width="100%">
```

19
.github/readme/partials/documentation/setup/shared.md vendored Normal file
View File

@@ -0,0 +1,19 @@
# 💕 Using the shared instance (~1 min setup, but with limitations)
For convenience, you can use the shared instance available at [metrics.lecoq.io](https://metrics.lecoq.io) without any additional setup.
```markdown
![Metrics](https://metrics.lecoq.io/my-github-user)
```
This is mostly intended for previews, to enjoy all features consider using GitHub Action instead.
Availability is not guaranteed.
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 🙂

142
.github/readme/partials/documentation/setup/web.md vendored Normal file
View File

@@ -0,0 +1,142 @@
# 🏗️ Deploying your own web instance (~20 min setup, depending on your sysadmin knowledge)
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).
Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below:
```markdown
![Metrics](https://my-personal-domain.com/my-github-user)
```
## 💬 How to setup?
### 0. Prepare your server
You'll need a server with a recent version of [Docker](https://www.docker.com/).
### 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. Configure your instance
Fetch [settings.example.json](/settings.example.json) which contains all supported option.
```shell
wget https://raw.githubusercontent.com/lowlighter/metrics/master/settings.example.json
```
Edit `settings.json` to configure your instance.
```javascript
{
//GitHub API token
"token":"GITHUB_TOKEN",
//Other options...
}
```
If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list.
### 3. Start docker container
Metrics docker images are published on [GitHub Container Registry](https://github.com/lowlighter/metrics/pkgs/container/metrics).
Configure the following variables (or hardcode them in the command in the next block):
```shell
# Select an existing docker image tag
VERSION=latest
# Path to configured `settings.json`
SETTINGS=/path/to/settings.json
# Port used internally (use the same one than in `settings.json`)
SERVICE_PORT=3000
# Port to publish
PUBLISHED_PORT=80
```
And start the container using the following command:
```shell
docker run -d --workdir=/metrics --entrypoint="" -p=127.0.0.1:$PUBLISHED_PORT:$SERVICE_PORT --volume=$SETTINGS:/metrics/settings.json ghcr.io/lowlighter/metrics:$VERSION npm start
```
### 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)
```
### 5. (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
ExecStart=(command to run as service)
[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
```
### Alternative option: run an instance locally (intended for testing and development)
To run an instance without docker, you'll need to have [NodeJS](https://nodejs.org) (see used version in [Dockerfile](/Dockerfile#L1-L2)) installed.
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
```
Once you've finished configuring metrics, start your instance using the following command:
```shell
npm start
```
You should now be able to access your server with provided port in `setting.json` from your browser.
## 🔗 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.<section>`".
For example, to display only `repositories` section, use:
```
https://my-personal-domain.com/my-github-user?base=0&base.repositories=1
```