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.
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 Configuring my server with HTTPS and search for the “Let’s Encrypt” link.
Update System Packages¶
For Ubuntu we type:
and for CentOS:
This will search for any packages to update on the system and require you to confirm the update.
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
For Centos we have a few options how to check if a reboot is required.
One of these options requires to install
yum install yum-utils -y
Once installed, we can run
# 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
shutdown -r now)
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).
See Using Nano to Edit Files for instructions on how to use
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.
In these two variable files you will find some configuration parameters for the installation. You can edit those using “nano” (see Note below).
To edit files you can use
nano which is a simple editor. See Using Nano to Edit Files for instructions.
Configure Memory Limits¶
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¶
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
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).
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
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.
- 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.
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.
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.
In order to install IOTA Peer Manager or fullnode monitoring, some packages and updates are required.
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
yum install git ansible curl -y
Clone this playbook to
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
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.
edit group_vars/all/iri.ymland make sure the
iri_api_port:option points to the correct IRI API port. In addition, ensure that
iri_tcp_portmatch the ports your IRI is using for neighbor peering.
install_nginx: trueand set it to
falseif 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
As mentioned earlier: currently, the fullnode monitoring depends on nginx being installed.
- In the same file
group_vars/all/iotapm.yml, if using nginx, edit
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
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.
It is possible to install Nelson as part of this installation.
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.
- 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.
#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.
journalctl --no-pager -n50 -u nelson to view 50 last lines of Nelson’s log.
- Nelson’s configuration file can be found here:
- Nelson’s data directory can be found here:
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.
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).
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.
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.
For more information and support with Carriota Field please join IOTA’s Discord and find “#carriota-field” channel.