Set Up a Storage Node

Prerequisites

System Requirements

Linux is the preferred operating system.

Windows
Linux
macOS

Windows 10 64bit: Pro, Enterprise or Education (Build 15063 or later)

Windows Server (2016 or later)

If you are using Windows with Docker, your node may require extra monitoring.

You may have to frequently restart Docker from the Docker desktop application when your Last Contact shown in the dashboard gets larger than a few seconds.

CentOS - A maintained version of CentOS 7

Debian - 64-bit version of one of these Debian or Raspbian versions:

  • Buster 10

  • Stretch 9 (stable) / Raspbian Stretch

Fedora - 64-bit version of one of these Fedora versions:

  • 28

  • 29

Ubuntu - 64-bit version of one of these Ubuntu versions:

  • Cosmic 18.10

  • Bionic 18.04 (LTS)

  • Xenial 16.04 (LTS)

It is important to make sure you use static mount for your hard drive via /etc/fstab

macOS Sierra 10.12 and newer macOS releases are supported

Mac hardware must be a 2010 or newer model

VirtualBox prior to version 4.3.30 must NOT be installed (it is incompatible with Docker Desktop for Mac). If you have a newer version of VirtualBox installed, it’s fine.

If you are using macOS with Docker, your node may require extra monitoring.

You may have to frequently restart Docker from the Docker desktop application when your Last Contact shown in the dashboard gets larger than a few seconds.

If your OS is not supported, save your one-time-use authorization token, as it does not expire. We will notify you as updates are made.

Install Docker

To setup a Storage Node, you first must have Docker installed. Install Docker by following the appropriate installation guide for your OS.

Set Up Port Forwarding

Set up Port Forwarding & Dynamic DNS. The port you should specify is 28967. Please read our guide:

You may also visit portforward.com and follow the instructions for your router.

Internet Connection

It is highly recommended to have your Storage Node connected via LAN instead of WiFi to ensure a consistent and stable connection.

Important Security Consideration

Do not connect your computer directly to the internet without the assistance of a firewall.

Our software serves requests from the internet, but not all software you may have installed is designed to be exposed to the internet directly! This is especially true for users on Windows with applications responding to requests on all IPs.

Power Supply

If you live in a location where power outages or brownouts are a frequent occurrence, please consider protecting your hardware, including the equipment you run your node on, as well as your router/modem, with an Uninterrupted Power Supply (UPS). This would help protect against damage to your hardware as well as against corruption of your database resulting from abrupt shutdowns which could lead to unrecoverable loss of your node.

Using a Remote Connection?

If you must use a remote connection, due to the length of time it takes for some of the steps, it is highly recommended to run them inside a virtual console like TMUX or SCREEN.

It is recommended to perform the next steps local to the machine, and not via a remote connection.

Using a NAS?

If you get a permission error for docker commands on your NAS, please follow the docker post install instructions or start commands with sudo.

Setup

Prefer a video tutorial?

Download the Identity Binary

Download the binary for your OS and unzip it.

Create an Identity

This can take several hours or even days, depending on your machines processing power & luck.

If you are planning to run your node on a NAS, Raspberry Pi or other device with less computing power, you can create an Identity on a more powerful machine and then transfer it over to the device you will run your node on.

To create an identity:

1. Open a terminal window.

2. Go to the directory with your identity binary.

3. Use the create command to create an identity:

Windows
Linux
ARM-based OS
macOS
./identity_windows_amd64.exe create storagenode

Your identity will be generated in: $Env:APPDATA/Storj/Identity/storagenode

./identity_linux_amd64 create storagenode

If you are unable to execute the command, be sure that you set your file permission to executable: chmod +x identity_linux_amd64

Your identity will be generated in: ~/.local/share/storj/identity/storagenode

./identity_linux_arm create storagenode

If you are unable to execute the command, be sure that you set your file permission to executable: chmod +x identity_linux_arm

On Raspberry Pi, your identity will be generated in (the path may be different for other ARM platforms): /home/pi/.local/share/storj/identity/storagenode

./identity_darwin_amd64 create storagenode

If you are unable to execute the command, be sure that you set your file permission to executable.

Your identity will be generated in: /Users/USER/Library/Application Support/Storj/identity/storagenode

4. This process will continue until it reaches a difficulty of 30. On completion, it will look something like this:

Sign the Identity

Now, sign the identity you created with your single-use authorization token.

Reminder: The entire string including your email is your authorization token.

Windows
Linux
ARM-based OS
macOS
./identity_windows_amd64.exe authorize storagenode <email:characterstring>
./identity_linux_amd64 authorize storagenode <email:characterstring>
./identity_linux_arm authorize storagenode <email:characterstring>
./identity_darwin_amd64 authorize storagenode <email:characterstring>

If your identity folder only contains 4 files after this step, you did not successfully complete the identity authorization. Repeat signing your identity as described until you see 6 files in you identity folder.

Backup the Identity folder

Failure to create a complete backup of all 6 files in your identity folder after you signed your identity can result in not being able to recover your node later. Save it now!

Make a backup of your identity folder, including all 6 files contained in it. This will allow you to restore your node to working order in case of an unfortunate incident such as a hard drive crash. Find your identity folder here:

Windows
Linux
ARM-based OS
macOS

Your identity folder is located in: $Env:APPDATA/Storj/Identity/storagenode

Your identity folder is located in: ~/.local/share/storj/identity/storagenode

On Raspberry Pi, your identity folder is located in (the path may be different for other ARM platforms): /home/pi/.local/share/storj/identity/storagenode

Your identity folder is located in: /Users/USER/Library/Application Support/Storj/identity/storagenode

Download the Storage Node Docker Container

Pull the Storage Node Docker Container.

Non-ARM based platforms
ARM-based platforms
docker pull storjlabs/storagenode:alpha
docker pull storjlabs/storagenode:arm

Storage Node Concepts

Before running your Storage Node for the first time, please note the definitions of the parameters to be used.

Parameter

Description

WALLET

your address to receive STORJ token payouts for running the node. Learn how to obtain a valid payout address.

EMAIL

email address so that we can notify you when a new version has been released (optional)

ADDRESS

external IP address or the DDNS you configured and the port you opened on your router <ip>:<port>

If you are using a custom port other than 28967, you have to change the -p 28967:28967 to -p <port>:28967

BANDWIDTH

how much bandwidth you can allocate to the Storj network. Be sure to allow for other use cases you have for your internet connection, and do not allocate more than your ISP supplied up and download speed can physically supply. To calculate the maximum monthly BANDWIDTH you can enter here, follow instructions here. The minimum bandwidth requirement is 2TB.

STORAGE

how much disk space you want to allocate to the Storj network

Be sure not to over-allocate space! Allow at least 10% extra for overhead. If you over-allocate space, you may corrupt your database when the system attempts to store pieces when no more physical space is actually available on your drive. The minimum storage shared requirement is 500 GB, which means you need a disk of at least 550 GB total size to allow for the 10% overhead.

<identity-dir>

replace to the location of your identity files. You can copy the absolute path from the output of the identity commands you ran earlier.

<storage-dir>

replace to the local directory where you want files to be stored on your hard drive for the network.

Note: the current database backend is BoltDB, which requires mmap, hence you have to use a file system which supports mmap.

Special Node Configuration to Limit Concurrent Uploads

Slower nodes like Raspberry Pi3 for example, may have difficulties getting any data. In previous releases (up to 0.14.3) they were accepting too many concurrent uploads but were unable to finish them in time. In the new releases after 0.14.3, we now have a new configuration option available to fine-tune the number of concurrent uploads. If your node was already previously running, first docker stop -t 300 storagenode and then please edit your config.yaml file (on Windows, use Nodepad++, not Notepad, on MacOS, use TextEdit, not Notes) to add the following line at the end of the file:

storage2.max-concurrent-requests: 7

Save the config.yaml file and then restart your node by docker restart -t 300 storagenode, if it was already running before. If this is the first time you will start your node, please follow the instructions in the following sections to use the proper parameters with your docker run storagenode command.

This will allow slow nodes to focus on a smaller number of uploads and finish them as fast as possible, while refusing the uploads it couldn't process anyway. You can adjust the number of requests - 7 is just an initial suggestion, but you can modify this number up or down and monitor the performance of your node until you find the right number of requests for your particular node which does not cause your node to be overwhelmed. Faster nodes will be able to function with a higher number of concurrent requests than slow nodes.

Running the Storage Node

If you were already previously running a node, please be sure to verify that for defining your identity and storage folder locations, you are using the --mount instead of the -v option mentioned in earlier versions of the setup instructions. If Docker for any reason fails to map the disk, when using the -v option, it will create an empty disk inside the container. If you then later remove the container, it will be removed along with the data inside it, and data will be unrecoverable. To avoid this, edit your docker run command to include the --mount options instead.

1. Copy the command format appropriate for your OS into a text editor:

Windows
Non-ARM based platforms
ARM-based platforms
docker run -d --restart unless-stopped -p 28967:28967 -e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -e EMAIL="user@example.com" -e ADDRESS="domain.ddns.net:28967" -e BANDWIDTH="20TB" -e STORAGE="2TB" --mount type=bind,source="<identity-dir>",destination=/app/identity --mount type=bind,source="<storage-dir>",destination=/app/config --name storagenode storjlabs/storagenode:alpha

On Windows, you need to format the paths using double backslashes: D:\\identity\\storagenode\\ or D:\\data\\

docker run -d --restart unless-stopped -p 28967:28967 \
-e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-e EMAIL="user@example.com" \
-e ADDRESS="domain.ddns.net:28967" \
-e BANDWIDTH="20TB" \
-e STORAGE="2TB" \
--mount type=bind,source="<identity-dir>",destination=/app/identity \
--mount type=bind,source="<storage-dir>",destination=/app/config \
--name storagenode storjlabs/storagenode:alpha
docker run -d --restart unless-stopped -p 28967:28967 \
-e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-e EMAIL="user@example.com" \
-e ADDRESS="domain.ddns.net:28967" \
-e BANDWIDTH="20TB" \
-e STORAGE="2TB" \
--mount type=bind,source="<identity-dir>",destination=/app/identity \
--mount type=bind,source="<storage-dir>",destination=/app/config \
--name storagenode storjlabs/storagenode:arm

2. Edit the WALLET, EMAIL, ADDRESS, BANDWIDTH, STORAGE, <identity-dir>, and <storage-dir> with your parameters.

3. Copy the updated command.

4. Run it in a terminal window.

Running the Storage Node Dashboard

In order to monitor the functioning of your node, you can start the dashboard:

docker exec -it storagenode /app/dashboard.sh

Depending on how much data you already have stored on your node, the dashboard may not load instantly.

Give it some time to fully load. Also, it is not necessary to keep the dashboard constantly running. You can exit the dashboard with Ctrl-C and the Storage Node will continue running in the background.

What the dashboard will look like

Check your Logs

You can look at your logs to see if you have some errors indicating that something is not functioning properly:

docker logs storagenode

Log too long?

Use this command if you just want to see the last 20 lines of the log:

docker logs --tail 20 storagenode

Redirecting logs to a file

1. To redirect the logs to a file, stop your node:

docker stop -t 300 storagenode

2. Then edit your config.yaml (you can use nano or vi editor) to add:

log.output: "/app/config/node.log"

3. Start your node again:

docker start storagenode

When you use this option, docker logs commands no longer show your node log. Use the file instead.

Support

If you need help setting up your storage node, visit our Community Forum to receive interactive assistance. Be sure to provide your logs and stack trace when requested by the community leader attending your issue.

You can also file a support ticket.

Short Maintenance Shutdown

If you need to shutdown the Storage Node for maintenance on your system, run:

docker stop -t 300 storagenode

After you finished your maintenance, restart the node with:

docker start storagenode

Updating Your Storage Node

Automatic Updates

You can set up automatic updates for your storagenode Docker container using watchtower.Watchtower will look for new updates to the Docker container on Docker Hub and automatically update your storage node when it sees a new version.

To set up auto-update for storagenode, please run the following only once:

Non-ARM based platforms and Raspberry Pi
ARM-based platforms
docker run -d --restart=always --name watchtower -v /var/run/docker.sock:/var/run/docker.sock storjlabs/watchtower storagenode watchtower --stop-timeout 300s

For ARM-based platforms like Odroid N2:

docker pull storjlabs/watchtower:latest-arm32v6
docker run -d --restart=always --name watchtower -v /var/run/docker.sock:/var/run/docker.sock storjlabs/watchtower:latest-arm32v6 storagenode watchtower --stop-timeout 300s

This command sets up watchtower to only monitor the Storage Node container. If you want to use watchtower for other containers as well, please refer to the watchtower documentation.

Manual Updates

1. Stop the running Storage Node container:

docker stop -t 300 storagenode

2. Remove the existing container:

docker rm storagenode

3. Pull the latest image from docker:

Non-ARM based platforms
ARM-based platforms
docker pull storjlabs/storagenode:alpha
docker pull storjlabs/storagenode:arm

4. Start your storage node again by running the following command after editing WALLET, EMAIL, ADDRESS, BANDWIDTH, STORAGE, <identity-dir>, and <storage-dir>:

Windows
Non-ARM based platforms
ARM-based platforms
docker run -d --restart unless-stopped -p 28967:28967 -e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" -e EMAIL="user@example.com" -e ADDRESS="domain.ddns.net:28967" -e BANDWIDTH="20TB" -e STORAGE="2TB" --mount type=bind,source="<identity-dir>",destination=/app/identity --mount type=bind,source="<storage-dir>",destination=/app/config --name storagenode storjlabs/storagenode:alpha
docker run -d --restart unless-stopped -p 28967:28967 \
-e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-e EMAIL="user@example.com" \
-e ADDRESS="domain.ddns.net:28967" \
-e BANDWIDTH="20TB" \
-e STORAGE="2TB" \
--mount type=bind,source="<identity-dir>",destination=/app/identity \
--mount type=bind,source="<storage-dir>",destination=/app/config \
--name storagenode storjlabs/storagenode:alpha
docker run -d --restart unless-stopped -p 28967:28967 \
-e WALLET="0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-e EMAIL="user@example.com" \
-e ADDRESS="domain.ddns.net:28967" \
-e BANDWIDTH="20TB" \
-e STORAGE="2TB" \
--mount type=bind,source="<identity-dir>",destination=/app/identity \
--mount type=bind,source="<storage-dir>",destination=/app/config \
--name storagenode storjlabs/storagenode:arm

If you want to change any of your parameters, such as payout address, allotted storage space, bandwidth, etc., just stop and remove the container, and then run the container again after editing the parameter that has changed. You will not need to execute thedocker pull command in this case.

Migrating your Node to a new Drive or Computer

If you want to migrate your node to a new drive or computer, you need to migrate both the contents of your storage folder and your identity folder to the new location and change the corresponding paths for both storage and identity folders --mount parameters in your docker run storagenode command.

Estimating your Payouts per Satellite

If you would like to estimate how much you can expect to get paid for running your node during a given month, please follow the instructions in these instructions. Please note that this script will not give you exact values, your actual payout may be slightly different from what you calculated for each satellite. Also note that the script will estimate what will be the payout you will receive depending on how long you already have been running the node on a satellite, taking into account the amount withheld in the initial months which is not immediately paid out to the node operator. Please see more details about held amounts in this blog post.

Execute Other Storage Node Commands

Run help to see other commands:

docker exec -it storagenode /app/storagenode help

Run the following to execute other commands:

docker exec -it storagenode /app/storagenode <<command>>