Single-Server Installation#

Automatic Script-based Installation#

The installation on supported Ubuntu (22.04 and 20.04), or RHEL 8 distributions (support for RHEL 9 is still in BETA) can be carried out by downloading, editing, and running a dedicated bash script on the Server on which you want to install Carbonio CE.

The script will recognise the version of the OS and execute the steps that are described in Manual Installation.

To correctly run the script, please follow these advices

  • Make sure you have already run the script you received after registering Carbonio CE, which sets up the Carbonio CE repositories

  • Review the script and the tasks it performs before you run it

  • Run the script as the root user on the server on which you want to install Carbonio CE

  • When the script successfully completes, it will print on the screen the password of the Carbonio Mesh and PostgreSQL services that you will need some important Administration task. Make sure that you store them in a safe place!

  • For RHEL, the RHEL Specific Requirements are automatically satisfied by the script

Script for Ubuntu 20.04 and 22.04 /scripts/install_carbonio_ce_singleserver_ubuntu.sh

Script for Ubuntu 22.04 and 20.04 /scripts/install_carbonio_ce_singleserver_ubuntu.sh

Warning

The script does not yet support RHEL 9 BETA installations, you need to install manually, see next Section (Manual Installation).

Manual Installation#

The manual installation 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.

In case you experience some issues during the installation, please refer to Section CLI Commands, in which you can find helpful commands.

Preliminary Task#

Before starting the Carbonio CE installation, we need to install and configure the PostgreSQL 16 database.

Repository Setup

# sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
# sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

# wget -O- "https://www.postgresql.org/media/keys/ACCC4CF8.asc" | \
gpg --dearmor | sudo tee /usr/share/keyrings/postgres.gpg > \
/dev/null

# chmod 644 /usr/share/keyrings/postgres.gpg
# sed -i 's/deb/deb [signed-by=\/usr\/share\/keyrings\/postgres.gpg] /' /etc/apt/sources.list.d/pgdg.list
# dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-8-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# dnf -y install https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
# apt update
# apt install postgresql-16 service-discover-agent
# apt update
# apt install postgresql-16 service-discover-agent

To make sure that Postgresql 16 is installed, run commands

# dnf -qy module disable postgresql
# dnf -y install postgresql16 postgresql16-server service-discover-agent

Once installed, initialise and enable the database

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

To make sure that Postgresql 16 is installed, run commands

# dnf -qy module disable postgresql
# dnf -y install postgresql16 postgresql16-server service-discover-agent

Once installed, initialise and enable the database

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

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 few steps.

Note

If you are running Carbonio CE on RHEL 8, make sure you installed and configured PostgreSQL 16 according to the instruction in section Preliminaries.

We start by defining a robust password for PostgreSQL’s administrative user.

# read -s -p "Insert Password:" DB_ADM_PWD

When prompted, enter a password of your choice: it will be stored in a variable denoted $DB_ADM_PWD that can be used throughout the whole procedure. It is important to notice that the password is accessible to the user (root) in the current terminal only. No one else can access it and it will be deleted upon logging out.

# 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;\""

You can manually delete the variable–and the password it stores– at any moment with the command below, but remember that you need it in the next step.

# unset DB_ADM_PWD

Finally, allow the other nodes to access the databases that will be stored on this node by running these commands.

# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# echo "host    all             all             0.0.0.0/0            md5" >> /etc/postgresql/16/main/pg_hba.conf
# systemctl restart postgresql
# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# echo "host    all             all             0.0.0.0/0            md5" >> /etc/postgresql/16/main/pg_hba.conf
# systemctl restart postgresql
# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# echo "host    all             all             0.0.0.0/0            md5" >> /var/lib/pgsql/16/data/pg_hba.conf
# systemctl restart postgresql-16
# su - postgres -c "psql --command=\"ALTER SYSTEM SET listen_addresses TO '*';\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET max_connections = 500;\""
# su - postgres -c "psql --command=\"ALTER SYSTEM SET shared_buffers = 5000;\""
# echo "host    all             all             0.0.0.0/0            md5" >> /var/lib/pgsql/16/data/pg_hba.conf
# systemctl restart postgresql-16

Hint

You may replace the 0.0.0.0/0 network with the one within the cluster is installed (e.g., 172.16.0.0/24) to prevent unwanted accesses.

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 bugs, 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 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 I be informed about new RC packages?

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

  4. How will I 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. Therefore, it is necessary to take care of properly configuring the /etc/hosts file, otherwise the services will not be able to bind to the correct address, leading to a disruption in Carbonio CE's functionality.

To configure the file and the hostname, execute these two commands. First, set the hostname

# hostnamectl set-hostname mta1.example.com

then replace the content of the /etc/hosts file with IP and hostname.

# echo -e  "127.0.0.1 localhost\n172.16.0.10 mta1.example.com mta1" > /etc/hosts

Hint

Replace 172.16.0.10 with the local IP of the Node.

You can also simply get the current IP and hostname and save it in the file /etc/hosts/:

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

In case you need to enable IPv6 on Carbonio CE, make sure that the /etc/hosts/ file contains the following line:

::1     ip6-localhost ip6-loopback

Warning

The above line must not contain references to localhost, as this would result in disruptions.

::1     ip6-localhost ip6-loopback CORRECT

::1     ip6-localhost ip6-loopback localhost WRONG

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
# apt update && apt upgrade
# dnf 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-mailbox-db \
carbonio-appserver carbonio-user-management \
carbonio-files-ce carbonio-files-public-folder-ui \
carbonio-files-db carbonio-tasks-ce carbonio-tasks-db \
carbonio-tasks-ui carbonio-storages-ce carbonio-preview-ce \
carbonio-docs-connector-ce carbonio-docs-connector-db \
carbonio-docs-editor carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher \
carbonio-message-dispatcher-db carbonio-ws-collaboration-ce \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-videoserver-ce
# apt install service-discover-server \
carbonio-directory-server carbonio-proxy carbonio-webui \
carbonio-files-ui carbonio-mta carbonio-mailbox-db \
carbonio-appserver carbonio-user-management \
carbonio-files-ce carbonio-files-public-folder-ui \
carbonio-files-db carbonio-tasks-ce carbonio-tasks-db \
carbonio-tasks-ui carbonio-storages-ce carbonio-preview-ce \
carbonio-docs-connector-ce carbonio-docs-connector-db \
carbonio-docs-editor carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher \
carbonio-message-dispatcher-db carbonio-ws-collaboration-ce \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-videoserver-ce

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-mailbox-db carbonio-appserver \
carbonio-user-management carbonio-preview-ce \
carbonio-files-ce carbonio-files-public-folder-ui \
carbonio-files-db carbonio-tasks-ce carbonio-tasks-db
carbonio-tasks-ui carbonio-storages-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-docs-connector-db carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher \
carbonio-docs-connector-dbcarbonio-message-dispatcher-db \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-ws-collaboration-ce carbonio-videoserver-ce

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-mailbox-db carbonio-appserver \
carbonio-user-management carbonio-preview-ce \
carbonio-files-ce carbonio-files-public-folder-ui \
carbonio-files-db carbonio-tasks-ce carbonio-tasks-db
carbonio-tasks-ui carbonio-storages-ce \
carbonio-docs-connector-ce carbonio-docs-editor \
carbonio-docs-connector-db carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher \
carbonio-docs-connector-dbcarbonio-message-dispatcher-db \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-ws-collaboration-ce carbonio-videoserver-ce

After the successful package installation, you can check that all Carbonio CE services are running, by using

# systemctl status carbonio-*

If any service is in failed status, restart it. Some of he Carbonio Monitoring exporters may not correctly start, because the bootstrap of the databases (see section Preliminary Task) must be executed in advance. After that step, if any of the services is not in running state, you will need to manually start it by running a command like the following, replacing carbonio-prometheus-nginx-exporter.service with the service that is not running.

# systemctl restart carbonio-prometheus-nginx-exporter.service

Post-Installation tasks

Step 4: Configure Firewall#

You need to open only the ports that must be accessible form the Internet, i.e., those that are listed in the Requirement’s Firewall Ports section.

Step 5: Configure Carbonio VideoServer#

After the package installation, make sure that the Carbonio VideoServer public IP address (i.e., the one that will accept incoming connections to the Carbonio VideoServer) is present in the configuration file /etc/janus/janus.jcfg and add it if missing: find the variable nat_1_1_mapping and add it, for example:

nat_1_1_mapping = "93.184.216.34"

Finally, enable and start the service with the commands

# systemctl enable carbonio-videoserver.service
# systemctl start  carbonio-videoserver.service

Step 6: 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 7: 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 reset them using the procedure detailed in section Reset Carbonio Mesh Credentials on Single-Server.

  • 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 is stored in file /var/lib/service-discover/password, which is accessible only by the root user.

Step 8: Bootstrap Carbonio Files Databases#

The password DB_ADM_PWD created for the carbonio_adm role is required in this step, in which we configure the databases required by Carbonio CE, by running the following commands.

Carbonio Files
# PGPASSWORD=$DB_ADM_PWD carbonio-files-db-bootstrap \
  carbonio_adm 127.0.0.1
Carbonio Tasks
# PGPASSWORD=$DB_ADM_PWD carbonio-tasks-db-bootstrap \
  carbonio_adm 127.0.0.1
Work Stream Collaboration (Chats)
# PGPASSWORD=$DB_ADM_PWD carbonio-ws-collaboration-db-bootstrap \
  carbonio_adm 127.0.0.1
Work Stream Collaboration (Chats) Dispatcher
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-db-bootstrap \
  carbonio_adm 127.0.0.1
Work Stream Collaboration (Chats) migration
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-migration \
  carbonio_adm 127.78.0.10 20000

When you’re done, 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.

You are also strongly advised to change the password of the Global Admin, a task explained in section Manage Global Administrators.

Step 9: Enable Work Stream Collaboration (Chats) UI#

The Work Stream Collaboration (Chats) role is disabled by default, you can enable it either from the Carbonio Admin Panel or from the command line by running as the zextras user the command

zextras$ carbonio prov mc default carbonioFeatureChatsEnabled TRUE

This command enables the chat for the default COS, but you can enable it only on selected COSes.

Restart the following services in the given order

  1. Message broker

    # systemctl restart carbonio-message-broker
    
  2. Message dispatcher

    # systemctl restart carbonio-message-dispatcher
    
  3. Work Stream Collaboration (Chats)

    # systemctl restart carbonio-ws-collaboration
    
  4. In case you also installed Carbonio VideoServer

    # systemctl restart carbonio-videoserver
    
Check status of Work Stream Collaboration (Chats)

After the installation, you can check the status of and all its dependencies by running command

# curl -v http://127.78.0.4:10000/health | jq