Using Ansible

Using Ansible#

The upgrade procedure with Ansible Galaxy is strongly suggested when you are upgrading from the previous version, which will take care of all the tasks required.

Before starting the procedure, make sure that you satisfy the Requirements & Preliminaries, then choose one of the supported Upgrade Paths.

Please also check Sections Known Issues (Current Release) or Known Issues (Older Releases) for known issues impacting the upgrade process, depending on the version from which you are upgrading.

Requirements & Preliminaries#

The following points must be taken into account before starting the upgrade procedure with Ansible.

If you do not have yet a working Ansible environment, please follow the instructions in section Prepare the Ansible Environment
You need to install the latest carbonio_upgrade Ansible Galaxy collection installed
- If you already have installed it, make sure that it is updated, see how to check the current version
The upgrade procedure does not depend on the underlying supported operating system. However, note that this release, 25.03, is the last version supporting Ubuntu 20.04 LTS, which goes EOL in May 2025, so you are strongly recommended to upgrade to Ubuntu 22.04 LTS.
This upgrade procedure works even if you installed Carbonio manually: see Section Upgrade Paths for details
The version of Carbonio that you want to upgrade is not important: you can start from any version (24.12, 24.9, or older) and you will always end up with the latest version (25.3.0 at the time of writing)
The Ansible Galaxy collection will update all the packages installed on the system, from any active configured repository, not only Carbonio's. To avoid this behaviour, comment out any repositories from which you do not want to upgrade packages.
Ansible will not upgrade PostgreSQL to version 16, you need to upgrade it manually: please refer to Section Upgrade to PostgreSQL 16. Carbonio no longer supports PostgreSQL 12, which must be upgraded to version 16 before upgrading Carbonio to 25.3.0. Check section Upgrade to PostgreSQL 16 for directions.
The upgrade procedure using Ansible is slightly different depending if you already installed Work Stream Collaboration (Chats) or not. Choose the right upgrade path according to your setup.
If you install Work Stream Collaboration (Chats) in the upgrade procedure:
- The old, legacy Chats will be left untouched, i.e., it will neither be removed, nor set in read-only mode
- No migration of the old (legacy) Chats to WSC will be performed

Install carbonio_upgrade collection

To install the latest carbonio_upgrade collection, issue the following command, which will install the necessary infrastructure to use for the Carbonio upgrade.

$ ansible-galaxy collection install zxbot.carbonio_upgrade

Update Ansible Galaxy collection

The collection is version-dependant: to upgrade Carbonio to version 25.3.0, you need to have the same main version of the collection. For example, to upgrade to version 25.3.0, the collection version must be 25.3.X, regardless of the last number. To install the latest version of the collection, execute the following command.

$ ansible-galaxy collection install -U zxbot.carbonio_upgrade

Check current Collection version

To verify the currently installed version of the collection, execute command

$ ansible-galaxy collection list zxbot.carbonio_upgrade

The output will be similar to:

# /home/ansible/.ansible/collections/ansible_collections
Collection             Version
---------------------- -------
zxbot.carbonio_upgrade 25.3.0

This version of the collection can be used to upgrade Carbonio to the most recent version in the 25.3 series of Carbonio.

Upgrade Paths#

To upgrade with Ansible, the inventory file must accurately reflect the Carbonio infrastructure. This is particularly important if you installed Carbonio manually and are now upgrading with Ansible. In this case, you can use an inventory file from one of the Installation Scenarios and adapt it to your Carbonio infrastructure. See section Prepare Inventory for directions.

These are the alternatives to upgrade an existent Carbonio infrastructure, depending if you have installed the latest 24.12 version or an older one.

Hint

If you are unsure, check the command to retrieve the correct version number.

Upgrade From Carbonio 24.12#

If you are upgrading from the 24.12 series version (24.12.0 and 24.12.1), there are two different paths, depending on whether you previously installed with Ansible or not.

Carbonio was Installed with Ansible#

The infrastructure has no Work Stream Collaboration (Chats) Role installed. In this case, add an this (empty) block at the end of the file:
```
[workStreamServers]
```
You can now proceed to Section Run the Upgrade below.
The Work Stream Collaboration (Chats) Role was manually installed. In this case, edit the inventory file and add this block at the end of the file:
```
[workStreamServers]
wsc.example.com
```
Replace the wsc.example.com string with the actual FQDN of the Node on which Work Stream Collaboration (Chats) is installed, then proceed to Section Run the Upgrade below.

Carbonio was Manually Installed#

The infrastructure has no Work Stream Collaboration (Chats) Role installed. You need to compile the inventory file, then you can proceed to Section Run the Upgrade below.
The infrastructure has the Work Stream Collaboration (Chats) Role installed. Compile the inventory file and then, like in the previous case, edit the inventory file and add this block at the end of the file:
```
[workStreamServers]
wsc.example.com
```
Replace the wsc.example.com string with the actual FQDN of the Node on which Work Stream Collaboration (Chats) is installed, then proceed to Section Run the Upgrade below.

Carbonio has both Work Stream Collaboration (Chats) and Legacy Chats installed

Regardless if you installed manually or with Ansible, if both the Work Stream Collaboration (Chats) Role and the legacy Chats and Video Server Roles are installed, you need to edit the inventory file like above:

[workStreamServers]
wsc.example.com

Ansible will take care of upgrading all Nodes, including those installing the legacy Roles. Note, however, that there are no updates to the packages providing these Roles, so they will keep the same version.

In both cases, you need to save the inventory file in the data directory (see Section Run the Upgrade below`). You must also save in that directory these additional files, which contain access passwords for various services. You should have saved these password during the installation process.

inventory_postgrespassword must contain the password of PostgreSQL administrative user, called DB_ADM in the documentation.
inventory_ldap_password must contain the password that you can retrieve with the command, executed as the zextras user on the node featuring the Mesh & Directory Role
```
zextras$ zmlocalconfig -s | grep ldap_password"
```
inventory_consulpassword must contain the password stored in file /var/lib/service-discover/password
inventory_videoserver_password must contain the password used by the Carbonio VideoServer, that you can retrieve with the command, executed as the root user on the Node installing the Carbonio VideoServer:
```
# grep api_secret /etc/janus/janus.jcfg
```

Upgrade From Carbonio 24.9 or Older#

If you are upgrading from the 24.9 version or older, you need to make sure that you inventory file still contains the DB Connector Role:

[dbsConnectorServers]
srv3.example.com

Replace the srv3.example.com string with the actual FQDN of the Node on which the Role is installed.

While the Role was removed, its presence is necessary to allow Ansible to properly deal with the packages providing the Role: pgpool will be removed, while the *-db packages will be moved to the Node where the Database Role is installed.

After the successful upgrade, the Role can be emptied and a comment can be added to the inventory file, for example:

### Keep this Role empty and uncommented
[dbsConnectorServers]

Run the Upgrade#

To run the upgrade, you need to move to the directory where you have the inventory file of your installation (it is called data in the Ansible Setup Section), then issue the command below. Before running it, please note that:

The command will automatically remove all unused dependencies installed on your system. To prevent this behaviour, add to the command line the option --extra-vars skip_autoremove=1
- Packages that were manually installed and are no longer used will not be removed from your system: you need to remove them manually

$ ansible-playbook zxbot.carbonio_upgrade.carbonio_upgrade \
-u root -i carbonio-inventory

In case the procedure does not complete successfully, you can run the command a second time, during which the tasks that successfully run will be skipped. For details, refer to Section Troubleshooting Ansible Installation.