Ctrl+K
What do you think about our new Documentation Layout? Take the survey
Back to Documentation Hub

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 and an Ansible playbook to be run.

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 the Nodes on which to install the various Roles and automatically execute on the selected Nodes all the necessary task.

Once the Control Node (see Section Ansible Setup below) has been properly set up according the directions in the remainder, 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 workstation, which runs Linux, macOS, or BSD, satisfying the following requirements

Note

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

Workstation requirements

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

  2. The workstation 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 workstation to the .ssh/authorized_keys file of the Nodes’ root user

Nodes requirements

Besides the Requirements that every Node must satisfy, the Nodes

  1. must be equipped with the same supported OS

  2. must be able to reach one another via SSH

Ansible Setup#

This section guides you in the set up of a workstation 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.

If you prefer alternative installation methods, like using manual python package installation, containers, or from source code, please refer to the Installing Ansible section of the official documentation, which includes also installation requirements.

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 Playbook#

While you can simply clone (or better, fork) the repository on the control node and use it to keep everything therein, we suggest a slight different approach.

First, create a top-level directory in a location of your choice, for example in the home directory of the user that will run the playbook (preferably not the root user),

$ mkdir carbonio-ansible

Enter the directory

$ cd carbonio-ansible

Now create a directory called data

$ mkdir data

Then clone the repository, which is read-only, meaning you can only pull the code

$ git clone https://github.com/zextras/carbonio-install-ansible

Note

Alternatively, you can also point your browser to that link and fork or download the repository.

This command creates a directory called carbonio-install-ansible, so you have created this structure within carbonio-ansible:

$ ls -1
carbonio-install-ansible
data

The idea is that you keep the repository clean, so you can simply git pull whenever there is some update and use the data to keep all the information about the Carbonio infrastructure(s) that you manage.

Playbook Information#

The ansible playbook is publicly available on the read-only GitHub repository zextras/carbonio-install-ansible.

The repository will be updated either when new features will be made available or other improvements will be implemented.

Strong points of the playbook are:

  • It will be updated by the Zextras team

  • It automatically recognises the OS on the Nodes, therefore it chooses the appropriate packages for your operating system, and execute only those commands necessary for installation for that environment

  • only require to fill in a template and launch the playbook using a single CLI command

  • When more scenarios will be added, suitable inventory files will be added

Configure Ansible#

You can configure Ansible using the ansible.cfg in the cloned repository (i.e., in directory carbonio-install-ansible). We suggest to define at least a log file, which you can do achieve as follows:

[defaults]
log_path=/var/log/carbonio-ansible.log
Contents