Skip to content

Latest commit

 

History

History
204 lines (159 loc) · 7.06 KB

web.md

File metadata and controls

204 lines (159 loc) · 7.06 KB
Raw

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

Setup a GitHub personal token Setup a GitHub personal token

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",
  },
  "plugins": {
    "isocalendar":{
      "enabled": false
    }
  }
}

2️.3️ Extra features configuration

Extra features are a way to enable and control advanced functionality in plugins, which are usually either CPU or API intensive, require access to filesystem or binaries, and sometimes also allow remote code execution.

⚠️ Please understand that some extras features may compromise container integrity or security. Never use them if outside a containerized or development environment!

Use at your own risk, metrics and its authors cannot be held responsible for any damage caused.

Example: extra features server configuration

{
  "extras": {
    "features": [
      "metrics.setup.community.templates",
      "metrics.api.github.overuse",
      "metrics.cpu.overuse",
      "metrics.run.puppeteer.scrapping",
    ]
  }
}

The following extra features are supported:

Extra feature identifier Description
metrics.setup.community.templates Allow community templates download
metrics.setup.community.presets Allow community presets usage
metrics.api.github.overuse Allow GitHub API intensive requests
metrics.api.* Allow use of external API requests
metrics.cpu.overuse Allow CPU intensive requests
metrics.run.tempdir Allow access to temporary directory (including I/O)
metrics.run.git Allow to run git
metrics.run.licensed Allow to run licensed
⚠️ metrics.run.user.cmd Allow to run ANY command by user (USE WITH CAUTION! May result in token leaks by malicious users)
metrics.run.puppeteer.scrapping Allow to run puppeteer to scrape data
metrics.run.puppeteer.user.css Allow to run CSS by user during puppeteer render
metrics.run.puppeteer.user.js Allow to run JavaScript by user during puppeteer render
⚠️ metrics.npm.optional.* Allow use of specified dependency (CONSULT RESPECTIVE DEPENDENCY CVE FIRST)

If a plugin is used without sufficient permissions, it will result in an error.

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 --rm --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 behind 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