Home

Welcome to the IOTA full node installation wiki!

My first tutorial has been written around August 2017. This tutorial is aimed at those who have at least some background working on the Linux command line (and was specifically written for CentOS).

Since then, the IOTA community has grown exponentially and many new members want to join the effort and host their own full node. And, as suggested by many tutorials (and justifiably), Linux is the best way to go.

I realized that it would be very helpful to write a new tutorial, one that aims at those who posses less, or almost no skills with Linux.

In addition, I found that many tutorials lack some overall system configuration. For example, running IRI as an unprivileged user, configuring firewalls and so on.

A copy-paste tutorial is awesome, but as it so often happens, the user misses some basic technical explanation about the setup. While it is impossible to include a crash-course of Linux for the purpose of this tutorial, I will try to explain some basic concepts where I find that many users had troubles with.

For some details I will leave it to you to google (for example, how to SSH access your server). Otherwise the tutorial becomes too lofty.

Overview

This tutorial will help you setup a full node on a Linux system (Ubuntu or CentOS). The git repository I have created includes an automated installation. I hope to be adding other distributions like Debian in the future.

It will install IRI and IOTA peer manager, a web GUI with which you can view your neighbors, add or remove neighbors, view the sync etc.

The Requirements

Virtual Private Server

This is probably the best and most common option for running a full node. I will not get into where or how to purchase a VPS (virtual private server). There are many companies offering a VPS for good prices. The basic recommendation is to have one with at least 4GB RAM, 2 cores and minimum 30GB harddrive (SSD preferably).

Operating System

When you purchase a VPS you are often given the option which operating system (Linux of course) and which distribution to install on it. This tutorial currently supports CentOS (>=7) and Ubuntu (>=16)

Accessing the VPS

Once you have your VPS deployed, most hosting provide a terminal (either GUI application or web-based terminal). With the terminal you can login to your VPS's command line. You probably received a password with which you can login to the server. This can be a 'root' password, or a 'privileged' user (with which you can access 'root' privileges).

The best way to access the server is via a Secure Shell (SSH). If your desktop is Mac or Linux, this is native on the command line. If you use Windows, I recommend installing Putty

There are plenty of tutorials on the web explaining how to use SSH (or SSH via Putty). Basically, you can use a password login or SSH keys (better).

System User

Given you are the owner of the server, you should either have direct access to the 'root' account or to a user which is privileged. It is often recommended to run all commands as the privileges user, prefixing the commands with 'sudo'. In this tutorial I will leave it to the user to decide.

If you accessed the server as a privileged user, and want to become 'root', you can issue a sudo su -. Otherwise, you will have to prefix most commands with sudo, e.g. sudo apt-get install somepackage.

Installation

To prepare for running the automated "playbook" from this repository you require some basic packages. First, it is always a good practice to check for updates on the server.

Update System Packages

For Ubuntu we can type:

apt-get update

and for CentOS:

yum update

This will search for any packages to update on the system and require you to confirm the update.

Reboot Required?

Sometimes it is required to reboot the system after these updates (e.g. kernel updated).

For **Ubuntu **we can check if a reboot is required. Issue the command ls -l /var/run/reboot-required

# ls -l /var/run/reboot-required
-rw-r--r-- 1 root root 32 Dec  8 10:09 /var/run/reboot-required

If the file is found as seen here, you can issue a reboot (shutdown -r now or simply reboot).

For Centos we have a few options how to check if a reboot is required. A simple one I've learned of recently is to install yum-utils:

yum install yum-utils -y

There's a utility that comes with it, we can run needs-restarting -r:

# needs-restarting  -r
Core libraries or services have been updated:
  systemd -> 219-42.el7_4.4
  glibc -> 2.17-196.el7_4.2
  linux-firmware -> 20170606-56.gitc990aae.el7
  gnutls -> 3.3.26-9.el7
  glibc -> 2.17-196.el7_4.2
  kernel -> 3.10.0-693.11.1.el7

Reboot is required to ensure that your system benefits from these updates.

More information:
https://access.redhat.com/solutions/27943

As you can see, a reboot is required (do so by issuing a reboot or shutdown -r now)

Installing Ansible

Ansible is an awesome software used to automate configuration and/or deployment of services. This repository contains what Ansible refers to as a "Playbook" which is a set of instructions on how to configure the system.

This playbook installs required dependencies, the IOTA IRI package and IOTA Peer Manager. In addition, it configures firewalls and places some handy files for us to control these services.

To install Ansible on Ubuntu I refer to the official documentation:

apt-get install software-properties-common
apt-add-repository ppa:ansible/ansible
apt-get install ansible git

For CentOS, simply run:

yum install ansible git nano -y

You will notice I've added 'git' which is required (at least on CentOS it doesn't have it pre-installed as in Ubuntu). In addition, I've added 'nano' which is helpful for beginners to edit files with (use vi or vim if you are adventurous).

Cloning the Repository

Issue a git clone https://github.com/nuriel77/iri-playbook.git && cd iri-playbook This will pull the repository to the directory in which you are and move you into the repository's directory.

Configuring Values

There are some values you can tweak before the installation runs. There are two files you can edit:

nano group_vars/all/iri.yml

and

nano group_vars/all/iotapm.yml

These files have comments above each option to help you figure out if anything needs to be modified. In particular, look at the iri_java_mem and iri_init_java_mem. Depending on how much RAM your server has, you should set these accordingly.

For example, if your server has 4096MB (4GB memory), a good setting would be:

iri_java_mem: 3072
iri_init_java_mem: 256

Just leave some room for the operating system and other processes. You will also be able to tweak this after the installation, so don't worry about it too much.

Running the Playbook

By default, the playbook will run locally on the server where you've cloned it to. You can run it:

ansible-playbook -i inventory site.yml

Or, for more verbose output add the -v flag:

ansible-playbook -i inventory -v site.yml

This can take a while as it has to install packages, download IRI and compile it. Hopefully this succeeds without any errors (create a git Issue if it does, I will try to help).

Post Installation

We can run a few checks to verify everything is running as expected. First, let's use the 'systemctl' utility to check status of iri (this is the main full node application)

Using the systemctl status iri we can see if the process is Active: active (running).

See examples below.

Controlling IRI

Check status:

systemctl status iri

Stop:

systemctl stop iri

Start:

systemctl start iri

Restart:

systemctl restart iri

Controlling iota-pm (IOTA Peer Manager)