Ansible based Installation

Prerequisites

Nodeum is compatible with the RHEL, Rocky, and AlmaLinux families. Please refer to the software requirements for further details.

Installing Nodeum Software

Nodeum can be installed on either a physical server or a virtual machine. To learn more about hardware requirements, please refer to the official documentation. The installation process utilizes an Ansible Playbook or a Docker Image for setup.

Checklist

1. DNS Resolution: Ensure DNS resolution is functioning correctly.

2. Server Time: Verify the server's time is accurately configured.

3. Packages: unzip - tar - wget applications have to installed

4. Rights & Privileges: Execute the installation as root to get all required priviledges.

Install requirements for EL8 (RHEL, Rocky Linux, AlmaLinux)

Ensure Python 3.9 is installed

$ ls /usr/bin/python* -l
lrwxrwxrwx. 1 root root 9 Apr 25 2025 /usr/bin/python -> ./python3
lrwxrwxrwx. 1 root root 9 Apr 25 2025 /usr/bin/python3 -> python3.9
-rwxr-xr-x. 1 root root 15448 Apr 25 2025 /usr/bin/python3.9

If not install it:

$ dnf install python39

Installation of pip linked to python 3.9

$ dnf install python-pip
$ pip install pip --upgrade

Install Ansible. ansible-core must be 2.15 or later and earlier than 2.19.

$ pip install ansible

Verify the ansible version and the associated collections

$ ansible --version
ansible [core 2.15.13]
  config file = /root/v1-101-1/ansible.cfg
  configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/lib/python3.9/site-packages/ansible
  ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.9.25 (main, Dec 18 2025, 08:36:10) [GCC 8.5.0 20210514 (Red Hat 8.5.0-28)] (/usr/bin/python3.9)
  jinja version = 3.1.6
  libyaml = True

$ ansible-galaxy collection list | grep -E "community.general|community.crypto|ansible.utils|community.mongodb|community.mysql"
ansible.utils                 2.12.0
community.crypto              2.16.1
community.general             7.5.2
community.mongodb             1.6.3
community.mysql               3.8.0

Install requirements for EL9 (RHEL, Rocky Linux, AlmaLinux)

Ensure Python 3.9 is installed

$ ls /usr/bin/python* -l
lrwxrwxrwx. 1 root root 9 Apr 25 2025 /usr/bin/python -> ./python3
lrwxrwxrwx. 1 root root 9 Apr 25 2025 /usr/bin/python3 -> python3.9
-rwxr-xr-x. 1 root root 15448 Apr 25 2025 /usr/bin/python3.9

If not install it:

$ dnf install python39

Installation of pip linked to python 3.9

$ dnf install python-pip
$ pip install pip --upgrade

Install Ansible. ansible-core must be 2.15 or later and earlier than 2.19.

$ pip install ansible

Verify the ansible version and the associated collections

$ ansible --version
ansible [core 2.15.13]
  config file = /root/v1-101-0/ansible.cfg
  configured module search path = ['/root/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /usr/local/lib/python3.9/site-packages/ansible
  ansible collection location = /root/.ansible/collections:/usr/share/ansible/collections
  executable location = /usr/local/bin/ansible
  python version = 3.9.21 (main, Feb 10 2025, 00:00:00) [GCC 11.5.0 20240719 (Red Hat 11.5.0-5)] (/usr/bin/python3)
  jinja version = 3.1.6
  libyaml = True
$ ansible-galaxy collection list | grep -E "community.general|community.crypto|ansible.utils|community.mongodb|gluster.gluster|community.mysql"
ansible.utils                 2.12.0
community.crypto              2.16.1
community.general             7.5.2
community.mongodb             1.6.3
community.mysql               3.8.0
gluster.gluster               1.0.2

Upgrade the community.general collection is lower than 8.2.0

community.general.dnf_config_manager is required for CRB. The module has been introduced in community.general 8.2.0. It does not exist in 7.5.2.

$ ansible-galaxy collection install community.general --upgrade
$ ansible-galaxy collection list community.general

Nodeum Installation and Update Guide

To install or update Nodeum, follow these steps. Ensure the host has unrestricted internet access.

Download the Nodeum ansible package:

1. Install wget:

   yum install wget

2. Download the Nodeum package:

   wget get.nodeum.io/public/nodeum-v2-x-y-zzz.tar.gz

3. Extract the package:

   tar -xvzf /root/nodeum-v2-x-y-zzz.tar.gz

4. Navigate to the extracted folder:

   cd v2-x-y

The inventory location is defined by inventory in ansible.cfg. It must be stored in a specific folder and be available for each installation. To do this, move the folder into the standard inventory location:

1. Create the Nodeum directory:

   mkdir ~/nodeum

2. Move the inventory:

   mv ./inventory ~/nodeum/inventory

Password Configuration

Passwords are crucial for internal database usage. It's essential to define them initially, as changes after the first installation should be avoided. Configure passwords in the following file:

~/nodeum/inventory/group_vars/all/passwords-v1.yml

This file must also contain the Redis password:

redis_server_password: "REPLACE_WITH_A_STRONG_RANDOM_PASSWORD"

For production systems, file encryption is highly recommended. Learn more by exploring the "Customize Your Installation" guide.

Internal Certificate Authority

Nodeum secures communication between its internal services and databases with certificates that Ansible generates from a dedicated internal CA. You must provide this CA as files/pki/ca.crt and files/pki/ca.key inside your inventory directory before running the playbook.

From your inventory directory (for example ~/nodeum/inventory), run:

mkdir -p files/pki
openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:prime256v1 -nodes \
  -days 3650 -subj "/CN=ACME Nodeum Internal CA" \
  -addext "basicConstraints=critical,CA:TRUE,pathlen:0" \
  -addext "keyUsage=critical,keyCertSign,cRLSign" \
  -keyout files/pki/ca.key \
  -out files/pki/ca.crt

You may change the CN text ACME Nodeum Internal CA; it is a label, not a DNS setting. Otherwise, use the command unchanged.

Securely back up both files. A corporate intermediate CA is not accepted.

Installation Guide

1. Install EPEL Release:

   $ yum install epel-release

2. Install sshpass:

   $ yum install sshpass

   Note: This command is essential for installations on multiple nodes and for adding each host's fingerprint to the known_hosts file. You can do this by executing ssh commands on each node.

3. Verify Installation:

   Execute the check_install playbook:

   $ ansible-playbook check_install.yml

4. Run Installation:

   If you are not using an encrypted password file, execute:

   $ ansible-playbook install.yml

If Ansible requests a reboot, restart the server. Once it has restarted, execute the command again.

1. Verification:

After completing the playbook installation, verify that it finishes successfully and produces the expected output.

Be aware that no results have failed.

Accessing the Console

To access the Console, open your browser and enter the URL: http://your-nodeum-ip-address/ or use the DNS name associated with it.

If you cannot access the Console on the default HTTP port, it could be due to your local firewall settings. Ensure that your firewall is configured to permit HTTP/HTTPS traffic to the server.

Accessing the metrics endpoint

If you configured the Nodeum metrics endpoint (see Customize your Installation), metrics are available at http://<IP-of-the-selected-interface>:9180/metrics.

Running Ansible Playbook with Encrypted Passwords

If you have an encrypted password file, execute the Ansible playbook using:

• Prompt for vault password:

  ansible-playbook --ask-vault-password install.yml

• Use a vault password file:

  ansible-playbook --vault-password-file=password_file install.yml

Even if the user is in the sudoers file, Ansible might still ask for a sudo password. Use the -kK options to prompt for both SSH and sudo passwords:

ansible-playbook install.yml -kK

Post-Ansible Verification

After completing the deployment, verify that all defined storage configurations are present in the data mover service. To do this, review the file located at /etc/nodeum/mover.toml.

Step 1: Verify Plugin Status

Ensure that the Object Storage plugins:

s3.so is correctly defined and enabled.

/etc/nodeum/mover.toml
--

...

[[plugins]]
  path = "s3.so"

...

swift.so is well defined

/etc/nodeum/mover.toml
--

...

[[plugins]]
  path = "swift.so"

...

Verify Configuration

For Mounted File system Storage

/etc/nodeum/mover.toml
--
...  
[[storages.options]]
  # Applying additional options to connect to POSIX file system
  type = "nas-share"
  parent_name = "data1"
  [storages.options.handler]
    # will always be considered mounted in this directory, no mounting will be 
    attempted
    always_mounted = true
    path = "/mnt/data1"
...

For OpenStack Swift Storage

/etc/nodeum/mover.toml
--
...
[[storages.options]]
  # Applying additional options to connect to OpenStack swift as IDP
  parent_name = "swift_connector"
  [storages.options.handler]
    region_name = "my-region"
    auth_url = "https://my-swift-storage-url/"
    identity_provider = "your provider"
    auth_protocol = "openid"
...

Configuration Change

To update your configuration, modify the /etc/nodeum/mover.toml file. Ensure you apply changes to all nodes if multiple nodes are running the mover service.

Please ensure to save the file and restart the mover service.

$ sudo systemctl restart nodeum_mover.target

Caution: Manual changes will be overwritten if you relaunch Ansible without updating the group_vars/all/options.yml Ansible Inventory file. Always backport your manual changes to avoid losing them.

Customize Your Installation

You can define and automate various options during deployment. Visit the Customize Your Installation page for more information.