Manual Installation

Manual Installation#

The manual installation is organised in steps. 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 Systemd Usage Guide For Administrators, 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

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

# 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

Update Package List and Install Postgres

# apt update
# apt install postgresql-16

# apt update
# apt install postgresql-16

To make sure that Postgresql 16 is installed, run commands

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

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

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.

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

Complete the Postgres configuration 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 Carbonio CE is installed (e.g., 172.16.0.0/24) to prevent unwanted accesses.

Step 1: Repository Configuration#

In order to configure Carbonio CE’s repository, you need to some files with the necessary information.

It you install Carbonio CE on Ubuntu, you also need to import the GPG key used for signing the packages and verify them.

Configure Carbonio CE Repository

You need to create file /etc/apt/sources.list.d/zextras.list and add the following content to it:

deb [arch=amd64 signed-by=/usr/share/keyrings/zextras.gpg] https://repo.zextras.io/release/ubuntu jammy main

Hint

Make sure the above content is correctly saved on the same line

You need to create file /etc/apt/sources.list.d/zextras.list and add the following content to it:

deb [arch=amd64 signed-by=/usr/share/keyrings/zextras.gpg] https://repo.zextras.io/release/ubuntu noble main

Hint

Make sure the above content is correctly saved on the same line

You need to create file /etc/yum.repos.d/zextras.repo and add the following content to it:

[zextras]
name=zextras
baseurl=https://repo.zextras.io/release/rhel8
enabled=1
repo_gpgcheck=1
gpgcheck=0
gpgkey=https://repo.zextras.io/repomd.xml.key

You need to create file /etc/yum.repos.d/zextras.repo and add the following content to it:

[zextras]
name=zextras
baseurl=https://repo.zextras.io/release/rhel9
enabled=1
repo_gpgcheck=1
gpgcheck=0
gpgkey=https://repo.zextras.io/repomd.xml.key
Import GPG Key

This step is required only on Ubuntu systems (Ubuntu 22.04 and Ubuntu 24.04).

Download and save the GPG key

# wget -O- "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x5dc7680bc4378c471a7fa80f52fd40243e584a21" | gpg --dearmor | sudo tee /usr/share/keyrings/zextras.gpg > /dev/null

Assign correct access permissions to the key

# chmod 644 /usr/share/keyrings/zextras.gpg

Download and save the GPG key

# wget -O- "https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x5dc7680bc4378c471a7fa80f52fd40243e584a21" | gpg --dearmor | sudo tee /usr/share/keyrings/zextras.gpg > /dev/null

Assign correct access permissions to the key

# chmod 644 /usr/share/keyrings/zextras.gpg

This step is not needed.

This step is not needed.

Configure RHEL-only Repositories

This step is not needed.

This step is not needed.

You need to add the EPEL repository and enable the BaseOS, Appstream, and CodeReady repositories.

# dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
# subscription-manager repos --enable=rhel-8-for-x86_64-baseos-rpms
# subscription-manager repos --enable=rhel-8-for-x86_64-appstream-rpms
# subscription-manager repos --enable=codeready-builder-for-rhel-8-x86_64-rpms

You need to add the EPEL repository and enable the BaseOS, Appstream, and CodeReady repositories.

# dnf -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
# subscription-manager repos --enable=rhel-9-for-x86_64-baseos-rpms
# subscription-manager repos --enable=rhel-9-for-x86_64-appstream-rpms
# subscription-manager repos --enable=codeready-builder-for-rhel-9-x86_64-rpms

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.

Note

Replace the values srv1.example.com and 172.16.0.10 with values suitable for your setup.

First, set the hostname

# hostnamectl set-hostname srv1.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 srv1.example.com srv1" > /etc/hosts

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

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

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-editor carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher-ce \
carbonio-message-dispatcher-db carbonio-ws-collaboration-ce \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-videoserver-ce carbonio-catalog

# 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-editor carbonio-prometheus \
carbonio-message-broker carbonio-message-dispatcher-ce \
carbonio-message-dispatcher-db carbonio-ws-collaboration-ce \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-videoserver-ce carbonio-catalog

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-prometheus \
carbonio-message-broker carbonio-message-dispatcher-ce \
carbonio-message-dispatcher-db \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-ws-collaboration-ce carbonio-videoserver-ce \
carbonio-catalog

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-prometheus \
carbonio-message-broker carbonio-message-dispatcher-ce \
carbonio-message-dispatcher-db \
carbonio-ws-collaboration-db carbonio-ws-collaboration-ui \
carbonio-ws-collaboration-ce carbonio-videoserver-ce \
carbonio-catalog

Package installation completed

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#

Starting from 25.3 release, the /etc/janus/janus.jcfg configuration file will be updated automatically to include the Carbonio VideoServer public IP address (i.e., the one that will accept incoming connections to the Carbonio VideoServer) using a curl call.

Different IPs for outgoing and incoming traffic

This might be incorrect in case the Node setup has different IP addresses for incoming and outgoing traffic, for example:

  • the incoming traffic to the Carbonio VideoServer node is routed using IP address 203.0.113.102

  • the outgoing traffic from the Node to the Internet is routed through IP address 203.0.113.105

In cases like this one, the curl call would return the latter IP (i.e., 105), but the actual IP in the configuration file should be the former (102).

Therefore, after the installation, make sure that the correct public IP address is present in the file: the line containing the nat_1_1_mapping variable should be:

nat_1_1_mapping = "203.0.113.102"

VideoServer not exposed to the Internet (LAN-only deployments)

In some deployment scenarios, the VideoServer is not publicly exposed, and video meetings take place only between peers within the same local network (LAN).

In these cases, the automatically configured public IP address is not suitable and may cause connectivity issues.

Required action

When the VideoServer is not exposed externally, the nat_1_1_mapping parameter must be manually set to the private IP address of the host where the VideoServer component is installed.

For example:

nat_1_1_mapping = "192.168.1.50"

Apply changes after updating janus.jcfg

After each change to the nat_1_1_mapping parameter in the /etc/janus/janus.jcfg configuration file, restart the VideoServer service to apply the new IP address.

Finally, enable and start the service with the commands

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

Step 6: Bootstrap Carbonio CE#

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.

    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 Carbonio Mesh Credentials.

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

The command will ask for the password stored in the /var/lib/service-discover/password on the Directory Leader Node (i.e., the node on which the Mesh server is installed).

Step 8: Bootstrap Carbonio Files Databases#

Mailbox
# 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 Tasks
# PGPASSWORD=$DB_ADM_PWD carbonio-tasks-db-bootstrap carbonio_adm 127.0.0.1
Chats
# PGPASSWORD=$DB_ADM_PWD carbonio-ws-collaboration-db-bootstrap  carbonio_adm 127.0.0.1
Message Dispatcher
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-db-bootstrap carbonio_adm 127.0.0.1
Chats migration
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-migration \
  carbonio_adm 127.0.0.1

Restart the service

# systemctl restart carbonio-message-dispatcher

Installation Completed

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 also need to set the password of the Admin, a task explained in section Set or Change Password.

Contents