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 CEWhen 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
Script for RHEL 8
/scripts/install_carbonio_ce_singleserver_rhel.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.
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
-
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 I be informed about new RC packages?
There will be no notification, because RC channel is updated continuously.
-
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.
-
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)"
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.
# PGPASSWORD=$DB_ADM_PWD carbonio-files-db-bootstrap \
carbonio_adm 127.0.0.1
# PGPASSWORD=$DB_ADM_PWD carbonio-tasks-db-bootstrap \
carbonio_adm 127.0.0.1
# PGPASSWORD=$DB_ADM_PWD carbonio-ws-collaboration-db-bootstrap \
carbonio_adm 127.0.0.1
# PGPASSWORD=$DB_ADM_PWD carbonio-message-dispatcher-db-bootstrap \
carbonio_adm 127.0.0.1
# 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
-
Message broker
# systemctl restart carbonio-message-broker
-
Message dispatcher
# systemctl restart carbonio-message-dispatcher
-
Work Stream Collaboration (Chats)
# systemctl restart carbonio-ws-collaboration
-
In case you also installed Carbonio VideoServer
# systemctl restart carbonio-videoserver
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