Run a Logos storage node

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

Version

This document is accurate for Testnet v0.2.1.

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.

Prerequisites

A supported OS:
- Linux
- Mac OS (should work, but not tested)
jq on your PATH.
- To verify, run: jq --version

The Logos tool suite:

logoscore (the Logos runtime);
lgpd (the Logos package downloader);
lgpm (the Logos package manager).

You can obtain them by running:

# Export those first or the script will fetch the latest version, which might not
# work with this tutorial
export LGPM_TAG=0.2.1
export LGPD_TAG=0.2.1
export LOGOSCORE_TAG=0.2.2

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

What to expect

In this tutorial, you will:

Connect a Logos Storage node to the testnet.
Publish a file to the network.
Download an existing file - the Logos book, Farewell to Westphalia - from the Logos storage network.

Download and install the storage module

Download the storage module:

mkdir -p storage-lgx
lgpd download storage_module --version 2.1.2 -o storage-lgx

This should download an lgx file in the storage-lgx folder.

Install the package using lgpm.

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

Confirm the module landed:

lgpm --modules-dir ./modules list
Found 1 installed module(s):

NAME                           VERSION         TYPE       CATEGORY
----------------------------------------------------------------------
storage_module                 (v)           core       protocol

Start the daemon and load the storage module

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

Several module calls in this procedure are asynchronous: the call returns "result":true as soon as the command is accepted, and the real outcome is delivered later as an event (storageStart, storageUploadDone, storageDownloadDone, storageRemoveDone, storageDownloadManifestDone). These events are emitted to event subscribers (such as the Storage UI); the logoscore call client does not subscribe to them, so they do not appear in logs.txt. Each step below instead waits briefly and confirms the outcome with a follow-up query (for example manifests or exists).

Start the logoscore daemon in background mode, capturing its output:
```
logoscore -D -m ./modules > logs.txt 2>&1 &
```
- The client subcommands below connect to this running process via the config written under ~/.logoscore/.

Verify the daemon is running:

logoscore status

# Logoscore Daemon
#   Status:       running
#   PID:          148188
#   Uptime:       0s
#   Version:      v1.0.0
#
# Modules: 1 loaded, 0 crashed, 1 not loaded
#   storage_modulev         not_loaded  -
#   capability_modulev         loaded      -

Load the storage module and confirm it reports loaded:

logoscore load-module storage_module
# Loaded module: storage_module (v)
logoscore status
# Logoscore Daemon
#   Status:       running
#   PID:          148188
#   Uptime:       0s
#   Version:      v1.0.0

# Modules: 2 loaded, 0 crashed, 0 not loaded
#   storage_modulev         loaded      -
#   capability_modulev         loaded      -

To see every method the module exposes (the same methods you can call), run logoscore module-info storage_module.

Create a minimal storage config. Use absolute paths: in daemon mode the module runs as its own process, whose working directory is not the one you are typing in, so relative paths resolve to the wrong place. The $(pwd) in the heredoc takes care of it:
```
mkdir -p "$(pwd)/storage-data"
cat > config.json <<EOF
{
    "data-dir": "$(pwd)/storage-data",
    "log-file": "$(pwd)/storage-data/storage.log"
}
EOF
```
- config.json includes the following fields:
Field Purpose
data-dir Storage repository path (absolute)
log-file Node log destination (absolute)
- The default settings for Logos storage should be enough to get your node properly connected onto the Logos testnet. In case you want more control over port allocation, or want to learn more about how Logos storage operates, see Connectivity.
tip
If you plan on running a node for longer, consider helping the network by setting up port mapping on your router (see Connectivity for details).
Initialise the storage module. init is synchronous and returns true on success (the @config.json syntax loads the file's contents as the argument):
```
logoscore call storage_module init @config.json
```
Start the node. start is asynchronous: the return value only confirms the command was accepted; completion is signalled later by the storageStart event (delivered to event subscribers, not written to logs.txt):
```
logoscore call storage_module start
# Wait few seconds to start
```

Field	Purpose
`data-dir`	Storage repository path (absolute)
`log-file`	Node log destination (absolute)

Inspect the running node with debug. It returns a lot of information about the node, including its id (peer ID) and its spr, the signed record other nodes use to connect to you (see Connectivity):

logoscore call storage_module debug | jq .result.value.id
# "16Uiu2HAmMA4NuQoCHz9p7jUskVjDd8WncwG3p6qBNnhnftUE5Q9C" # Your peer ID
logoscore call storage_module debug | jq .result.value.spr
# "spr:CiUIAhIhA35P5KZosVyfWTfIHBVtC_PtI ... H9gX-vA" # Your SPR

Publish a file

We will now publish a file to the Logos storage network. We create a simple file just for this tutorial, but you could publish any file you'd like.

Create a file to publish:

echo "Hello world from Logos Storage" > "$(pwd)/hello.txt"

Upload the file to the network with uploadUrl. It takes an absolute path and a chunk size in bytes, and returns immediately; the upload runs in the background and completes with a storageUploadDone event:
```
logoscore call storage_module uploadUrl "$(pwd)/hello.txt" 65536
```
info
The default chunk size is 65536.

Extract the content ID (CID) from the first manifests entry:

# Wait a second for the upload to complete first
logoscore call storage_module manifests \
   | jq -er '.result.value[0].cid' > cid.txt

Download Farewell to Westphalia

We will now download the Logos book, Farewell to Westphalia, from the Logos storage network.

We will use downloadToUrl to download the file from the network and place it into your local disk. It takes the CID, an absolute destination path, a local flag, and a chunk size in bytes. We set local to false as this file is not currently available in your node. Like uploadUrl it runs in the background and completes with a storageDownloadDone event:
```
CID="zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ"
logoscore call storage_module downloadToUrl "$CID" "$(pwd)/farewell-to-westphalia.pdf" false 65536
```
tip
The local flag reads only from locally cached data when set to true; false fetches from the network.
Wait for a while for the file to download. After a few seconds, check if the downloaded file is present at the destination path. You should try to open the pdf, and it should contain the whole book.
```
shasum "$(pwd)/farewell-to-westphalia.pdf"
# 2c6b4dc8e8e4dae336b87b9922c38f3c94217872  farewell-to-westphalia.pdf
```

Remove content and shut everything down

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

Remove content from local storage by its CID. remove returns immediately; the outcome arrives as a storageRemoveDone event:

# Deletes the first file we uploaded.
logoscore call storage_module remove "$(cat cid.txt)"
# Deletes the Farewell to Westphalia book.
logoscore call storage_module remove "zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ"

Confirm the content is gone:

# Wait a second for the removal to complete first
logoscore call storage_module exists "$(cat cid.txt)" | jq '.result.value'
logoscore call storage_module exists "zDvZRwzkzrrYB6sS1rRpRLt4gBhc1pWoyTSjkfszfmj1seaYYLCZ" | jq '.result.value'
# false

Stop the storage node. stop is asynchronous like start; completion is signalled by a storageStop event (delivered to event subscribers, not written to logs.txt). The node can be started and stopped multiple times:
```
logoscore call storage_module stop
# Wait a few seconds for the node to stop before destroying it
```
Destroy the storage context. destroy is synchronous and must be called after the node is stopped:
```
logoscore call storage_module destroy
```

Stop the daemon and confirm it has exited:

logoscore stop
# Wait 5 seconds
logoscore status
# Logoscore Daemon
#   Status:       not_running

Troubleshooting Logos Storage

Connectivity problems (downloads timing out from another machine, no peers, unreachable node) are covered in the Troubleshooting and Connectivity pages.

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

What to expect​

Download and install the storage module​

Start the daemon and load the storage module​

Publish a file​

Download Farewell to Westphalia​

Remove content and shut everything down​

Troubleshooting Logos Storage​