An almost complete guide to setting up a full IOTA node

So you’ve heard about IOTA?!?

And you even heard that it’s cool to run your own node? Great! That’s why you’re reading this. So let’s get started.

If you simply want to get up and running quickly, you can load a prebuilt docker container from https://hub.docker.com/r/iotaledger/iri/:

docker pull iotaledger/iri

But if you want to do it yourself, read on. You’re going to need to setup a VPS, or grab a spare computer. There are loads of tutorials on how to set one of those up, so we won’t go into details on that. You’re probably going to want one with at least 4GB of RAM. Yes, you could get away with less, but you’ll have issues. Come on back when you have a fresh install of Linux on that machine.

For this walk-through, we’ll be using Ubuntu 16.04 (Xenial) but any modern Linux distro should work.

First we’re going to want to update the base libraries. From a terminal command prompt, enter:

$ apt update

If you have permission issues, prepend every command we’ll enter with sudo <command> e.g. $ sudo apt update

Then we’re going to need a JVM installed, because the current IOTA Reference Implementation (IRI) is written in java. There’s a rust and clojure implementation in the works, but they’re not ready for prime-time just yet. So java it is.

Users have reported having some issues using OpenJDK, so we’re going to use the JDK from Oracle:

# install Java8
add-apt-repository ppa:webupd8team/java
apt-get update
apt-get install oracle-java8-installer
apt-get install -y maven 

# set environment variables
apt-get install oracle-java8-set-default

# confirm it was installed correctly
java -version >> /dev/null

If that last command returns something like:

$ java -version >> /dev/null
java version "1.8.0_144"
Java(TM) SE Runtime Environment (build 1.8.0_144-b01)
Java HotSpot(TM) 64-Bit Server VM (build 25.144-b01, mixed mode)

then we’re good to continue.

Optional: we can clean up after the installation:

# remove cache
rm -rf /var/lib/apt/lists/*
rm -rf /var/cache/oracle-jdk8-installer

Now we’re actually getting to the fun part: Installing IOTA

We have two options:

• 1. download and build from the source:

# Note: you can put the IRI in whatever directory you want.
$ cd /opt/install

$ git clone https://github.com/iotaledger/iri
$ mvn clean compile
$ mvn package

note: If you don’t have git installed, run $ apt install -y git before cloning the repo

• 2. download the iri-<version>.jar file and run that.

$ cd /opt/install
$ wget https://github.com/iotaledger/iri/releases/download/v1.4.2.4/iri-1.4.2.4.jar

The current version as of this writing is is v.1.4.2.4 and will likely be higher when you’re reading this. Go to https://github.com/iotaledger/iri/releases to find out the lastest version. Replace the version number in the line above. You should generally always be running the latest version. So check back periodically to make sure you’re up to date and update as necessary.

You have enough set up now to run IRI. congrats!

java -jar <target>/iri-<version>.jar -p 14265

Verify that your node is running:

$ curl -X POST -H "X-IOTA-API-Version: 1.0" -H "Content-Type: application/json" -d '{"command": "getNodeInfo"}' http://localhost:14265

But… it’s not quite enough to really be up & running. You’re going to need some neighbors to connect with. And the way that works is becoming known as tethering. And the way to find neighbors was in slack, but has since completely moved over to discord. So make your way to the iotaledger group on discord and hop into the#nodesharing channel and start asking around politely for who else needs some neighbors.

Note: Another emerging option for building up your tethered neighbors, is to use [Nelson](https://github.com/SemkoDev/nelson.cli) which I highly recommend checking out, but is outside the scope of this tutorial.

If you go with manually tethering, there are recommendations floating around that 8–10 neighbors is enough to maintain the latest transactions.

Do not share the IP or DNS address of your node publicly in the channel. Instead, direct message (DM) people and ask to connect with them privately. This helps prevent the possibility of your node getting spammed or attacked by malicious parties.

So you’ve direct-message contacted some people in discord and you’ve exchanged your respective node addresses. Great, you’re going to want to add those to your iri.ini file. If it doesn’t exist, create it using your favorite editor and save it to the top-level directory. It’s just a simple config file.

Your iri.ini file should contain at least the following:

[IRI]
PORT = 14625
TCP_RECEIVER_PORT = 14700
UDP_RECEIVER_PORT = 14700
NEIGHBORS = tcp://<NEIGHBOR1>:<PORT> tcp://<NEIGHBOR2>:<PORT> udp://<NEIGHBO3>:<PORT> udp://<NEIGHBOR-N>:<PORT> 
IXI_DIR = ixi
HEADLESS = true
DEBUG = false
DB_PATH = db

replacing the NEIGHBORS with the addresses of those you’ve mutually agreed to connect with from slack.

IMPORTANT: The only way for it to work is if BOTH sides have MUTUALLY added each other as neighbors. It is not enough for you to simply add them if they don’t add you.

You can verify that data is flowing with your neighbor(s) by issuing the following command:

$ curl -X POST -H "X-IOTA-API-Version: 1.0" -H "Content-Type: application/json" -d '{"command": "getNeighbors"}' http://localhost:14265
{:neighbors
 [{:address "<NEIGHBOR_IP_ADDR>:<PORT>",
   :numberOfAllTransactions 17409,
   :numberOfRandomTransactionRequests 4125,
   :numberOfNewTransactions 3134,
   :numberOfInvalidTransactions 0,
   :numberOfSentTransactions 30059,
   :connectionType "udp"}...]
If the numbers above are 0, then IOTA transactions are not flowing.

Some other things that might trip you up: make sure your firewall or VPS settings are set to allow the UDP and/or TCP traffic on the port you specify.

Depending on how many neighbors you connect with, and how ‘synced’ they are, getting caught up & verifying the full tangle may take some time. Be patient.

If you want to enable remote access to your node, add the following to your iri.ini

API_HOST = 0.0.0.0
REMOTE_AUTH = user:ChooseAReallyLongSecureSuperSecretPasswordToPutHere

and restart IRI with the -c <iri.ini> flag:

java -jar target/iri-1.4.2.4.jar -c iri.ini 

Or if you want to remove which commands can get executed against your node at runtime, you can specify which of those the —remote-limit-api flag:

java -jar target/iri-1.4.2.4jar --remote --remote-limit-api "removeNeighbors, addNeighbors"

You can also set some more run-time parameters, like JVM options, allowing remote auth, and logging to a file:

java -Xms256m -Xmx3328m -jar target/iri-1.4.2.4.jar -c /opt/install/iri/iri.ini --remote > /tmp/iri.log &

There are a few more advanced settings you can tweak, which — if there is community demand for it — I can include in future revisions of this article. For now, get involved in the community, ask questions, and of course, now that you have your own IOTA node running…

Go build the next great thing that uses IOTA!