web.md

🏗️ Deploying a web instance (~20 min)

Setup a metrics web instance on your server.

0️ Prepare your server

A server with a recent version of docker is required.

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

💡 For security reasons, it is advised to use a scope-less token for web instances.

2️ Configure metrics

Fetch a copy of settings.example.json and rename it settings.json

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

Edit settings.json to configure your instance.

Example: minimal configuration

{
  "token": "GITHUB_TOKEN",
}

2️.1️ Restricting access to your web instance

If you intend to make your web instance public, it is advised to restrict access using an access list or rate-limiting it.

Only authorized users will be able to generate images.

Example: restricted access server

{
  "restricted": ["user1", "user2", "user3"],
  "maxusers": 2,
  "ratelimiter": {
    "windowMs": 900000,
	  "max": 100
  }
}

2️.2️ Global configuration

Configuration file also contains settings about enabled templates, plugins and features.

Example: additional server configuration

{
  "cached": 3600000,
  "port": 3000,
  "templates": {
    "default": "classic",
    "enabled": ["classic", "terminal"],
  },
  "community": {
    "templates": ["user/repo@main:custom-theme"],
  },
  "hosted": {
    "by": "me",
    "link": "https://user.me",
  },
  "extras": {
    "css": true,
    "features": false
  },
  "plugins": {
    "isocalendar":{
      "enabled": false
    }
  }
}

⚠️ Extras features should not be enabled on a public server, most of these are compute-intensive and some of some even allow remote code execution! Use with caution

3️ Start docker container

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 --entrypoint="" -p=127.0.0.1:$PUBLISHED_PORT:$SERVICE_PORT --volume=$SETTINGS:/metrics/settings.json ghcr.io/lowlighter/metrics:$VERSION npm start

4️ Add images to your profile README.md

Update profile README.md to include rendered image.

Example: add rendered image with markdown

![Metrics](https://my.server.com/username)

4️.1️ URL parameters syntax

The GitHub action and the web instance uses the same engine behing the hood.

It is actually possible to generate image directly from url without passing by the web ui by knowing how to pass parameters.

Parameters for the web instance:

• use dots (.) instead of underscores (_)
• does not use plugin_ prefixes
• special characters need to be url encoded

Example: configuring ⏱️ pagespeed plugin for https://example.org

<img src="https://my.server.com/username?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com">

🗃️ base plugin use a slightly different notation where sections are configured through base.<section> param.

Example: configuring 🗃️ base plugin to display only repositories section

<img src="https://my.server.com/username?base=0&base.repositories=1">

*️⃣ Create a service (optional)

To ensure that service will restart after reboots or crashes, it is advised to setup it 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:

[Unit]
Description=Metrics
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=# docker command #

[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