# Run a delivery node Runs a delivery node (a Logos Core daemon + `delivery_module` 0.4.0, for Logos Testnet v0.3). There is no GUI or HTTP API — interaction is via the daemon's CLI (`logosctl`, or `logoscore` in the Nix setup). You can run it three ways: - [With Docker](#with-docker) — quickest; everything runs in a container. - [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. All three connect the node to the `logos.test` fleet by default. A node that other peers should be able to dial also needs its [public address](#public-address) set. ## With Docker ### Prerequisites - Docker with Compose ### Start ```bash git clone https://github.com/logos-co/logos-delivery-module.git cd logos-delivery-module docker compose up -d --build ``` The image is built from [logos-docker](https://github.com/logos-co/logos-docker): the `logosctl` daemon with `delivery_module` 0.4.0 and the RLN modules (`liblogos_rln_module` 0.12.0, `liblogos_lez_rln_module` 5.1.0) from the Logos catalog. ### Boot the node The daemon is running; load the module and create the node: ```bash docker exec logos-node logosctl module load delivery_module docker exec logos-node logosctl call delivery_module createNode @/conf/logos-test.json ``` `logos.test` runs RLN, so the node needs a membership before it can start — [fund it](#fund-the-nodes-rln-membership), then: ```bash docker exec logos-node logosctl call delivery_module start ``` Verify: ```bash docker exec logos-node logosctl daemon status ``` The daemon logs to the container's output: `docker logs logos-node`. ### Stop ```bash docker compose down ``` Node data lives in the `logos-persistence` volume, so it survives `down` and rebuilds. `docker compose down -v` removes it. ## Without Docker: prebuilt binaries Run a node from released binaries — nothing to build, no repository clone. You need one CLI, [`logosctl`](https://github.com/logos-co/logos-logoscore-cli) 0.3.0: the node daemon, its client, and the package manager in one binary. ### Install logosctl Download the archive for your system from the [logosctl 0.3.0 release](https://github.com/logos-co/logos-logoscore-cli/releases/tag/0.3.0) and follow its install steps to put `logosctl` on your `PATH`. ### Install the module and boot the node ```bash # Start the daemon; --detach returns once it accepts commands logosctl daemon start --detach # Fetch delivery_module and the RLN modules logos.test needs from the Logos # catalog and install them (liblogos_lez_rln_module comes in as a dependency) logosctl catalog refresh logosctl package install delivery_module --version 0.4.0 --yes logosctl package install liblogos_rln_module --version 0.12.0 --yes # logos.test node config (layered createNode shape — see Configuration below) cat > logos-test.json <<'JSON' { "preset": "logos.test", "messagingOverrides": { "logLevel": "DEBUG", "tcp-port": 30303, "discv5-udp-port": 9000, "nat": "extip:" } } JSON logosctl module load delivery_module logosctl call delivery_module createNode @logos-test.json # fund the node's RLN membership first (see below), then: logosctl call delivery_module start ``` Replace `` with the host's public IPv4 address, or drop the `nat` line for a node nobody needs to dial — see [Public address](#public-address). `logosctl` keeps everything — installed modules, logs, node data — in its session directory, `~/.logosctl` (`--config-dir` picks another). The daemon log is `~/.logosctl/logs/daemon.log`. Verify with `logosctl daemon status`; stop with `logosctl daemon stop`. ## Fund the node's RLN membership `logos.test` rate-limits with RLN on the LEZ testnet (see [`rln.md`](./rln.md)). `createNode` brings the RLN modules up on the preset's registry; they create the node's own wallet and register a membership as soon as its payer account holds enough native LEZ — the node pays for itself, nothing is registered by hand. `start` passes only once that membership is active. With Docker, prefix each command with `docker exec logos-node`. ```bash # The account to fund (state "ready", "network":"testnet") logosctl call liblogos_lez_rln_module wallet_status # → {... "payer":"" ...} ``` Send it **at least 200000000** native on the LEZ testnet: the registration price is 1000000 (rate limit 100), and the transaction's fee reserve, sized from the chain's live fees, is ~1.8e8 at base fee 8 (most of it is refunded). Bridge funds from the Logos blockchain testnet with a channel deposit, or transfer from an account that already holds LEZ testnet native. Then wait for the membership (typically 1–3 minutes after the funds land): ```bash printf '%s' '5e269b6a19fce081f5808b13442dcbc3522197638dd38df5a28bc4e55236b977' > /tmp/rln-id.arg logosctl call liblogos_rln_module get_membership_state \ logos:testnet:fd322d32a46ddf57eece9db8d68e9b722262d1f770760fca63b8cb9e7775b971 @/tmp/rln-id.arg # "state":"unknown" with provisioning.step "awaiting_funding" → not funded yet # "state":"active" → ready to start ``` The wallet (and the key to its funds) lives in the node's data — the `logos-persistence` volume with Docker, the session directory otherwise. ## Without Docker: build with Nix Build the runtime and this module with Nix, then run the `logoscore` daemon directly on the host. ### Prerequisites - [Nix](https://nixos.org/download.html) with flakes enabled - Linux or macOS ### Build the runtime and module Build the `logoscore` CLI (the headless runtime) and the `lgpm` package manager from their flakes, then build and install this module's `.lgx`. Both of its dependencies are optional. `libp2p_module` hosts external service discovery: a node configured for it (`plugin-kad-discovery`) fails to start without it, any other node runs without it. An RLN-enabled preset also needs `liblogos_rln_module` and `liblogos_lez_rln_module`. This flake re-exports their `.lgx`s from its own locked inputs, so they match the revs the module was built against: ```bash git clone https://github.com/logos-co/logos-delivery-module.git cd logos-delivery-module git checkout v0.4.0 # Runtime + package manager nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos nix build 'github:logos-co/logos-package-manager#cli' -o lgpm # This module, built from the checkout nix build '.#lgx' -o delivery-lgx # libp2p, for external service discovery nix build '.#libp2p_module-lgx' -o libp2p-lgx # Its RLN dependency chain nix build '.#liblogos_rln_module-lgx' -o rln-lgx nix build '.#liblogos_lez_rln_module-lgx' -o lez-rln-lgx # Seed the modules dir with the bundled capability module, then install mkdir -p modules cp -RL ./logos/modules/. ./modules/ for pkg in libp2p-lgx lez-rln-lgx rln-lgx delivery-lgx; do ./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file "$pkg"/*.lgx done ``` The first build compiles the whole runtime stack through Nix — allow ~30–45 min. Later builds are fast. `.#lgx` is a development package that only the Nix-built runtime above can load. To install a local build into a released `logosctl` instead, build `.#lgx-portable` and pass it to `logosctl package install`. ### Start the daemon Put `logoscore` on your `PATH` and start it in daemon mode pointed at `./modules`: ```bash export PATH="$PWD/logos/bin:$PATH" logoscore -D -m ./modules > logs.txt & ``` ### Boot the node ```bash logoscore load-module delivery_module logoscore call delivery_module createNode @conf/logos-test.json logoscore call delivery_module start ``` Verify: ```bash logoscore status ``` ### Stop ```bash logoscore stop ``` > For a fully pinned, build-from-this-commit walkthrough — plus notes on the > blocking Kademlia bootstrap in headless runs — see the > [runtime doc-test](https://github.com/logos-co/logos-delivery-module/blob/master/doctests/outputs/delivery-module-runtime.md). ## Check the node Once `start` returns, the node joins the network in the background. Within a few minutes it should report connected peers: ```bash logosctl call delivery_module getNodeInfo Metrics --json \ | jq -r .result.value | grep '^libp2p_peers ' # libp2p_peers 8.0 ``` and advertise its public address in its ENR and listen addresses: ```bash logosctl call delivery_module getNodeInfo MyMultiaddresses --json | jq -r .result.value # /ip4//tcp/30303/p2p/16Uiu2…,/ip4//udp/30303/quic-v1/p2p/16Uiu2… ``` With Docker, prefix them with `docker exec logos-node`; with the Nix build, use `logoscore call …`. See [`query-node.md`](./query-node.md) for everything else the node reports. ## Configuration The config uses the layered `createNode` shape: `preset` picks the network, `mode` defaults to `"Core"` (`"Edge"` for a light node), per-layer settings go in `messagingOverrides`. The repo ships it as [`conf/logos-test.json`](../../conf/logos-test.json): Docker mounts it 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, plus `nat`. Edit it and re-run the boot steps to change settings. Keep extra keys inside `messagingOverrides` / `channelsOverrides` / `kernelConf` — a bare top-level key (even `logLevel`) switches parsing to the legacy flat shape. Unpinned listening ports are OS-assigned; the config pins the p2p ports to match the Docker port mappings. For the dev network, use [`conf/logos-dev.json`](../../conf/logos-dev.json) (preset `logos.dev`) — see [`networks.md`](./networks.md) for how the two differ. The full config grammar, including kernel-only nodes (`"entryLayer": "kernel"`), is documented in the [API reference](api_reference.rst). The node's local state goes to the runtime's per-instance persistence directory unless `localStoragePath` names another. ### Public address The node advertises only addresses peers can actually dial. It no longer publishes `0.0.0.0` or a placeholder port: until it learns its public address, its ENR carries no IP at all and other nodes cannot connect to it. For a node others should reach, set the address explicitly: ```json "messagingOverrides": { "nat": "extip:" } ``` `nat` also takes `"any"` (the default: discover a UPnP or NAT-PMP gateway), `"upnp"`, `"pmp"` or `"none"`. Inside Docker, use `extip`. Open the p2p port (`tcp-port`, 30303) for both TCP and UDP (QUIC, below) and the UDP discovery port (`discv5-udp-port`, 9000) on the host firewall. ### QUIC QUIC is on by default and runs next to TCP. Unless `quic-port` names another port, it listens on UDP at the TCP port number — `/udp/30303/quic-v1` for the config above. [`docker-compose.yml`](../../docker-compose.yml) already publishes it. On Linux, raise the socket receive buffer limit, or the node logs `QUIC UDP receive buffer capped below requested size` at every start: ```bash sudo sysctl -w net.core.rmem_max=8388608 ``` ### RLN RLN comes from the preset — there is nothing to configure. `logos.test` runs with it on (the LEZ testnet registry), so a `logos.test` node needs the RLN modules and an active RLN membership; see [`rln.md`](./rln.md#turning-rln-on). `logos.dev` runs with it off, so a `logos.dev` node needs no RLN modules; `module load` reports `liblogos_rln_module` as skipped and carries on. [`networks.md`](./networks.md) tracks each network's RLN state. On a preset with RLN on, install the RLN modules next to this one before `createNode`, or bring-up ends in `Failed`: - Prebuilt binaries — they are in a separate catalog: ```bash logosctl catalog add https://github.com/logos-co/logos-rln-modules/releases/download/index/logos-repo.json logosctl catalog refresh logosctl package install liblogos_rln_module --yes ``` - Nix — the build above already installs them. - Docker — set the `RLN_VERSION` build arg of the [logos-docker](https://github.com/logos-co/logos-docker) image in [`docker-compose.yml`](../../docker-compose.yml), with `MODULES_REPO` pointing at a catalog that carries the RLN modules. Follow bring-up with `rlnState`: `Disabled` → `Initializing` → `Ready` | `Failed`. See [`rln.md`](./rln.md) for the details. ### Plugin-hosted discovery Enable it with `"pluginKadDiscovery": true` in `messagingOverrides` (or in `kernelConf` for a kernel-only node); leave it out to keep the node's internal discovery. On top of [`conf/logos-dev.json`](../../conf/logos-dev.json) the switch is all it takes: ```json { "preset": "logos.dev", "messagingOverrides": { "pluginKadDiscovery": true } } ``` Extra DHT bootstrap peers go through the node's own `kad-bootstrap-node` key. It needs `libp2p_module` installed next to this module (see the Nix build above). Without it `start` fails and the node is stopped. On Windows, where `libp2p_module` has no build, use internal discovery. `LIBP2P_MODULE_CONFIG` (inline JSON or a file path) is optional. Set it only to override libp2p's own defaults, for example its listen addresses when other nodes must reach it: unset, it listens on an ephemeral loopback port. How it works is described in [Architecture](./architecture.md#plugin-hosted-discovery). ## 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).