Skip to content
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.

Commit adee252

Browse files
MaelkumMaelkum
authoredNov 13, 2024··
Documentation update (#174)
* Update b7s flags * Simplify documentation wording * Split flags in groups based on what they impact - similar to the config file * Update example YAML file * Update docs page * Update code for generating config docs * Remove half-baked markdown thing - use just HTML until done right
1 parent 86fd1f6 commit adee252

File tree

9 files changed

+269
-127
lines changed

9 files changed

+269
-127
lines changed
 

‎README.md

+58-23
Original file line numberDiff line numberDiff line change
@@ -24,29 +24,64 @@ You can also use Docker to install b7s. See the [Docker documentation](/docker/R
2424

2525
## Usage
2626

27-
For a more detailed overview of the configuration options, see the [b7s-node Readme](/cmd/node/README.md#usage).
28-
29-
| Flag | Short Form | Default Value | Description |
30-
| ------------------------- | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
31-
| config | N/A | N/A | Specifies the config file to load. |
32-
| log-level | -l | "info" | Specifies the level of logging to use. |
33-
| db | N/A | "db" | Specifies the path to database used for persisting peer and function data. |
34-
| role | -r | "worker" | Specifies the role this node will have in the Blockless protocol (head or worker). |
35-
| address | -a | "0.0.0.0" | Specifies the address that the libp2p host will use. |
36-
| port | -p | 0 | Specifies the port that the libp2p host will use. |
37-
| websocket-port | N/A | 0 | Specifies the port that the libp2p host will use for websocket connections. |
38-
| private-key | N/A | N/A | Specifies the private key that the libp2p host will use. |
39-
| concurrency | -c | node.DefaultConcurrency | Specifies the maximum number of requests the node will process in parallel. |
40-
| rest-api | N/A | N/A | Specifies the address where the head node REST API will listen on. |
41-
| boot-nodes | N/A | N/A | Specifies a list of addresses that this node will connect to on startup, in multiaddr format. |
42-
| workspace | N/A | "./workspace" | Specifies the directory that the node can use for file storage. |
43-
| runtime | N/A | N/A | Specifies the runtime address used by the worker node. |
44-
| dialback-address | N/A | N/A | Specifies the advertised dialback address of the Node. |
45-
| dialback-port | N/A | N/A | Specifies the advertised dialback port of the Node. |
46-
| websocket-dialback-port | N/A | 0 | Specifies the advertised dialback port for Websocket connections. |
47-
| cpu-percentage-limit | N/A | 1.0 | Specifies the amount of CPU time allowed for Blockless Functions in the 0-1 range, 1 being unlimited. |
48-
| memory-limit | N/A | N/A | Specifies the memory limit for Blockless Functions, in kB. |
49-
| no-dialback-peers | N/A | false | Specifies if the node should avoid dialing back peers known from past runs |
27+
For a more detailed overview of the node options and their meaning see [b7s-node Readme](/cmd/node/README.md#usage).
28+
You can see an example YAML config file [here](/cmd/node/example.yaml).
29+
30+
### General Flags
31+
32+
| Flag | Short Form | Default Value | Description |
33+
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
34+
| config | N/A | N/A | Config file to load. |
35+
| log-level | -l | "info" | Level of logging to use. |
36+
| db | N/A | "db" | Path to database used for persisting peer and function data. |
37+
| role | -r | "worker" | Role this node will have in the Blockless protocol (head or worker). |
38+
| workspace | N/A | "./workspace" | Directory that the node will use for file storage. |
39+
| concurrency | -c | node.DefaultConcurrency | Maximum number of requests the node will process in parallel. |
40+
| load-attributes | N/A | false | Load attributes from the environment. |
41+
| topics | N/A | N/A | Topics that the node should subscribe to. |
42+
43+
### Connectivity
44+
45+
| Flag | Short Form | Default Value | Description |
46+
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
47+
| address | -a | "0.0.0.0" | Address that the libp2p host will use. |
48+
| port | -p | 0 | Port that the libp2p host will use. |
49+
| private-key | N/A | N/A | Private key that the libp2p host will use. |
50+
| boot-nodes | N/A | N/A | List of addresses that this node will connect to on startup, in multiaddr format. |
51+
| websocket | -w | false | Use websocket protocol for communication, besides TCP. |
52+
| websocket-port | N/A | 0 | Port that the libp2p host will use for websocket connections. |
53+
| dialback-address | N/A | N/A | Advertised dialback address of the Node. |
54+
| dialback-port | N/A | N/A | Advertised dialback port of the Node. |
55+
| websocket-dialback-port | N/A | 0 | Advertised dialback port for Websocket connections. |
56+
| no-dialback-peers | N/A | false | Avoid dialing back peers known from past runs |
57+
| must-reach-boot-nodes | N/A | false | Halt if the Node cannot reach boot nodes on startup. |
58+
| disable-connection-limits | N/A | false | Try to maintain as many connections as possible. |
59+
| connection-count | N/A | N/A | Number of connections that the node will aim to have. |
60+
61+
### Worker Node
62+
63+
| Flag | Short Form | Default Value | Description |
64+
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------------- |
65+
| runtime-path | N/A | N/A | Local path to the Blockless Runtime. |
66+
| runtime-cli | N/A | "bls-runtime" | Name of the Blockless Runtime executable, as found in the runtime-path. |
67+
| cpu-percentage-limit | N/A | 1.0 | Amount of CPU time allowed for Blockless Functions in the 0-1 range, 1 being unlimited (100%) |
68+
| memory-limit | N/A | N/A | Memory limit for Blockless Functions, in kB. |
69+
70+
### Head Node
71+
72+
| Flag | Short Form | Default Value | Description |
73+
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
74+
| rest-api | N/A | N/A | Address where the head node will serve the REST API |
75+
76+
### Telemetry
77+
78+
| Flag | Short Form | Default Value | Description |
79+
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
80+
| enable-tracing | N/A | false | Emit tracing data. |
81+
| tracing-grpc-endpoint | N/A | N/A | GRPC endpoint where node should send tracing data. |
82+
| tracing-http-endpoint | N/A | N/A | HTTP endpoint where node should send tracing data. |
83+
| enable-metrics | N/A | false | Enable metrics. |
84+
| prometheus-address | N/A | N/A | Address where node should serve metrics (for head node this is the REST API address) |
5085

5186
## Dependencies
5287

‎cmd/b7s-node-docs/assets/css/style.css

+10-7
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,6 @@ h1 {
1313
margin-bottom: 20px;
1414
}
1515

16-
h3 {
17-
color: #666;
18-
margin-top: 20px;
19-
}
20-
2116
ul {
2217
list-style-type: none;
2318
padding: 0;
@@ -28,7 +23,11 @@ li {
2823
padding: 20px;
2924
}
3025

31-
li.cfg {
26+
div.cfg-list {
27+
padding: 0;
28+
}
29+
30+
div.cfg {
3231
background-color: #fff;
3332
border-radius: 15px;
3433
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
@@ -56,7 +55,7 @@ li.cli {
5655
margin-left: 20px;
5756
}
5857

59-
h3 {
58+
h2 {
6059
color: #333;
6160
margin-top: 0;
6261
}
@@ -65,6 +64,10 @@ p {
6564
margin: 5px 0;
6665
}
6766

67+
p.description {
68+
margin: 10px 10px;
69+
}
70+
6871
dl {
6972
margin: 0;
7073
}

‎cmd/b7s-node-docs/b7sdocs.templ

+18-11
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ package main
33
import "fmt"
44
import "github.com/blocklessnetwork/b7s/config"
55

6-
templ page(configs []config.ConfigOption) {
6+
templ page(version string, configs []config.ConfigOption) {
77
<html>
88
<head>
99
<title>Blockless B7S Node Configuration</title>
@@ -12,26 +12,33 @@ templ page(configs []config.ConfigOption) {
1212
</head>
1313
<body>
1414
<h1>Blockless B7S Node Configuration</h1>
15-
<p>
15+
16+
<p class="description">
1617
This page lists all of the configuration options supported by the b7s daemon.
1718
It showcases the configuration structure, as accepted in a YAML config file, environment variables that can be used to set those options and, where applicable, the CLI flags and their default values.
1819
</p>
1920

2021
@b7sdocs(configs)
22+
23+
if version != "" {
24+
<footer>
25+
<small>Node version: {version}</small>
26+
</footer>
27+
}
28+
2129
</body>
2230
</html>
2331
}
2432

25-
2633
templ b7sdocs(configs []config.ConfigOption) {
2734

28-
<ul>
29-
for _, cfg := range configs {
30-
<li class="cfg">
31-
@configOption(cfg)
32-
</li>
33-
}
34-
</ul>
35+
<div class="cfg-list">
36+
for _, cfg := range configs {
37+
<div class="cfg">
38+
@configOption(cfg)
39+
</div>
40+
}
41+
</div>
3542
}
3643

3744
func formatCLIDefault(def any) string {
@@ -45,7 +52,7 @@ func formatCLIDefault(def any) string {
4552

4653
templ configOption(cfg config.ConfigOption) {
4754

48-
<h3 id={cfg.FullPath}>{cfg.Name} <a class="link-icon" href={ templ.URL(fmt.Sprintf("#%s", cfg.FullPath)) }><span >&#128279;</span></a></h3>
55+
<h2 id={cfg.FullPath}>{cfg.Name} <a class="link-icon" href={ templ.URL(fmt.Sprintf("#%s", cfg.FullPath)) }><span >&#128279;</span></a></h2>
4956

5057
if cfg.Type() != "" {
5158
<p>Type: {cfg.Type()}</p>

‎cmd/b7s-node-docs/b7sdocs_templ.go

+111-77
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎cmd/b7s-node-docs/main.go

+6-2
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import (
1212
"github.com/spf13/pflag"
1313

1414
"github.com/blocklessnetwork/b7s/config"
15+
"github.com/blocklessnetwork/b7s/info"
1516
)
1617

1718
//go:embed assets/*
@@ -30,7 +31,7 @@ func main() {
3031
pflag.Parse()
3132

3233
configs := config.GetConfigDocumentation()
33-
component := page(configs)
34+
component := page(info.VcsVersion(), configs)
3435

3536
if flagOutput != "" {
3637

@@ -44,7 +45,10 @@ func main() {
4445
log.Fatalf("could not render component: %s", err)
4546
}
4647

47-
f.Close()
48+
err = f.Close()
49+
if err != nil {
50+
log.Fatalf("could not close file: %s", err)
51+
}
4852
return
4953
}
5054

‎cmd/node/README.md

+19-2
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ Head Nodes also serve a REST API that can be used to query or trigger certain ac
1919

2020
## Usage
2121

22-
There are two ways of specifying configuration options - the CLI flags and a config file.
22+
There are two main ways of specifying configuration options - the CLI flags and a config file.
2323
CLI flags override any configuration options in the config file.
2424

2525
List of supported CLI flags is listed below.
@@ -43,11 +43,19 @@ Usage of b7s-node:
4343
--websocket-port uint port to use for websocket connections
4444
--websocket-dialback-port uint external port that the b7s host will advertise for websocket connections
4545
--no-dialback-peers start without dialing back peers from previous runs
46+
--must-reach-boot-nodes halt node if we fail to reach boot nodes on start
47+
--disable-connection-limits disable libp2p connection limits (experimental)
48+
--connection-count uint maximum number of connections the b7s host will aim to have
4649
--rest-api string address where the head node REST API will listen on
4750
--runtime-path string Blockless Runtime location (used by the worker node)
4851
--runtime-cli string runtime CLI name (used by the worker node)
4952
--cpu-percentage-limit float amount of CPU time allowed for Blockless Functions in the 0-1 range, 1 being unlimited
5053
--memory-limit int memory limit (kB) for Blockless Functions
54+
--enable-tracing emit tracing data
55+
--tracing-grpc-endpoint string tracing exporter GRPC endpoint
56+
--tracing-http-endpoint string tracing exporter HTTP endpoint
57+
--enable-metrics emit metrics
58+
--prometheus-address string address where prometheus metrics will be served
5159
--config string path to a config file
5260
```
5361

@@ -61,7 +69,7 @@ Example configuration for a worker node:
6169
role: worker
6270
concurrency: 10
6371
workspace: /tmp/workspace
64-
attributes: false
72+
load-attributes: false
6573

6674
log:
6775
level: debug
@@ -77,6 +85,15 @@ worker:
7785
runtime-path: /home/user/.local/blockless-runtime/bin
7886
cpu-percentage-limit: 0.8
7987

88+
telemetry:
89+
tracing:
90+
enable: true
91+
http:
92+
endpoint:
93+
metrics:
94+
enable: true
95+
prometeus-address: 0.0.0.0:8080
96+
8097
```
8198

8299
You can find a more complete reference in [example.yaml](/cmd/node/example.yaml).

‎cmd/node/example.yaml

+45-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,10 @@
1414
# boot-nodes: []
1515

1616
# should the node load its attributes from IPFS/IPNS
17-
# attributes: false
17+
# load-attributes: false
18+
19+
# topics this node should subscribe to
20+
# topics: []
1821

1922
# log information
2023
# log:
@@ -45,6 +48,18 @@
4548
# external port the node will advertise for websocket communication
4649
# websocket-dialback-port: 9010
4750

51+
# do not dial back peers known from past runs
52+
# no-dialback-peers: false
53+
54+
# halt if the node cannot reach boot nodes
55+
# must-reach-dialback-peers: false
56+
57+
# try to maintain as many connections as possible (useful for head nodes that need to be connected to many workers)
58+
# disablle-connection-limits: false
59+
60+
# number of connections node will aim to have
61+
# connection-count: 512
62+
4863

4964
# head node configuration
5065
# head:
@@ -56,8 +71,37 @@
5671
# local path to Blockless Runtime
5772
# runtime-path: /path/to/blockless/runtime
5873

74+
# name of the Runtime executable
75+
# runtime-cli: bls-runtime
76+
5977
# max percentage of CPU time Blockless will use for execution (1.0 for 100%)
6078
# cpu-percentage-limit: 1.0
6179

6280
# max amount of memory (in kB) Blockless will use for execution (0 is unlimited)
6381
# memory-limit: 0
82+
83+
# telemetry:
84+
# tracing:
85+
# should node emit tracing information
86+
# enable: false
87+
88+
# how often should tracing information be sent
89+
# exporter-batch-timeout: 5s
90+
91+
# configuration for tracing over GRPC
92+
# grpc:
93+
# endpoint where tracing data will be sent over GRPC.
94+
# endpoint: localhost:4317
95+
96+
# configuration for tracing over HTTP
97+
# http:
98+
# endpoint where tracing data will be sent over HTTP.
99+
# endpoint: localhost:4318
100+
101+
# metrics:
102+
# should node publish metrics
103+
# enable: false
104+
105+
# address where node should serve metrics on
106+
# prometheus-address: localhost:8888
107+

‎config/config.go

+1-3
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,14 @@ package config
22

33
import (
44
"time"
5-
6-
"github.com/blocklessnetwork/b7s/node"
75
)
86

97
// Default values.
108
const (
119
DefaultPort = uint(0)
1210
DefaultAddress = "0.0.0.0"
1311
DefaultRole = "worker"
14-
DefaultConcurrency = uint(node.DefaultConcurrency)
12+
DefaultConcurrency = 10
1513
DefaultUseWebsocket = false
1614
DefaultLogLevel = "info"
1715
)

‎go.mod

+1-1
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,7 @@ require (
152152
github.com/google/uuid v1.6.0
153153
github.com/hashicorp/errwrap v1.1.0 // indirect
154154
github.com/hashicorp/go-multierror v1.1.1
155-
github.com/hashicorp/golang-lru v1.0.2 // indirect
155+
github.com/hashicorp/golang-lru v1.0.2
156156
github.com/huin/goupnp v1.3.0 // indirect
157157
github.com/ipfs/go-cid v0.4.1 // indirect
158158
github.com/ipfs/go-datastore v0.6.0 // indirect

0 commit comments

Comments
 (0)
Please sign in to comment.