Upgrade Using Ansible

Upgrade Using Ansible#

This section describes how to upgrade an existing Carbonio installation using an Ansible playbook.

Before starting the procedure, make sure you meet all the requirements described in Requirements & Preliminaries.

Requirements & Preliminaries#

Before starting the upgrade procedure with Ansible, take the following points into account:

  • The latest version of the carbonio_upgrade Ansible Galaxy collection must be installed.

  • This upgrade procedure also works if Carbonio was originally installed manually, as long as the inventory is correctly filled with your infrastructure data.

  • The current Carbonio version is not relevant: you can upgrade from any supported version and the system will be upgraded to the latest available release.

  • The Ansible Galaxy collection updates all system packages available from the enabled repositories, not only Carbonio packages. To avoid unintended upgrades, disable or comment out any repositories you do not want Ansible to use before running the playbook.

  • The upgrade procedure does not modify the chat system currently in use:

    • If you are using legacy Chats, they will be left untouched.

    • Legacy Chats will not be removed, set to read-only, or migrated to the new Chats system.

Install or Upgrade the carbonio_upgrade Collection#

To install or update the carbonio_upgrade Ansible Galaxy collection, run the following command:

ansible-galaxy collection install zxbot.carbonio_upgrade -U

The -U flag ensures that the collection is installed if not already present, or updated to the latest available version if it is already installed.

This command installs all the required Ansible infrastructure needed to perform the Carbonio upgrade.

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.

Specific upgrade Paths#

If you are upgrading from older Carbonio releases or need to handle special inventory configurations, see:

Upgrade Using Ansible from older versions

Contents