Skip to main content

Run a Logos delivery node

Use the Logos Delivery module to run a Logos delivery node​

Version

This document is accurate for Testnet v0.3.

This procedure covers how to install and start a logos-delivery-module node connected to the Logos testnet (v0.3). It is intended for node operators who want to run their own Delivery node and join the network. Three installation paths are available—Docker, prebuilt binaries, and Nix—so you can choose the one that fits your environment.

Choose one of the three installation paths based on your environment:

PathMethodBest for
ADocker with ComposeQuickest start
BPrebuilt binariesNo build, no clone required
CNixFrom source; most reproducible
Prerequisites
  • A supported OS:
    • Linux
    • macOS
  • Network access so both node instances can reach each other.
  • Inbound ports open:
    • TCP 30303: P2P (tcpPort).
    • UDP 30303: P2P over QUIC, on by default at the tcpPort number.
    • UDP 9000: discv5 discovery (discv5UdpPort).
  • logosctl installed.
    • Install it by running curl -fsSL https://raw.githubusercontent.com/logos-co/logos-docs/main/resources/scripts/install-logosctl.sh | sudo sh
  • Some prerequisites differ between paths:

    • Path A: Docker with Compose

    • Path B: curl and a shell

    • Path C: Nix with flakes enabled.

      • Install from nixos.org, then enable flakes:
      mkdir -p ~/.config/nix
      echo 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf

What to expect​

  • You can start a delivery_module node connected to the Logos Network.
  • You can confirm the node is running and has a live network identity by querying its discv5 ENR.
  • You can configure the node for a different network preset by swapping the config file passed to createNode.

Step 1: Install and start the daemon​

Follow the instructions for your chosen path.

Path A—Docker

  1. Clone the repository and start the daemon container:

    git clone https://github.com/logos-co/logos-delivery-module.git
    cd logos-delivery-module
    docker compose up -d --build

Path B—Prebuilt binaries

  1. Start logosctl:

    logosctl daemon start

  2. In a new terminal window with the same user, refresh the official module catalogue:

    logosctl catalog refresh

  3. Download and install the delivery module:

    logosctl package install delivery_module \
    --version 0.3.0 \
    --yes
    note

    Individual module package versions (for example, delivery module version 0.3.0) are pinned independently and do not necessarily match the testnet version number (0.3.0).

  4. Write the testnet config:

    cat > logos-test.json <<EOF
    {
       "entryLayer": "kernel",
       "kernelConf": {
          "preset": "logos.test",
          "relay": true,
          "logLevel": "INFO",
          "tcpPort": 30303,
          "discv5UdpPort": 9000,
          "discv5Discovery": true,
          "nat": "extip:<public-ip>"
       }
    }
    EOF
    • logos-test.json includes the following fields:
    FieldPurpose
    entryLayerDelivery stack layer; use kernel for a node-operator service
    kernelConfKernel node configuration
    kernelConf.presetNetwork preset
    kernelConf.relayEnable the Relay protocol
    kernelConf.logLevelLog verbosity
    kernelConf.tcpPortPublic TCP P2P port
    kernelConf.discv5UdpPortPublic UDP discovery port
    kernelConf.discv5DiscoveryEnable discv5 discovery
    kernelConf.natPublic IP advertisement mode

Path C—Nix

  1. Clone the repository and build the module:

    git clone https://github.com/logos-co/logos-delivery-module.git
    cd logos-delivery-module
    git checkout v0.3.0

    nix build '.#lgx-portable' -o delivery-lgx
    • v0.3.0 is the release Path B installs, so both paths run the same module.
    • Build lgx-portable, not lgx: the lgx output is a development build (variant linux-amd64-dev) that logosctl package install rejects with Package does not contain variant for platform: linux-x86_64.

  2. Start logosctl:

    logosctl daemon start

  3. In a new terminal window with the same user, install the module:

    logosctl package install delivery-lgx/*.lgx --yes

  4. Write the testnet config:

    cat > logos-test.json <<EOF
    {
       "entryLayer": "kernel",
       "kernelConf": {
          "preset": "logos.test",
          "relay": true,
          "logLevel": "INFO",
          "tcpPort": 30303,
          "discv5UdpPort": 9000,
          "discv5Discovery": true,
          "nat": "extip:<public-ip>"
       }
    }
    EOF

Step 2: Load the module and boot the node​

Run these commands for your path.

  1. Load the delivery module:

    # Path A (Docker)
    docker exec logos-node logosctl module load delivery_module --json

    # Paths B and C
    logosctl module load delivery_module

  2. Create the node with the testnet config:

    • Path A (config is mounted at /conf in the container):

      docker exec logos-node logosctl call delivery_module createNode @/conf/logos-test.json --json

    • Path B:

      logosctl call delivery_module createNode @logos-test.json

    • Path C:

      logosctl call delivery_module createNode @logos-test.json

  3. Start the node:

    # Path A
    docker exec logos-node logosctl call delivery_module start --json

    # Paths B and C
    logosctl call delivery_module start

Step 3: Verify the node is running​

Query the node's discv5 ENR to confirm it booted with a network identity and joined the Logos Testnet.

  1. Verify the status of the node:

    # Path A
    docker exec logos-node logosctl daemon status --json

    # Paths B and C
    logosctl daemon status

  2. Run the health query:

    # Path A
    docker exec logos-node logosctl call delivery_module getNodeInfo MyENR --json | jq

    # Paths B and C
    logosctl call delivery_module getNodeInfo MyENR --json | jq

    Expected output:

    {
      "method": "getNodeInfo",
      "module": "delivery_module",
      "result": {
        "error": null,
        "success": true,
        "value": "enr:-LW4QItc5tHj3rWoFaaQIUWvaBYijDf2TJKW83SNdyylJVAYVoUlBl1h5..."
      },
      "status": "ok"
    }
    • The "value" field is your node's live ENR and will differ from the example above.
    • "success": true and "status": "ok" confirm the delivery node is running.

  3. Stop the node when finished:

    • Path A: docker compose down
    • Paths B and C: logosctl daemon stop

Troubleshooting delivery node setup​

Why does logosctl call return an error after module load?​

The daemon may not have finished starting. Wait a few seconds after logosctl daemon start returns and retry. For Path A, confirm the container is running with docker ps before calling docker exec logos-node logosctl ….