Ctrl+K
What do you think about our new Documentation Layout? Take the survey
Back to Documentation Hub

Single-Server Installation

Single-Server Installation#

Automatic Script-based Installation#

The installation on supported Ubuntu (22.04 and 20.04), or RHEL 8 distributions 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 22.04 and 20.04 /scripts/install_carbonio_ce_singleserver_ubuntu.sh

Script for RHEL 8 /scripts/install_carbonio_ce_singleserver_rhel.sh

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 System Troubleshooting, in which you can find helpful commands.

Preliminary Task#

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

First, install PostgreSQL:

# apt install postgresql-16

To configure PostgreSQL, edit file /etc/postgresql/16/main/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

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 configure PostgreSQL, edit file /var/lib/pgsql/16/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-16

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. 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 local IP of the Node.

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

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 (Step 9) 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: 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 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 Preliminary Tasks.

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

Step 9: 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 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
Carbonio Workstream Collaboration
# PGPASSWORD=$DB_ADM_PWD carbonio-ws-collaboration-db-bootstrap
  carbonio_adm 127.0.0.1
Carbonio Workstream Collaboration Dispatcher
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-db-bootstrap \
  carbonio_adm 127.0.0.1
Carbonio Workstream Collaboration 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 10: Enable Workstream Collaboration UI BETA#

The Carbonio Workstream Collaboration 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. Carbonio Workstream Collaboration

    # systemctl restart carbonio-ws-collaboration

  4. In case you also installed Carbonio VideoServer

    # systemctl restart carbonio-videoserver
Check status of Carbonio Workstream Collaboration

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
Contents