Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation update #174

Merged
merged 7 commits into from
Nov 13, 2024
Merged

Documentation update #174

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c28af08
Update b7s flags
Maelkum Oct 29, 2024
37459b7
Simplify documentation wording
Maelkum Oct 29, 2024
749c35c
Split flags in groups based on what they impact - similar to the conf…
Maelkum Oct 29, 2024
43ab440
Update example YAML file
Maelkum Oct 29, 2024
a3d4173
Update docs page
Maelkum Oct 30, 2024
f21fa6a
Update code for generating config docs
Maelkum Oct 30, 2024
f8d91ef
Remove half-baked markdown thing - use just HTML until done right
Maelkum Oct 31, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 58 additions & 23 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,29 +24,64 @@ You can also use Docker to install b7s. See the [Docker documentation](/docker/R

## Usage

For a more detailed overview of the configuration options, see the [b7s-node Readme](/cmd/node/README.md#usage).

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | ----------------------------------------------------------------------------------------------------- |
| config | N/A | N/A | Specifies the config file to load. |
| log-level | -l | "info" | Specifies the level of logging to use. |
| db | N/A | "db" | Specifies the path to database used for persisting peer and function data. |
| role | -r | "worker" | Specifies the role this node will have in the Blockless protocol (head or worker). |
| address | -a | "0.0.0.0" | Specifies the address that the libp2p host will use. |
| port | -p | 0 | Specifies the port that the libp2p host will use. |
| websocket-port | N/A | 0 | Specifies the port that the libp2p host will use for websocket connections. |
| private-key | N/A | N/A | Specifies the private key that the libp2p host will use. |
| concurrency | -c | node.DefaultConcurrency | Specifies the maximum number of requests the node will process in parallel. |
| rest-api | N/A | N/A | Specifies the address where the head node REST API will listen on. |
| boot-nodes | N/A | N/A | Specifies a list of addresses that this node will connect to on startup, in multiaddr format. |
| workspace | N/A | "./workspace" | Specifies the directory that the node can use for file storage. |
| runtime | N/A | N/A | Specifies the runtime address used by the worker node. |
| dialback-address | N/A | N/A | Specifies the advertised dialback address of the Node. |
| dialback-port | N/A | N/A | Specifies the advertised dialback port of the Node. |
| websocket-dialback-port | N/A | 0 | Specifies the advertised dialback port for Websocket connections. |
| 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. |
| memory-limit | N/A | N/A | Specifies the memory limit for Blockless Functions, in kB. |
| no-dialback-peers | N/A | false | Specifies if the node should avoid dialing back peers known from past runs |
For a more detailed overview of the node options and their meaning see [b7s-node Readme](/cmd/node/README.md#usage).
You can see an example YAML config file [here](/cmd/node/example.yaml).

### General Flags

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
| config | N/A | N/A | Config file to load. |
| log-level | -l | "info" | Level of logging to use. |
| db | N/A | "db" | Path to database used for persisting peer and function data. |
| role | -r | "worker" | Role this node will have in the Blockless protocol (head or worker). |
| workspace | N/A | "./workspace" | Directory that the node will use for file storage. |
| concurrency | -c | node.DefaultConcurrency | Maximum number of requests the node will process in parallel. |
| load-attributes | N/A | false | Load attributes from the environment. |
| topics | N/A | N/A | Topics that the node should subscribe to. |

### Connectivity

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
| address | -a | "0.0.0.0" | Address that the libp2p host will use. |
| port | -p | 0 | Port that the libp2p host will use. |
| private-key | N/A | N/A | Private key that the libp2p host will use. |
| boot-nodes | N/A | N/A | List of addresses that this node will connect to on startup, in multiaddr format. |
| websocket | -w | false | Use websocket protocol for communication, besides TCP. |
| websocket-port | N/A | 0 | Port that the libp2p host will use for websocket connections. |
| dialback-address | N/A | N/A | Advertised dialback address of the Node. |
| dialback-port | N/A | N/A | Advertised dialback port of the Node. |
| websocket-dialback-port | N/A | 0 | Advertised dialback port for Websocket connections. |
| no-dialback-peers | N/A | false | Avoid dialing back peers known from past runs |
| must-reach-boot-nodes | N/A | false | Halt if the Node cannot reach boot nodes on startup. |
| disable-connection-limits | N/A | false | Try to maintain as many connections as possible. |
| connection-count | N/A | N/A | Number of connections that the node will aim to have. |

### Worker Node

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------------- |
| runtime-path | N/A | N/A | Local path to the Blockless Runtime. |
| runtime-cli | N/A | "bls-runtime" | Name of the Blockless Runtime executable, as found in the runtime-path. |
| cpu-percentage-limit | N/A | 1.0 | Amount of CPU time allowed for Blockless Functions in the 0-1 range, 1 being unlimited (100%) |
| memory-limit | N/A | N/A | Memory limit for Blockless Functions, in kB. |

### Head Node

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
| rest-api | N/A | N/A | Address where the head node will serve the REST API |

### Telemetry

| Flag | Short Form | Default Value | Description |
| ------------------------- | ---------- | ----------------------- | --------------------------------------------------------------------------------------- |
| enable-tracing | N/A | false | Emit tracing data. |
| tracing-grpc-endpoint | N/A | N/A | GRPC endpoint where node should send tracing data. |
| tracing-http-endpoint | N/A | N/A | HTTP endpoint where node should send tracing data. |
| enable-metrics | N/A | false | Enable metrics. |
| prometheus-address | N/A | N/A | Address where node should serve metrics (for head node this is the REST API address) |

## Dependencies

Expand Down
17 changes: 10 additions & 7 deletions cmd/b7s-node-docs/assets/css/style.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,6 @@ h1 {
margin-bottom: 20px;
}

h3 {
color: #666;
margin-top: 20px;
}

ul {
list-style-type: none;
padding: 0;
Expand All @@ -28,7 +23,11 @@ li {
padding: 20px;
}

li.cfg {
div.cfg-list {
padding: 0;
}

div.cfg {
background-color: #fff;
border-radius: 15px;
box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
Expand Down Expand Up @@ -56,7 +55,7 @@ li.cli {
margin-left: 20px;
}

h3 {
h2 {
color: #333;
margin-top: 0;
}
Expand All @@ -65,6 +64,10 @@ p {
margin: 5px 0;
}

p.description {
margin: 10px 10px;
}

dl {
margin: 0;
}
Expand Down
29 changes: 18 additions & 11 deletions cmd/b7s-node-docs/b7sdocs.templ
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ package main
import "fmt"
import "github.com/blocklessnetwork/b7s/config"

templ page(configs []config.ConfigOption) {
templ page(version string, configs []config.ConfigOption) {
<html>
<head>
<title>Blockless B7S Node Configuration</title>
Expand All @@ -12,26 +12,33 @@ templ page(configs []config.ConfigOption) {
</head>
<body>
<h1>Blockless B7S Node Configuration</h1>
<p>

<p class="description">
This page lists all of the configuration options supported by the b7s daemon.
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.
</p>

@b7sdocs(configs)

if version != "" {
<footer>
<small>Node version: {version}</small>
</footer>
}

</body>
</html>
}


templ b7sdocs(configs []config.ConfigOption) {

<ul>
for _, cfg := range configs {
<li class="cfg">
@configOption(cfg)
</li>
}
</ul>
<div class="cfg-list">
for _, cfg := range configs {
<div class="cfg">
@configOption(cfg)
</div>
}
</div>
}

func formatCLIDefault(def any) string {
Expand All @@ -45,7 +52,7 @@ func formatCLIDefault(def any) string {

templ configOption(cfg config.ConfigOption) {

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

if cfg.Type() != "" {
<p>Type: {cfg.Type()}</p>
Expand Down
Loading
Loading