Run a Logos storage node

Get started running a Logos storage node and uploading your first file to the Logos network.

This procedure covers how to build and run the Logos Storage Module, connect it to the testnet bootstrap nodes, publish a file, and verify that the file can be downloaded. It is intended for node operators on testnet v0.2 who want to contribute storage capacity to the Logos network.

Before you start, make sure you have the following:

• Linux (tested on Ubuntu 22.04)

• 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

• logoscore, and lgpm installed. To install these tools, use the install-node-tools.sh helper script:

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

• jq on your PATH — used to pull the uploaded CID out of the manifests JSON. Verify: jq --version

What to expect

• You can connect a Logos Storage node to the testnet and have it listed among the bootstrap peers.
• You can publish a file to the network and retrieve a content address to share with other nodes.
• You can download the file back from the network and confirm it lands on disk.

Build and install the storage module

1. Build the module package with Nix:

   nix build 'github:logos-co/logos-storage-module/v2.0.1#lgx' -o storage-lgx

   • This produces a logos-storage_module-module-lib.lgx package in ./storage-lgx/.
   info

   The initial Nix build takes 15–20 minutes on first run. Subsequent builds use the Nix cache and complete in seconds.

2. Install the package into a local modules directory using lgpm:

   lgpm --modules-dir ./modules install --file storage-lgx/*.lgx

Start the daemon and load the storage module

Run logoscore with the modules directory, then load and initialise the storage module against the testnet config.

1. Start the logoscore daemon in background mode:

   logoscore -D -m ./modules

2. Verify the daemon is running:

   logoscore status

3. Create the storage config:

   mkdir -p storage-data
   cat > config.json <<EOF
   {
     "data-dir": "./storage-data",
     "log-level": "INFO",
     "listen-ip": "0.0.0.0",
     "listen-port": 8091,
     "disc-port": 8090,
     "nat": "extip:<public-ip>",
     "network": "logos.test"
   }
   EOF

   • config.json includes the following fields:

   Field	Purpose
   data-dir	Storage repository path
   log-level	Log verbosity
   listen-ip	Local TCP bind address
   listen-port	Public TCP libp2p port
   disc-port	Public UDP discovery port
   nat	Public IP advertisement mode
   network	Storage network preset

   • Use fixed listen-port and disc-port; do not leave public nodes on random ports.
   • The logos.test preset provides the storage bootstrap settings.
   • Fields
   info

   To run storage with mix support, generate the config from the published mix bootstrap data:

   cat > make-mix-storage-config.sh <<'EOF'
   #!/usr/bin/env bash
   set -e
   
   data_dir=${1:-"./logos-storage-data"}
   udp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/udp-sprs.json)
   tcp_spr_json=$(curl -s https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/tcp-sprs.json)
   
   wget https://logos-storage-network.fra1.digitaloceanspaces.com/v0.2/mix-pool.json
   mp_path=$(realpath "./mix-pool.json")
   
   cat <<JSON
   {
     "nat": "any",
     "log-level": "DEBUG",
     "mix-enabled": true,
     "listen-port": 8080,
     "disc-port": 8090,
     "bootstrap-node": $udp_spr_json,
     "dht-mix-proxy": $tcp_spr_json,
     "data-dir": "${data_dir}",
     "mix-pool": "${mp_path}"
   }
   JSON
   EOF
   
   chmod 755 make-mix-storage-config.sh
   ./make-mix-storage-config.sh > config.json

4. Load the storage module, initialise it with the testnet configuration, and start it:

   logoscore load-module storage_module
   logoscore call storage_module init @config.json
   logoscore call storage_module start

   • If using the mix config, also enable private queries and verify with a test download:

     logoscore call storage_module togglePrivateQueries true
     logoscore call storage_module downloadToUrl zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ ./farewell-to-westphalia.pdf false 65536

Publish and download a file

Once the node is running and connected to the testnet, publish a file and verify the round-trip.

1. Upload a file to the network with uploadUrl:

   logoscore call storage_module uploadUrl <file-path-or-url> <chunk-size-in-bytes>

   info

   The default chunk size is 65536.

2. After a second, extract the content ID (CID) from the first manifests entry:

   sleep 1
   
   logoscore call storage_module manifests \
      | jq -er '.result.value[0].cid' > cid.txt

3. Download the file back from the network with downloadToUrl. You need the CID for this step.

   logoscore call storage_module downloadToUrl "$(cat cid.txt)" <destination-path> false <chunk-size-in-bytes>

   • downloadToUrl takes a local flag which reads only from locally cached data if set to true.

4. Confirm the downloaded file is present at <output-path> and matches the original.

Remove content and destroy the storage node

To clear your local storage and destroy the storage node, follow the steps below.

1. Remove content from local storage by its CID:

   logoscore call storage_module remove "$(cat cid.txt)"

2. Confirm content is gone:

   sleep 1
   
   logoscore call storage_module exists "$(cat cid.txt)"
   # should return false

3. Stop the storage node:

   logoscore call storage_module stop

4. Wait a bit and destroy the entire storage context:

   sleep 2
   
   logoscore call storage_module destroy

Troubleshooting Logos Storage

Why does downloadToUrl time out when downloading from a different machine?

NAT is blocking the peer connection. When running multiple nodes across machines, the external IP and port mapping must be configured in config.json. See the NAT section of the Logos Storage Module documentation for guidance.