Installation

If you have little to no experience with Linux, I recommend you use the Getting Started Quickly.

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.

Warning

All web pages served by this installer will be served on HTTPS with self-signed certificates. The browser will issue a warning when you connect for the first time. You can proceed and add the sites certificate as an exception. If you want valid certificates you can refer to serverHTTPS and search for the “Let’s Encrypt” link.

Update System Packages

For Ubuntu we 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.

One of these options requires to install yum-utils:

yum install yum-utils -y

Once installed, 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 upgrade -y && apt-get clean && apt-get update -y && apt-get install software-properties-common -y && apt-add-repository ppa:ansible/ansible -y && apt-get update -y && apt-get install ansible git nano -y

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).

Note

See Using Nano to Edit Files for instructions on how to use nano.

Cloning the Repository

To clone, run:

cd /opt && 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

In these two variable files you will find some configuration parameters for the installation. You can edit those using “nano” (see Note below).

group_vars/all/iri.yml

and

group_vars/all/iotapm.yml

Note

To edit files you can use nano which is a simple editor. See Using Nano to Edit Files for instructions.

Configure Memory Limits

In group_vars/all/iri.yml:

The options iri_java_mem and iri_init_java_mem in the configuration files can determine what are the memory usage limits for IRI.

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: 3072m
iri_init_java_mem: 256m

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.

Note

For the click-‘n-go installation, these values are automatically configured. You can choose to auto-configure those values: When running the playbook (later in this guide) you can add -e "memory_autoset=true" to the ansible-playbook command.

Set Access Password

This user name and password are used for all web-based authentications (e.g. Peer Manager, Monitoring Graphs).

Create a new variable file called group_vars/all/z-override.yml and set a user and a (strong!) password of your choice:

iotapm_nginx_user: someuser
iotapm_nginx_password: 'put-a-strong-password-here'

You can always add new users after the installation has finished:

htpasswd /etc/nginx/.htpasswd newuser

Replace ‘newuser’ with the user name of your choice. You will be prompted for a password.

To remove a user from authenticating:

htpasswd -D /etc/nginx/.htpasswd username

Note

This username and password will also be used for Grafana (monitoring graphs)

Configure Multiple Fullnodes

You can skip this section and proceed to “Running the Playbook” below if you are only installing on a single server.

The nice thing about Ansible’s playbooks is the ability to configure multiple nodes at once.

You can have hundreds of fullnodes installed simultaneously!

To configure multiple hosts you need to use their IP addresses or hostnames (hostnames must resolve to their respective IP).

Edit the file inventory. Here’s an example of how we would list four hosts, using hostname and/or IP:

[fullnode]
localhost        ansible_connection=local
iota01.tangle.io ansible_user=john
iota02.tangle.io ansible_user=root
10.20.30.40      ansible_ssh_port=9922

A requirement is that you can SSH access these servers from the server you are working on. Please check Configuring Multiple Nodes for Ansible for more information.

Running the Playbook

Two prerequisites here: you have already installed Ansible and cloned the playbook’s repository.

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).

Final Steps

Please go over the Post Installation chapters to verify everything is working properly and start adding your first neighbors!

Also note that after having added neighbors, it might take some time to fully sync the node, or read below the “Fully Synchronized Database Download” section.

If you installed monitoring and IOTA Peer Manager you should be able to access those:

Peer Manager: http://your-external-ip:8811
Grafana: http://your-external-ip:5555

Use the username and password from group_vars/all/z-override.yml if you set it there previously.

If you followed the Getting Started Quickly guide, you configured a password during the installation, and you can use user iotapm.

To configure an email for alerts see Sending Alert Notifications.

Fully Synchronized Database Download

In order to get up to speed quickly you can download a fully sycned database. Please check Where can I get a fully synced database to help kick start my node

Installing Only IOTA Peer Manager or Monitoring

It is possible to install individual components from the playbook. For example, if you already have installed IRI following a different guide/method, you can use this playbook to install the full node monitoring graphs or IOTA Peer Manager.

Overview

  • IOTA Peer Manager is a GUI to help monitor, add and remove neighbors: IOTA Peer Manager.
  • The full node monitoring includes monitoring and graphs for IRI and your node: IOTA Exporter.

Note

If you haven’t already, just make sure your server matches the The Requirements.

  • IOTA Peer Manager doesn’t require to be served via a webserver. It is however the recommeneded method, unless you want to use SSH tunnel.
  • At this stage, the full node monitoring graphs require to be served via a webserver (nginx), which will be installed via this playbook.

Warning

By installing either Peer Manager and/or the full node monitorting, the firewall will be configured and enabled. It is strongly discouraged to run a server without the firewall enabled. Therefore, this playbook does not support running without a firewall.

Updates

In order to install IOTA Peer Manager or fullnode monitoring, some packages and updates are required.

For Ubuntu:

apt-get upgrade -y && apt-get clean && apt-get update -y && apt-get install software-properties-common -y && apt-add-repository ppa:ansible/ansible -y && apt-get update -y && apt-get install ansible git -y

For CentOS:

yum install git ansible curl -y

Installation

Clone this playbook to /opt:

cd /opt && git clone https://github.com/nuriel77/iri-playbook.git && cd iri-playbook

This assumes that you haven’t already cloned the repository to this location. If you have, you should enter the /opt/iri-playbook directory and run a git pull.

Some parameters require configuration before the installation. Both IOTA Peer Manager and the fullnode monitoring need to know on which port to access IRI API.

This is usually port 14265.

Note that in those two steps we are configurinig the variables files directly. Please consider using an override-file to only edit those parameters you need. This will avoid conflicts when updating new versions of the playbook. See How to override playbook variables.

  1. Edit edit group_vars/all/iri.yml and make sure the iri_api_port: option points to the correct IRI API port. In addition, ensure that iri_udp_port and iri_tcp_port match the ports your IRI is using for neighbor peering.
  2. Edit group_vars/all/iotapm.yml. Find install_nginx: true and set it to false if you don’t want to install nginx to serve these services via webserver. If you choose to install nginx, leave it as true (if you already have nginx installed, just leave it as true).

As mentioned earlier: currently, the fullnode monitoring depends on nginx being installed.

  1. In the same file group_vars/all/iotapm.yml, if using nginx, edit iotapm_nginx_user and iotapm_nginx_password. These will set the user and password with which you will be able to access Peer Manager and/or the fullnode monitoring graphs.
  • To install IOTA Peer Manager only, run:
ansible-playbook -i inventory -v site.yml --tags=iri_firewalld,iri_ufw,iri_ssl,iotapm_role
  • To install full node monitoring only, run:
ansible-playbook -i inventory -v site.yml --skip-tags=iotapm_npm --tags=deps,iri_firewalld,iri_ufw,iri_ssl,iotapm_deps,monitoring_role
  • To install both Peer Manager and fullnode monitoring, run:
ansible-playbook -i inventory -v site.yml --tags=deps,iri_firewalld,iri_ufw,iri_ssl,iotapm_role,monitoring_role

Access

To access the fullnode monitoring graphs, point your browser to http://YOUR-IP:5555 and use the username and password you’ve configured earlier to log in.

To access the IOTA Peer Manager (assuming you’ve installed nginx), point your browser to http://YOUR-IP:8811 and use the username and password you’ve configured earlier to log in.

If you haven’t install nginx and want to access IOTA Peer Manager, it is not configured to be accessible externally by default. It would pose a security risk to your server running it exposed and not locked with a password. As an alternative you can use a SSH tunnel to bind to it (port 8011). See 2. Tunneling IRI API for Wallet Connection.

Install Nelson

It is possible to install Nelson as part of this installation.

Warning

Nelson is still at beta stage.

Nelson depends on IRI being installed and running. Please check /opt/iri-playbook/group_vars/all/nelson.yml and configure to match your environment.

If you installed using the Getting Started Quickly chapter, you can just proceed to the installation below.

Installation

  • If you installed this playbook before Nelson was added you need to update the git repository. Run:
cd /opt/iri-playbook && git pull
  • To install Nelson, run:
cd /opt/iri-playbook && ansible-playbook -i inventory -v site.yml --tags=nelson_role -e "nelson_enabled=true"

You can stop, start and restart nelson via systemctl (start|stop|restart) nelson.

Join the #nelson-peering channel on IOTA’s Discord if you have questions regarding Nelson.

Upgrade Nelson Version

Run the upgrade command:

cd /opt/iri-playbook && ansible-playbook -i inventory -v site.yml --tags=nelson_role -e "upgrade_nelson=true" -e "nelson_enabled=true"

View Status/Logs and configuration

  • To view nelson status run: systemctl status nelson.
  • To view nelson logs run: journalctl -u nelson.

Or journalctl --no-pager -n50 -u nelson to view 50 last lines of Nelson’s log.

  • Nelson’s configuration file can be found here: /etc/nelson/nelson.ini.
  • Nelson’s data directory can be found here: /var/lib/nelson/data.

Install Field

Please visit Carriota Field on Github to learn more about what it is.

Field has been added to the playbook as an optional add-on. The recommended way to install it is using the iric configuration tool.

You might want to upgrade the iric tool (there’s an option for that in the menu) if you are missing the option to enable Field.

Note

The playbook also installs field_exporter to show stats on Grafana. If you already have Field installed and don’t have the field_exporter installed yet: make sure you have the latest iric and then choose to update field (proceed with the update when asked).

Manual Installation

The variables file for Field is in /opt/iri-playbook/group_vars/all/field.yml. If you want to change any of the variables you can copy the file to: /opt/iri-playbook/group_vars/all/z-field.yml and edit this file. It will override anything in the original file when running the playbook.

Another option is to override variables adding -e some_var=someval for any variable you want to override on the Ansible command line.

The manual procedure to install Field:

cd /opt/iri-playbook && git pull && ansible-playbook -i inventory -v site.yml --tags=prometheus_config_file,field_exporter,field_role -e field_enabled=yes

This will result in Field installed and configured. You should check the configuration file at /etc/field/field.ini to configure your payout address and node’s name.

Control Field

To restart Field run:

systemctl restart field

To stop Field run:

systemctl stop field

To view the logs:

journalctl -u field

And use SHIFT-g to skip to the end of the logs.

Again, the recommended way to enable, upgrade and manage Field is via the iric tool that ships with the playbook.

Note

For more information and support with Carriota Field please join IOTA’s Discord and find “#deviota” channel.