diff --git a/README.md b/README.md index 70b9131..d4b2f08 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ The delivery module provides the following API methods (all synchronous, all ret - `getAvailableNodeInfoIDs()` - List queryable node info identifiers - `getNodeInfo(nodeInfoId: QString)` - Retrieve node info by identifier - `getAvailableConfigs()` - Retrieve available configuration parameter descriptions -- `collectOpenMetricsText()` - Node metrics as OpenMetrics/Prometheus text for the `openmetrics` module (see [Metrics](#metrics)) +- `collectOpenMetricsText()` - Node metrics as OpenMetrics/Prometheus text for the `openmetrics` module (see [docs/run-node.md → Metrics](docs/run-node.md#metrics)) ### Node Configuration (`createNode`) @@ -202,26 +202,11 @@ carries a `QVariantList data` with positional values: ### Metrics -The node already aggregates Prometheus metrics internally (the same set exposed -on `metricsServerPort`, rendered behind the `"Metrics"` node-info attribute). -`collectOpenMetricsText()` hands that exposition text back **verbatim** so the -[`openmetrics`](https://github.com/logos-co/openmetrics-module) module can scrape -this module without standing up a separate HTTP server — no in-module parsing or -reshaping. The openmetrics scraper parses the text, injects a -`module="delivery_module"` label on every series, and merges it with other -modules. - -Point the `openmetrics` module at this one by name, selecting the text-source -convention with `"format": "text"`: - -```bash -logoscore --config-dir /tmp/om call openmetrics start \ - '{"port":9090,"modules":[{"name":"delivery_module","format":"text"}]}' -curl http://localhost:9090/metrics # every series carries module="delivery_module" -``` - -Before a node is created (or if the read fails) `collectOpenMetricsText()` -returns an empty document so a scrape never errors out on this module. +`collectOpenMetricsText()` returns the node's internal Prometheus metrics as +OpenMetrics/Prometheus exposition text for the +[`openmetrics`](https://github.com/logos-co/openmetrics-module) module to scrape. +For how to wire up `openmetrics` and scrape a running node, see +[Running a node → Metrics](docs/run-node.md#metrics). ## Architecture diff --git a/docs/run-node.md b/docs/run-node.md index 5c584f9..88a35e5 100644 --- a/docs/run-node.md +++ b/docs/run-node.md @@ -1,12 +1,15 @@ # Run a delivery node Runs a delivery node (`logoscore` daemon + `delivery_module`). There is no GUI -or HTTP API — interaction is via the `logoscore` CLI. You can run it two ways: +or HTTP API — interaction is via the `logoscore` CLI. You can run it three ways: - [With Docker](#with-docker) — quickest; everything runs in a container. -- [Without Docker](#without-docker) — build and run natively with Nix. +- [Prebuilt binaries](#without-docker-prebuilt-binaries) — download release + binaries, nothing to build (Linux and macOS). +- [Build with Nix](#without-docker-build-with-nix) — build from source on any + platform. -Both connect the node to the `logos.test` fleet by default. +All three connect the node to the `logos.test` fleet by default. ## With Docker @@ -47,7 +50,55 @@ docker exec logos-node logoscore status --json docker compose down ``` -## Without Docker +## Without Docker: prebuilt binaries + +Run a node from released binaries — nothing to build, no repository clone. You +need three CLIs from the Logos releases: + +- **`logoscore`** — the node daemon ([logos-logoscore-cli](https://github.com/logos-co/logos-logoscore-cli)) +- **`lgpd`** — package downloader, fetches modules from the Logos catalog + ([logos-package-downloader](https://github.com/logos-co/logos-package-downloader)) +- **`lgpm`** — package manager, installs them locally + ([logos-package-manager](https://github.com/logos-co/logos-package-manager)) + +All three are published for Linux (`x86_64` / `aarch64`) and macOS (Apple +Silicon / `aarch64`). + +### Install the tools + +This downloads `logoscore`, `lgpd`, and `lgpm` for your OS/arch into `./bin` +(the script pins a known-good release of each — bump the `*_TAG` values in it to +move to newer builds): + +```bash +curl -fsSL https://raw.githubusercontent.com/logos-co/logos-delivery-module/master/scripts/install-node-tools.sh | sh +export PATH="$PWD/bin:$PATH" +``` + +### Download the module and boot the node + +```bash +# Fetch delivery_module from the Logos catalog, then install it into ./modules +mkdir -p packages modules +lgpd download delivery_module --output ./packages +lgpm install --dir ./packages --modules-dir ./modules + +# logos.test node config +cat > logos-test.json <<'JSON' +{ "preset": "logos.test", "logLevel": "DEBUG" } +JSON + +# Run the daemon (it binds capability_module automatically, so ./modules only +# needs delivery_module), then boot the node +logoscore -D -m ./modules > logs.txt & +logoscore load-module delivery_module +logoscore call delivery_module createNode @logos-test.json +logoscore call delivery_module start +``` + +Verify with `logoscore status`; stop with `logoscore stop`. + +## Without Docker: build with Nix Build the runtime and this module with Nix, then run the `logoscore` daemon directly on the host. @@ -118,11 +169,12 @@ logoscore stop ## Configuration -The node config is [`conf/logos-test.json`](../conf/logos-test.json); it uses -the `logos.test` network preset. With Docker it is mounted into the container -at `/conf` (`@/conf/logos-test.json`); without Docker, pass the path directly -(`@conf/logos-test.json`). Edit it and re-run the boot steps to change -settings. +The node config is just the `logos.test` network preset. The repo ships it as +[`conf/logos-test.json`](../conf/logos-test.json): with Docker it is mounted +into the container at `/conf` (`@/conf/logos-test.json`); with the Nix build, +pass the path directly (`@conf/logos-test.json`). The prebuilt-binaries path +above writes the same config inline as `logos-test.json` so no clone is needed. +Edit it and re-run the boot steps to change settings. To target the dev network instead, use [`conf/logos-dev.json`](../conf/logos-dev.json) (preset `logos.dev`). Available @@ -131,3 +183,29 @@ keys are documented in the The node is now connected to the `logos.test` network. See [`query-node.md`](./query-node.md) to read its peer ID, ENR, and metrics. + +## Metrics + +The node already aggregates Prometheus metrics internally (the same set exposed +on `metricsServerPort`, rendered behind the `"Metrics"` node-info attribute). +`collectOpenMetricsText()` hands that exposition text back **verbatim** so the +[`openmetrics`](https://github.com/logos-co/openmetrics-module) module can scrape +this module without standing up a separate HTTP server — no in-module parsing or +reshaping. The openmetrics scraper parses the text, injects a +`module="delivery_module"` label on every series, and merges it with other +modules. + +Point the `openmetrics` module at this one by name, selecting the text-source +convention with `"format": "text"`: + +```bash +logoscore --config-dir /tmp/om call openmetrics start \ + '{"port":9090,"modules":[{"name":"delivery_module","format":"text"}]}' +curl http://localhost:9090/metrics # every series carries module="delivery_module" +``` + +Before a node is created (or if the read fails) `collectOpenMetricsText()` +returns an empty document so a scrape never errors out on this module. + +For a one-off read without the `openmetrics` module, the raw exposition text is +also available via `getNodeInfo Metrics` — see [`query-node.md`](./query-node.md). diff --git a/scripts/install-node-tools.sh b/scripts/install-node-tools.sh new file mode 100755 index 0000000..a2f81d1 --- /dev/null +++ b/scripts/install-node-tools.sh @@ -0,0 +1,56 @@ +#!/bin/sh +# Download the Logos node CLIs — logoscore, lgpd, lgpm — into ./bin. +# +# Unpacks a pinned release of each tool for the host OS/arch. Works on Linux +# (x86_64/aarch64) and macOS (Apple Silicon). To move to newer builds, bump the +# *_TAG values below. After it finishes: export PATH="$PWD/bin:$PATH" +set -eu + +# Pinned tool releases (latest at time of writing). +LOGOSCORE_TAG=pre-release-8002477-4 +LGPD_TAG=pre-release-99d70db-7 +LGPM_TAG=pre-release-05b2cf8-7 + +os=$(uname -s | tr '[:upper:]' '[:lower:]') +if [ "$os" = darwin ]; then os=macos; fi +arch=$(uname -m) +if [ "$arch" = arm64 ]; then arch=aarch64; fi + +case "$os" in + linux|macos) ;; + *) echo "unsupported OS: $os (Linux/macOS only)" >&2; exit 1 ;; +esac + +bin="$PWD/bin" +mkdir -p "$bin" + +# fetch : download --.tar.gz, expose ./bin/ +fetch() { + repo=$1; tool=$2; tag=$3 + echo " $tool ($tag)" + tmp=$(mktemp -d) + curl -fsSL "https://github.com/logos-co/$repo/releases/download/$tag/$tool-$arch-$os.tar.gz" \ + | tar xz -C "$tmp" + if [ "$os" = macos ]; then + # tarball is --macos/{bin,lib,...}; the binary finds its bundled + # libs/modules relative to its real path, so wrap it (a symlink would break + # that resolution) rather than linking. + rm -rf "$bin/$tool-$arch-macos" + mv "$tmp/$tool-$arch-macos" "$bin/" + printf '#!/bin/sh\nexec "%s/%s-%s-macos/bin/%s" "$@"\n' "$bin" "$tool" "$arch" "$tool" > "$bin/$tool" + chmod +x "$bin/$tool" + else + # tarball is a single -.AppImage + mv "$tmp/$tool-$arch.AppImage" "$bin/$tool" + chmod +x "$bin/$tool" + fi + rm -rf "$tmp" +} + +echo "Installing Logos node tools for $os/$arch into $bin ..." +fetch logos-logoscore-cli logoscore "$LOGOSCORE_TAG" +fetch logos-package-downloader lgpd "$LGPD_TAG" +fetch logos-package-manager lgpm "$LGPM_TAG" +echo +echo "Done. Put them on your PATH:" +echo " export PATH=\"$bin:\$PATH\""