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.2.1.

This procedure covers how to install and start a logos-delivery-module node connected to the Logos testnet (v0.2). 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; first build takes 30–45 min
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.
  • 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
    info

    The first Docker build runs Nix and downloads release packages. It can take 30–45 minutes; subsequent starts are fast.

Path B—Prebuilt binaries

  1. Install logoscore, lgpd, and lgpm into ./bin:

    curl -fsSL https://raw.githubusercontent.com/logos-co/logos-docs/main/resources/scripts/install-node-tools.sh | sh
    export PATH="$PWD/bin:$PATH"

  2. Download and install the delivery module. The root hash selects the exact published package identity for the pinned version:

    mkdir -p packages modules
    lgpd download delivery_module --version 0.2.0 --root-hash eb47c06575a6113f34a6d71e5e0b72d6d2db2ec7510b8be0ab9633b8385edd57 --output ./packages
    lgpm install --dir ./packages --modules-dir ./modules

  3. Write the testnet config and start the daemon:

    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

    logoscore -D -m ./modules > logs.txt

Path C—Nix

  1. Clone the repository and build the runtime, package manager, and module:

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

    nix build 'github:logos-co/logos-logoscore-cli' --out-link ./logos
    nix build 'github:logos-co/logos-package-manager#cli' -o lgpm
    nix build '.#lgx' -o delivery-lgx

  2. Seed the modules directory and install the module:

    mkdir -p modules
    cp -RL ./logos/modules/. ./modules/
    ./lgpm/bin/lgpm --modules-dir ./modules --allow-unsigned install --file delivery-lgx/*.lgx

  3. Start the daemon:

    export PATH="$PWD/logos/bin:$PATH"
    logoscore -D -m ./modules > logs.txt

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 logoscore load-module delivery_module --json

    # Paths B and C
    logoscore load-module delivery_module

  2. Create the node with the testnet config:

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

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

    • Path B:

      logoscore call delivery_module createNode @logos-test.json

    • Path C:

      logoscore call delivery_module createNode @conf/logos-test.json

  3. Start the node:

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

    # Paths B and C
    logoscore 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 logoscore status --json

    # Paths B and C
    logoscore status

  2. Run the health query:

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

    # Paths B and C
    logoscore 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: logoscore stop

Troubleshooting delivery node setup​

Why does the first docker compose up appear stuck?​

The first build runs Nix and downloads release packages, which takes 30–45 minutes on a typical connection. The process is not hung—let it finish. Subsequent starts use the cached layers and complete in seconds.

Why does logoscore call return an error after load-module?​

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