Single-Server Installation

The installation on Ubuntu 20.04 or RHEL 8 is organised in steps, some of which are preliminary configuration tasks, and some is optional. During the installation and configuration of Carbonio CE, it is necessary to execute commands from the command line, so make sure you have access to it.

When the installation process has successfully finished, you can access Carbonio CE's GUI using a browser: directions can be found in Section Access to the Web Interface.

RHEL 8-only Preliminary Tasks

A few task are required for the installation of Carbonio CE on RHEL 8 systems, they concern the configuration of SELinux, the firewall, and the installation and configuration of Postgres 12. Indeed, The version of Postgres shipped by RHEL 8 is older than required by Carbonio CE.

Repositories

An active subscription (you must be able to fetch from BaseOS and the other main repositories):

# subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms

The CodeReady repository enabled:

# subscription-manager repos --enable codeready-builder-for-rhel-8-x86_64-rpms

The dedicated postgresql repository:

# yum -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm

SELinux and Firewall

SELinux

Must be set to disabled or permissive in file /etc/selinux/config. You can check the current profile using the command

# sestatus
Firewall

All the ports needed by Carbonio CE are open on the firewall or the firewall is disabled. To disable the firewall, issue the commands

# systemctl stop firewalld.service
# systemctl disable firewalld.service

Postgres

We need to make sure that Postresql 12 is installed, by running commands

# dnf -qy module disable postgresql
# dnf -y install postgresql12 postgresql12-server

Then, initialise and enable it.

# /usr/pgsql-12/bin/postgresql-12-setup initdb
# systemctl enable --now postgresql-12

To complete the setup, edit file /var/lib/pgsql/12/data/pg_hba.conf, find the line:

# IPv4 local connections:
host    all             all             127.0.0.1/32            ident

remove the # before host if present and change it as follows:

# IPv4 local connections:
host    all             all             127.0.0.1/32            md5

To make sure the changes are picked up by Postgres, reload it.

# systemctl reload postgresql-12

Step 1: Repository Configuration

In order to add Carbonio CE’s repository, go to the following page and fill in the form:

https://www.zextras.com/carbonio-community-edition/#discoverproduct

You will receive an e-mail containing:

  • the URL of the repository

  • the GPG key of the repository

Follow the instructions in the e-mail to add these data to your system.

Repository and Channels

The following are important information concerning the packages repository Carbonio CE and its content. Please read them carefully, as they might save you some time in case of installation or upgrade problems and help you to provide more precise bug reports.

The repository hosts simultaneously packages of two channels:

  • Release Candidate (RC). Packages in this channel are made available as soon as they are built by Zextras development and tested by the QA team. While they are stable, they are not suitable for a use in a production environment, because they might still contain some bug, new functionalities that have not yet reached a production-level quality, or some broken dependencies might be introduced.

    Usually these problems are fixed within days or even hours, so in case just try again before you report some problem.

    Use this channel and its packages for testing (or demo) installations only.

  • RELEASE. This channel contains only packages that are stable and suitable for a production environment.

Hint

When reporting a problem or opening a ticket, remember to always add the channel if you are using, as this helps us to analyse the problem quickly.

FAQ

  1. I want to help testing things, which channel should I use?

    RC channel.

  2. I need to install Carbonio in a production environment which channel should I use?

    RELEASE channel.

  3. How will we be informed about new RC packages?

    There will be no notification, because RC channel is updated continuously.

  4. How will we be informed about a potential new release incoming?

    A red message on the homepage of the documentation site will notify you of the release of a new stable version. You may also be informed through other means of communication such as email and social media.

  5. Could there be bugs in the packages downloaded from the RC channel?

    Yes, RC versions have a risk of containing bugs (which in some cases could lead to data loss). If you find a bug in an RC package we kindly ask you to report it on the appropriate community page. We will try to resolve it as quickly as possible.

Step 2: Setting Hostname

Carbonio CE needs a valid FQDN as hostname and a valid entry in the /etc/hosts file. To configure them, execute these two commands. First, set the hostname

# hostnamectl set-hostname mail.example.com

then update /etc/hosts with IP and hostname

# echo "172.16.0.10 mail.example.com mail" >> /etc/hosts

You can also simply get the current IP and hostname and save them:

# echo "$(hostname -I) $(hostname -f)"

Hint

Replace 172.16.0.10 with the actual management IP to be assigned to the server.

Installation task

Step 3: System Upgrade and Package Installation

After configuring the repositories, the installation of Carbonio CE requires to run a few commands.

We start by updating and upgrading the system.

# apt update && apt upgrade

# dnf upgrade

Next, we install all packages needed for Carbonio CE.

# apt install service-discover-server \
carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-mta \
carbonio-appserver \
carbonio-user-management \
carbonio-files-ce carbonio-files-db \
carbonio-storages-ce \
carbonio-preview-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-admin-ui carbonio-admin-console-ui \
carbonio-admin-login-ui postgresql-12

The installation on RHEL is divided in two steps. First, install the Carbonio Mesh service

# dnf install service-discover-server

Then, proceed with all other packages

# dnf install carbonio-directory-server \
carbonio-proxy \
carbonio-webui carbonio-files-ui \
carbonio-mta  \
carbonio-appserver \
carbonio-user-management carbonio-preview-ce \
carbonio-files-ce carbonio-files-db \
carbonio-storages-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-admin-ui carbonio-admin-console-ui \
carbonio-admin-login-ui

Post-Installation tasks

Step 4: Bootstrap Carbonio CE

Once all packages have been installed, use the following command to configure and launch Carbonio CE.

# carbonio-bootstrap

Before finalising the bootstrap, press y to apply the configuration. The process will continue until its completion: click Enter to continue.

What does carbonio-bootstrap do?

This command makes a few checks and then starts the installation, during which a few messages are shown, including the name of the log file that will store all messages produced during the process:

Operations logged to /tmp/zmsetup.20211014-154807.log

In case the connection is lost during the installation, it is possible to log in again and check the content of that file for information about the status of the installation. If the file does not exist anymore, the installation has already been completed and in that case the log file can be found in directory /opt/zextras/log.

The first part of the bootstrap enables all necessary services and creates a new administrator account (zextras@mail.example.com), initially without password (see below for instruction to set it).

Configuration and Setup tasks

The next steps concern the configuration and setup of the various Carbonio CE components.

Step 5: Setup Carbonio Mesh

Carbonio Mesh is required to allow communication between Carbonio CE and its components. The configuration is interactively generated by command

# service-discover setup-wizard

This command will:

  • ask for the IP address and netmask

  • ask for the Carbonio Mesh secret, which is used for setups, management, and to access the administration GUI. See section Carbonio Mesh Administration Interface for more information.

    This password will be denoted as MESH_SECRET throughout the documentation.

    Hint

    We suggest to use a robust password which is at least 16 characters long, including at least one of lowercase and uppercase letters, numbers, special characters and store it in a password manager.

    In case the password is lost or the credential file becomes corrupted and unusable, you can Regenerate Carbonio Mesh Secret.

  • store the setup in file /etc/zextras/service-discover/cluster-credentials.tar.gpg

To complete Carbonio Mesh installation, run

# pending-setups -a

Hint

The secret needed to run the above command is stored in file /var/lib/service-discover/password, which is accessible only by the root user.

Hint

In case of errors related to Carbonio Mesh token, please refer to section Token-related Error Messages.

Step 6: Create Main DB Role and Database for Carbonio CE

Carbonio CE relies on a number of databases to store and keep track of all the objects it needs to manage. The main database can be configured in two steps, but if you are running Carbonio CE on RHEL 8, please first configure Postgres according to the guidelines.

The first step is to create a role with administrative rights and an associated password.

# su - postgres -c "psql --command=\"CREATE ROLE carbonio_adm WITH LOGIN SUPERUSER encrypted password 'DB_ADM_PWD';\""

Remember to replace the password with a robust password of your choice and store it in a safe place (preferably using a password manager), as you need it in the remainder of the procedure, and you also might need them in the future. This password will be denoted as DB_ADM_PWD.

The second step is to create the database.

# su - postgres -c "psql --command=\"CREATE DATABASE carbonio_adm owner carbonio_adm;\""

Step 7: Bootstrap Carbonio Files Databases

The password DB_ADM_PWD created in the previous step for the carbonio_adm role in database is required in this step, in which we configure the database of Carbonio Files. First, we bootstrap the database.

# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm 127.0.0.1

Then restart the main mailbox process as the zextras user.

zextras$ zmcontrol stop
zextras$ zmcontrol start

Installation Complete

At this point installation is complete and you can start using Carbonio CE and access its graphic interface as explained in section Access to the Web Interface.

If you need to access the administration interface, you need to create a system user with administrative access, a task explained in Create System User below.

(Optional) Change Password for System User

In order to change the password used by the zextras@mail.example.com user for the Web access, log in to a shell terminal as the zextras user and execute these two commands. The first allows to switch to the zextras user, with the second you actually change the password.

# su - zextras
# carbonio prov setpassword zextras@mail.example.com newpassword

Make sure that newpassword meets good security criteria.

The zextras and zextras@mail.example.com users

There is a clear distinction between these two users, which are intended to execute different tasks:

zextras

This the unix account of the administrator and must be used to carry out administrative tasks from the command line.

zextras@mail.example.com

This is the default administrator user to be used to access the Admin UI and manage Carbonio CE from the web interface.

Carbonio CE Management and Troubleshooting

The carbonio service integrates seamlessly with the various system tools like systemctl and journalctl, therefore allowing quicker analysis of the situation and check for any problem should arise.

The syntax is the standard used by systemctl, hence you can use

# systemctl start|stop|status carbonio*

to start, stop or verify the status of all the carbonio units and

# journalctl -u carbonio*

to access the logs produced by all the units.

To check, start, or stop a single carbonio unit, you can receive a list of all Carbonio-related units (and their status) with the command below, then use only the unit that you would like to access.

# systemctl list-units "carbonio*"