Prepare the Ansible Environment

Prepare the Ansible Environment#

Section Roles Description and Installation reviews all the roles that make up Carbonio and the tasks required to successfully complete the installation.

To make the installation process easier and faster, this section introduces an alternative installation method based on Ansible Galaxy, an Ansible playbook, and an Ansible inventory file .

Note

Ansible is free software that allows you to automate the configuration and management procedures on Unix-like and Windows systems.

Ansible will read an inventory file containing a list of the Nodes on which to install the various Roles and automatically execute on the proper Node all the necessary tasks.

Once the Control Node (i.e., a workstation with Ansible installed and from which to launch Carbonio installations, see Section Ansible Setup below) has been properly set up according the directions below, the ansible installation only requires to edit the inventory file and run one CLI command to execute the playbook.

Requirements#

You can run the Ansible playbook form any control node, which runs Linux, macOS, or BSD, satisfying the following requirements

Note

Using Ansible from a Windows control node is not straightforward: If you want to use the Ansible playbook from a Windows control node, please read the official Windows FAQ for setting it up.

Control Node requirements

  1. The control node has a working installation of Ansible (see Section Ansible Setup for directions)

  2. The control node has SSH access as the root user to all the Nodes on which Carbonio must be installed. This is necessary because Ansible needs to install packages and carry out various tasks which require root privileges.

    Hint

    You can temporarily copy the SSH key of the user on the control node to the .ssh/authorized_keys file of the Nodes’ root user

Nodes requirements

Besides the Requirements that every Node must satisfy, each Nodes must

  1. be equipped with the same supported OS (see section Software Requirements)

  2. be able to reach one another via SSH

  3. have the Carbonio repository configured (see section Preliminaries for directions)

Ansible Setup#

This section guides you in the set up of a control node featuring Ansible (the Control Node) and the Carbonio Ansible playbook, with the purpose to install Carbonio on an existing infrastructure.

The control node should run on any Linux, macOS, or BSD box. Windows is supported but needs some work, therefore it is not mentioned here.

Install Ansible - Linux#

On Linux, Ansible can be installed using packages in the distribution’s repository, hence using the distribution’s package manager. Please refer to the official installation guide. This procedure pulls all the necessary dependencies, including python3.

To verify that installation was successful, run the following command on the control node

$ ansible --version

Install Ansible - macOS, BSD#

The best installation option on these platforms is to use homebrew, provided a python3 interpreter is installed on the system. You can follow these directions.

Install Carbonio Playbook#

Carbonio Playbook is available from Ansible Galaxy in two variants: one for Single-Server Scenario and one for all other scenarios. You need to simply run a command to install either of them. The playbooks are version-dependant: to install Carbonio you will need to use the corresponding playbook version. Please ensure that you always have installed the latest playbook to be able to install the most recent Carbonio release.

Playbook for Single-Server Scenario
# ansible-galaxy collection install zxbot.carbonio_ssinstall
Playbook for all other Scenarios
# ansible-galaxy collection install zxbot.carbonio_install

Configure Ansible#

You can configure Ansible using the ansible.cfg file. Please refer to the official documentation for directions.

Multiple Inventories#

If you plan to install multiple instances of Carbonio on different environments, we suggest that you create a dedicated directory to store the various inventories required for the different setups.

Contents