Skip to content

Commit 344c7a5

Browse files
lowlighterlowlighter
committed
docs: update web setup
1 parent a057693 commit 344c7a5

File tree

1 file changed

+98
-73
lines changed
  • .github/readme/partials/documentation/setup

1 file changed

+98
-73
lines changed

‎.github/readme/partials/documentation/setup/web.md‎

Lines changed: 98 additions & 73 deletions
Original file line numberDiff line numberDiff line change
@@ -1,50 +1,93 @@
1-
# 🏗️ Deploying your own web instance (~20 min setup, depending on your sysadmin knowledge)
1+
# 🏗️ Deploying a web instance (~20 min)
22

3-
Setup a metrics instance on your server if you don't want to use GitHub Actions and [metrics.lecoq.io](https://metrics.lecoq.io).
4-
See all supported options in [settings.example.json](/settings.example.json).
3+
Setup a *metrics* web instance on your server.
54

6-
Assuming your username is `my-github-user`, you can then embed rendered metrics in your readme like below:
5+
## 0️ Prepare your server
76

8-
```markdown
9-
![Metrics](https://my-personal-domain.com/my-github-user)
10-
```
11-
12-
## 💬 How to setup?
13-
14-
### 0. Prepare your server
7+
A server with a recent version of [docker](https://www.docker.com/) is required.
158

16-
You'll need a server with a recent version of [Docker](https://www.docker.com/).
17-
18-
### 1. Create a GitHub personal token
9+
## 1️ Create a GitHub personal token
1910

2011
From the `Developer settings` of your account settings, select `Personal access tokens` to create a new token.
2112

22-
No additional scopes are needed.
13+
No additional scopes are required.
14+
15+
> 💡 For security reasons, it is advised to use a scope-less token for web instances.
2316
2417
![Setup a GitHub personal token](/.github/readme/imgs/setup_personal_token.png)
2518

26-
### 2. Configure your instance
19+
## 2️ Configure *metrics*
2720

28-
Fetch [settings.example.json](/settings.example.json) which contains all supported option.
21+
Fetch a copy of [`settings.example.json`](/settings.example.json) and rename it `settings.json`
2922
```shell
3023
wget https://raw.githubusercontent.com/lowlighter/metrics/master/settings.example.json
24+
mv settings.example.json settings.json
3125
```
3226

3327
Edit `settings.json` to configure your instance.
3428

29+
*Example: minimal configuration*
3530
```javascript
3631
{
37-
//GitHub API token
38-
"token":"GITHUB_TOKEN",
39-
//Other options...
32+
"token": "GITHUB_TOKEN",
4033
}
4134
```
4235

43-
If you plan to make your web instance public, it is advised to restrict its access thanks to rate limiter and access list.
36+
### 2️.1️ Restricting access to your web instance
37+
38+
If you intend to make your web instance public, it is advised to restrict access using an access list or rate-limiting it.
4439

45-
### 3. Start docker container
40+
Only authorized users will be able to generate images.
4641

47-
Metrics docker images are published on [GitHub Container Registry](https://github.com/lowlighter/metrics/pkgs/container/metrics).
42+
*Example: restricted access server*
43+
```javascript
44+
{
45+
"restricted": ["user1", "user2", "user3"],
46+
"maxusers": 2,
47+
"ratelimiter": {
48+
"windowMs": 900000,
49+
"max": 100
50+
}
51+
}
52+
```
53+
54+
### 2️.2️ Global configuration
55+
56+
Configuration file also contains settings about enabled templates, plugins and features.
57+
58+
*Example: additional server configuration*
59+
```javascript
60+
{
61+
"cached": 3600000,
62+
"port": 3000,
63+
"templates": {
64+
"default": "classic",
65+
"enabled": ["classic", "terminal"],
66+
},
67+
"community": {
68+
"templates": ["user/repo@main:custom-theme"],
69+
},
70+
"hosted": {
71+
"by": "me",
72+
"link": "https://user.me",
73+
},
74+
"extras": {
75+
"css": true,
76+
"features": false
77+
},
78+
"plugins": {
79+
"isocalendar":{
80+
"enabled": false
81+
}
82+
}
83+
}
84+
```
85+
86+
> ⚠️ 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
87+
88+
## 3️ Start docker container
89+
90+
Docker images are published on [GitHub Container Registry](https://github.com/lowlighter/metrics/pkgs/container/metrics).
4891

4992
Configure the following variables (or hardcode them in the command in the next block):
5093
```shell
@@ -60,24 +103,47 @@ PUBLISHED_PORT=80
60103

61104
And start the container using the following command:
62105
```shell
63-
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
106+
docker run --entrypoint="" -p=127.0.0.1:$PUBLISHED_PORT:$SERVICE_PORT --volume=$SETTINGS:/metrics/settings.json ghcr.io/lowlighter/metrics:$VERSION npm start
64107
```
65108

66-
### 4. Embed link into your README.md
109+
## 4️ Add images to your profile `README.md`
67110

68-
Edit your repository readme and add your metrics image from your server domain:
111+
Update profile `README.md` to include rendered image.
69112

113+
*Example: add rendered image with markdown*
70114
```markdown
71-
![Metrics](https://my-personal-domain.com/my-github-user)
115+
![Metrics](https://my.server.com/username)
72116
```
73117

74-
### 5. (optional) Setup your instance as a service
118+
### 4️.1️ URL parameters syntax
75119

76-
To ensure that your instance will restart if it reboots or crashes, you should set it up as a service.
77-
This is described below for Linux-like systems which support *systemd*.
120+
The GitHub action and the web instance uses the same engine behing the hood.
121+
122+
It is actually possible to generate image directly from url without passing by the web ui by knowing how to pass parameters.
123+
124+
Parameters for the web instance:
125+
- use dots (`.`) instead of underscores (`_`)
126+
- does not use `plugin_` prefixes
127+
- special characters need to be url [encoded](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent)
78128

79-
Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following after editing paths inside:
129+
*Example: configuring `⏱️ pagespeed` plugin for [https://example.org](https://example.org/)*
130+
```html
131+
<img src="https://my.server.com/username?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com">
132+
```
133+
134+
`🗃️ base` plugin use a slightly different notation where sections are configured through `base.<section>` param.
80135

136+
*Example: configuring `🗃️ base` plugin to display only repositories section*
137+
```html
138+
<img src="https://my.server.com/username?base=0&base.repositories=1">
139+
```
140+
141+
## *️⃣ Create a service (optional)
142+
143+
To ensure that service will restart after reboots or crashes, it is advised to setup it as a service.
144+
This is described below for Linux-like systems which support *systemd*.
145+
146+
Create a new service file `/etc/systemd/system/github_metrics.service` and paste the following:
81147
```ini
82148
[Unit]
83149
Description=Metrics
@@ -86,57 +152,16 @@ Wants=network-online.target
86152

87153
[Service]
88154
Type=simple
89-
ExecStart=(command to run as service)
155+
ExecStart=# docker command #
90156

91157
[Install]
92158
WantedBy=multi-user.target
93159
```
94160

95161
Reload services, enable it, start it and check if it is up and running:
96-
97162
```shell
98163
systemctl daemon-reload
99164
systemctl enable github_metrics
100165
systemctl start github_metrics
101166
systemctl status github_metrics
102167
```
103-
104-
### Alternative option: run an instance locally (intended for testing and development)
105-
106-
To run an instance without docker, you'll need to have [NodeJS](https://nodejs.org) (see used version in [Dockerfile](/Dockerfile#L1-L2)) installed.
107-
108-
Clone repository, install dependencies and copy configuration example to `settings.json`:
109-
110-
```shell
111-
git clone https://github.com/lowlighter/metrics.git
112-
cd metrics/
113-
npm install --only=prod
114-
cp settings.example.json settings.json
115-
```
116-
117-
Once you've finished configuring metrics, start your instance using the following command:
118-
119-
```shell
120-
npm start
121-
```
122-
123-
You should now be able to access your server with provided port in `setting.json` from your browser.
124-
125-
## 🔗 HTTP parameters
126-
127-
Most of options from [action.yml](/action.yml) are actually supported by web instance, though syntax is slightly different.
128-
All underscores (`_`) must be replaced by dots (`.`) and `plugin_` prefixes must be dropped.
129-
130-
For example, to configure pagespeed plugin you'd use the following:
131-
```
132-
https://my-personal-domain.com/my-github-user?pagespeed=1&pagespeed.detailed=1&pagespeed.url=https%3A%2F%2Fexample.com
133-
```
134-
135-
Note that url parameters must be [encoded](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Objets_globaux/encodeURIComponent).
136-
137-
As for `base` content, which is enabled by default, sections are available through "`base.<section>`".
138-
139-
For example, to display only `repositories` section, use:
140-
```
141-
https://my-personal-domain.com/my-github-user?base=0&base.repositories=1
142-
```

0 commit comments

Comments
 (0)