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, it is necessary to execute commands from the command line, so make sure you have access to it.

Warning

Single-Server installations in a production environment are not supported and are intended for demo or test purposes only.

When the installation process has successfully finished, you can access Carbonio'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 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.

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 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

Instructions for setting up Carbonio repository will be provided by Zextras Sales Department.

Repository and Channels

The following are important information concerning the packages repository Carbonio 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

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

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

RELEASE channel.
How will we be informed about new RC packages?

There will be no notification, because RC channel is updated continuously.
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.
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 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 requires to run a few commands.

We start by updating and upgrading the system.

Ubuntu

# apt clean &&apt update && apt upgrade

RHEL

# dnf clean all && dnf upgrade

Next, we install all packages needed for Carbonio.

Ubuntu

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

RHEL

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-user-management \
carbonio-files-ui carbonio-files \
carbonio-files-db \
carbonio-mta \
carbonio-appserver \
carbonio-mailbox-db \
carbonio-advanced carbonio-zal \
carbonio-chats-ui \
carbonio-docs-editor \
carbonio-docs-connector carbonio-docs-connector-db \
carbonio-admin-ui carbonio-admin-console-ui \
carbonio-admin-login-ui carbonio-preview

Post-Installation tasks

Step 4: Bootstrap Carbonio

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

# carbonio-bootstrap

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

Configuration and Setup tasks

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

Step 5: Setup Carbonio Mesh

Carbonio Mesh is required to allow communication between Carbonio 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

Carbonio 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 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 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 databases of Carbonio using a few commands. First, we bootstrap the databases.

Carbonio Advanced

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

Carbonio Files

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

Carbonio Docs

# PGPASSWORD=DB_ADM_PWD carbonio-docs-connector-db-bootstrap carbonio_adm 127.0.0.1

Then restart the main mailbox process as the zextras user.

zextras$ zmcontrol stop
zextras$ zmcontrol start

Step 8: Carbonio VideoServer and Video Recording

Carbonio VideoServer is Carbonio component that provides video-conferencing and video-recording functionalities to Carbonio Chats. Since it is not installed by default, you need to install it separately.

Ubuntu

# apt install carbonio-videoserver carbonio-videoserver-recorder

RHEL

Before starting the procedure, install Fedora’s epel-repository.

# yum -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm

Then, install the packages.

# dnf install carbonio-videoserver carbonio-videoserver-recorder

Note

During the installation, you will be asked for a command to be executed.

Once the package has been successfully installed, you will be asked for the public IP Address of Carbonio VideoServer: enter it, then execute the following commands to start the service.

# systemctl enable videoserver.service
# systemctl start  videoserver.service

To complete the installation, first become the zextras user.

# su - zextras

Execute the following command to configure video recording.

zextras$ carbonio chats video-server add VS_IP port 8188 servlet_port 8090 secret VIDEOSERVER_PWD

Here, port 8188 is the default port used by Carbonio VideoServer, while 8090 for recording. Change these values according to your needs or preferences, but take into account that the value of the servlet_port must match the one defined for Carbonio VideoServer in file /etc/carbonio/videoserver-recorder/recordingEnv.

Remember also to replace VS_IP with the public IP address of the Carbonio VideoServer.

Hint

In case you forget the password used for the video recording setup, (VIDEOSERVER_PWD), you can retrieve it using this command

# grep -i -e nat_1_1 -e api_secret /etc/janus/janus.jcfg

For information about Carbonio VideoServer, advances settings, and recording options, refer to Section Carbonio VideoServer.

Finally, enable Carbonio VideoServer at COS level, Video Recording, and the possibility for each user to record meetings.

zextras$ carbonio config set cos default teamChatEnabled true
zextras$ carbonio config set global teamVideoServerRecordingEnabled true
zextras$ carbonio config set global teamMeetingRecordingEnabled true

Note

In the commands above, the policy allows every user to record a meeting. It is however possible to enforce this policy at user or COS level, to allow only selected users or members of a COS to record meetings.

Final Steps: Complete Setup and Activate License

We are now on the last mile. To verify there is no dangling installation or configuration task, 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.

Finally, as the zextras user, activate Carbonio license, replacing TOKEN with your licence token.

# carbonio core activate-license TOKEN

Installation Complete

At this point installation is complete and you can start using Carbonio 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 from the web interface.

Carbonio 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*"

(END)