Setting up a VPS IOTA Full Node from scratch

Leer versión en Español


In this tutorial I will guide you step by step through the process of installing and running a headless Full Node for the IOTA Network using the latest stable IRI release and a Virtual Private Server (VPS). We will also install iota-pm, in order to have a dashboard and be able to control our neighbors performance. I will be using Debian 9 in my local machine and in the VPS. If you use other OS, such as Windows, you can download a ssh tool like putty to connect to your remote server and run the commands we will cover. It should be just the same.

Note: You don’t need to be a Linux guru to do this. I have done this a couple of times and I ended up standardizing the process so anyone can get the results just by following this steps.

Getting a VPS

A Virtual Private Server is a virtual machine based server that allows you to connect and work on a given operating system as if it were a dedicated computer. You will be accessing the server and installing stuff from scratch on a Debian 9 Linux distribution. Ubuntu and other Debian based distros should be pretty similar -if not the same.

For this tutorial we will be using a Contabo VPS with 4 CPU cores, 12 GB RAM and 300 GB of SSD storage. As I write this tutorial, this plan costs 8.99 Euros.

Once we finished paying for the VPS, we will receive our public IP and the root password to login to the box via ssh. So, lets start there.

Starting the setup

We will be assumming that my public IP Address is Last numbers are not shown because this is actually a Full Node I will be running. You should replace this IP with yours whenever the IP is used in this tutorial. So my should be the public IP you got from your VPS.

First of all, let’s login to the VPS. Since my IP is I will type in the terminal ssh [email protected] The server will ask for my root password, which I got from the VPS provider.

We are in! Let’s go to the /opt directory and start installing some needed stuff: Git, Maven and Java 8. To get this done, just use the following commands. Note that everytime you run apt install command you will be prompted to confirm that you want to install the package. Just press the Y key and hit enter.

[email protected]:/# cd /opt
[email protected]:/opt# apt install git
[email protected]:/opt# apt install maven
[email protected]:/opt# apt install default-jre
[email protected]:/opt# apt install default-jdk


If everything went fine, you should now be able to see what java version you have installed by typing the command java -version (as illustrated below).

We are now ready to start working with the IOTA IRI! Let’s clone the iotaledger Github IRI in our opt folder to get the latest version. Once we clone the repo a new iri folder will be created inside /opt. We need to compile the IRI and build the package with the following commands.

[email protected]:/opt# git clone
[email protected]:/opt# cd iri
[email protected]:/opt/iri# mvn clean compile
[email protected]:/opt/iri# mvn package


After executing this commands a new folder called target will be created (so now you have /opt/iri/target). Inside this folder you are going to find the executable IRI with this name iri-

If everything went fine, we should be able to run our node to test it. We still have no neighbors so we will just try starting it up to see if we have no errors and then we will stop it with ctrl + c.

[email protected]:/opt/iri# cd target
[email protected]:/opt/iri/target# java -jar iri- -p 14265

Because we need to pass some arguments to the IRI (such as the port used in the example), we will create a configuration file and place all the parameters in there. Once we have our config, we can run the node only passing that config file as an argument. Let’s create a config file called iri.ini inside the target folder and place in there the values we will use to configure our Node. We will be using nano, a command line based text editor. All you need to know about nano is that you can create a new file by typing nano newfile.txt. To save the file contents you do ctrl + o. To exit the file and get back to the terminal you hit ctrl + x.

[email protected]:/opt/iri/target# nano iri.ini


Great! Now lets see a little what we are going to include in this iri.ini configuration file.

PORT = 14265
NEIGHBORS = udp://neighbor-1:14600 udp://neighbor-2:14600
IXI_DIR = ixi
DEBUG = true
DB_PATH = mainnetdb


Note that in here you must list your neighbors. In order to have a fully working node you need to exchange your Full Node address (udp://, for this tutorial) with other users running Full Nodes called neighbors. Only once you add a neighbor to the list and that neighbor do the same with your Node, you have a valid pair. It’s very important to have stable 24/7 dedicated neighbors if you want your Full Node to sync and work properly. So it’s a two way process. You can look for neighbors in the #nodesharing Slack channel.


According to Come From Beyond, it’s better to have 3 or 4 neighbors working fine that a lot that wont run their nodes 24/7. The maximum number of neighbors should be 7. So go to the #nodesharing slack channel and start seeking for neighbors. They will give you their address (udp://, for instance) and you will have to give them yours (which is udp:// –remember that you should replace my ip with yours here)

Everytime you need to add a new neighbor you must stop your Full Node, edit the iri.ini, add the new neighbor address leaving a space between addresses, save the file (ctrl + o) and exit (ctrl + x). Finally you restart your node with the command we will see next.

Once you have your config file updated, you just start the Full Node again with the command used before and the -c iri.ini as the only argument. This will run your node using all the settings described in that config file. If your neighbors are working fine you will eventually start getting some data.

[email protected]:/opt/iri/target# java -jar iri- -c iri.ini

Checking your node’s API endpoint

Before you proceed installing some Graphic tool to monitor your and yours neighbors nodes, you should perform a test to see if your running node has a reachable API. This can be done by using curl as described in the IRI API Reference Guide. My node IP is so, its API should be reachable at In order to check this we will run this Curl command in the terminal

curl \
-H 'Content-Type: application/json' \
-H 'X-IOTA-API-Version: 1' \
-d '{"command": "getNodeInfo"}'


If everything went fine we should get a response of this type.

Setting up a Graphic Interface to control your Full Node

So far we have our node running and we can see the data as it goes down in the terminal. This is not very practical, specially if you wanna have an overview of how your neighbor’s nodes are working and how is your sync doing. In order to have a tool that makes all this easy we will install iota-pm. This node.js tool will give us a public point to access our Full Node via our browser.

Let’s install Curl, node.js and nmp to get this wonderful tool working.

[email protected]:/opt# apt install curl
[email protected]:/opt# curl -sL | sudo bash -
[email protected]:/opt# apt install nodejs
[email protected]:/opt# npm i -g iota-pm


And that’s all! Now we have our Peer Manager installed. In order to start it and be able to monitor our dashboard from the browser we must use the following command (remember to use your IP instead of mine!)

[email protected]:/opt# iota-pm -i -p


Once the command is running you can just go to your browser and point to to see a nicely designed dashboard.

Final considerations

Full Nodes are useful for helping IOTA network to get stronger only if they are running 24/7, in good shape and with reasonable neighbors performace. Add some neighbors to see how good they are doing and clean your neighbors list to only keep the ones that are always up and working.

When you start running your node, you will have to go through the get in sync process. This can take hours or days depending on your node performance and your neighbors health as well. If you are deleting addresses from your neighbor config section, let them know so they can also remove you.

Sometimes is best to run the Node and iota-pm commands as background tasks, so you can close your terminal without interrupting them. This can be achieved by using nohub and the ampersand at the end. For example:

[email protected]:/opt/iri/target# nohup java -jar iri- -c iri.ini &
[email protected]:/opt# nohup iota-pm -i -p &


Finally, you can easily check if your iri and iota-pm are running by using the ps ax command, which lists all the processes running at the time in the machine.