logos-co/logos-messaging-module
1
0
Fork 0
mirror of https://github.com/logos-co/logos-messaging-module.git synced 2026-08-27 10:41:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add prebuilt-binary run path to run-node guide (#54)

Browse Source 
* docs: add prebuilt-binary run path (no build) to run-node guide

Document running a node without building from source: download the
logoscore daemon AppImage, the lgpm package manager, and this module's
prebuilt delivery_module.lgx from the logos-modules release, install with
lgpm, and boot the node — same load-module / createNode / start calls,
defaulting to the logos.test fleet.

Splits "Without Docker" into "prebuilt binaries" (Linux only) and "build
with Nix" (any platform). All three methods default to logos.test.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: fix prebuilt module source to logos-modules-release (logos.test)

The modules release repo was renamed to logos-modules-release and now
publishes per-module, versioned releases (no rolling `latest`). Point the
prebuilt delivery_module download at the versioned tag/asset
(delivery_module-v0.1.3 / delivery_module-0.1.3.lgx) and note that the
logos.test preset needs delivery_module >= 0.1.3 — earlier builds only
support twn and logos.dev.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: prebuilt path uses lgpd + covers macOS

Rework the prebuilt-binary section around the canonical downloader flow
used by logos-docker: fetch the module with `lgpd download delivery_module`
(its built-in catalog is logos-modules-release) and install with
`lgpm install`, instead of curling a release asset by hand.

Add macOS (Apple Silicon) alongside Linux — logoscore/lgpd/lgpm are all
published for both. Keep the note that logos.test needs delivery_module
>= 0.1.3, and mention the direct-.lgx fallback.

Verified end-to-end on macOS (host) and Linux (VM): lgpd download ->
lgpm install -> logoscore createNode @logos-test.json -> start, with the
node dialing the logos.test bootstrap fleet on both.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: resolve tools from latest release, move Metrics to run-node

- Prebuilt path: drop pinned pre-release tags; a latest()/dl() helper
  pair resolves each tool's newest release from the GitHub API, so no
  version is hardcoded.
- Move the Metrics (openmetrics scrape) instructions from README into
  run-node.md as a "## Metrics" section; README keeps the API reference
  and links to it.
- Drop the trailing note block from the prebuilt section.

Verified the exact doc commands on macOS: latest()/dl() -> tools on PATH,
lgpd download delivery_module -> 0.1.3, lgpm install.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: simplify prebuilt setup to a one-line install script

Replace the two helper functions + per-OS download blocks with
scripts/install-node-tools.sh, which detects OS/arch, resolves the latest
release of logoscore/lgpd/lgpm, and drops them in ./bin. The doc shrinks
to a curl one-liner + the lgpd/lgpm/run steps.

The script handles the per-OS packaging (Linux AppImage vs macOS app
tree) so the doc no longer has to. Verified on macOS + Linux: the script
installs all three working CLIs; lgpd download -> lgpm install -> boot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: pin tool releases instead of resolving latest

Drop the GitHub API lookup; install-node-tools.sh now pins the current
releases of logoscore/lgpd/lgpm via *_TAG vars (bump to upgrade). Removes
the unauthenticated API call (and its rate-limit failure mode) from the
install path.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Igor Sirotin
2026-06-24 17:18:47 +01:00
committed by GitHub
co-authored by Claude Opus 4.8
parent 794c21cbe1
commit ab904fd4c2
3 changed files with 149 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -21
View File
@@ -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
docs/run-node.md
+87 -9
View File
@@ -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).
scripts/install-node-tools.sh
Executable
+56
View File
@@ -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 <repo> <tool> <tag>: download <tool>-<arch>-<os>.tar.gz, expose ./bin/<tool>
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 <tool>-<arch>-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 <tool>-<arch>.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\""