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 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:

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

Cloning the Repository

To clone, run:

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




(Use ‘nano’ or ‘vi’ to edit the files)

These files have comments above each option to help you figure out if anything needs to be modified.

Configure Memory Limits

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


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

Very important value to set before the installation is the password and/or username with which you can access IOTA Peer Manager on the browser.

Edit the group_vars/all/iotapm.yml file and set a user and (strong!) password of your choice:

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

If you already finished the installation and would like to add an additional user to access IOTA PM, run:

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


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

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

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.

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.


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, but is 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.


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

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

Then, clone this playbook to /opt:

cd /opt && git clone && cd iri-playbook

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

A few parameters might required configuring. Both IOTA Peer Manager and the fullnode monitoring need to know on which port to access IRI API.

This is usually port 14265.

  1. Edit edit group_vars/all/iri.yml and make sure 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. Here you will see install_nginx: true, set it to false if you don’t want to install nginx and serve these services via webserver. If you choose to install nginx leave it with 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. If using nginx, edit iotapm_nginx_user and iotapm_nginx_password, this 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,iotapm_role
  • To install full node monitoring only, run:
ansible-playbook -i inventory -v site.yml --skip-tags=iotapm_npm --tags=iri_firewalld,iri_ufw,iotapm_deps,monitoring_role
  • To install both Peer Manager and fullnode monitoring, run:
ansible-playbook -i inventory -v site.yml --tags=iri_firewalld,iri_ufw,iotapm_role,monitoring_role