web.md

🏗️ 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. See all supported options in settings.example.json.

Assuming your username is my-github-user, you can then embed rendered metrics in your readme like below:

![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.

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.

2. Configure your instance

Fetch settings.example.json which contains all supported option.

wget https://raw.githubusercontent.com/lowlighter/metrics/master/settings.example.json

Edit settings.json to configure your instance.

{
  //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.

Configure the following variables (or hardcode them in the command in the next block):

# 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:

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:

![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:

[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:

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 (see used version in Dockerfile) installed.

Clone repository, install dependencies and copy configuration example to settings.json:

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:

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 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.

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