Close menu

Installation on a single server

Installation on a single server

Each stage of the installation process on RHEL 8 or Ubuntu 20.04 is broken down into optional and preliminary setup procedures. Make sure you have access to the command line because it will be used to run commands during Carbonio CE’s installation and configuration

Following a successful installation, you may use a browser to view Carbonio CE’s GUI by following the instructions in Section view to the Web Interface.

Preliminary Tasks

The PostgreSQL database needs to be installed and configured before we can start the Carbonio CE installation.

First, install PostgreSQL:

# apt install postgresql-12

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

First, install PostgreSQL:

# apt install postgresql-12

To configure PostgreSQL, edit file /etc/postgresql/12/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
Step 1: Configuring the repository

Go to the following page and complete the form to add Carbonio CE’s repository:

https://www.zextras.com/carbonio-community-edition/#discoverproduct

You will get an email that includes:

  • the repository’s web address
  • the repository’s GPG key

To add this data to your system, follow the instructions in the email.

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

  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 we be informed about new RC packages?

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

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

  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 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 CE requires to run a few commands. 

We start by updating and upgrading the system.

Next, we install all packages needed for Carbonio CE.

If Carbonio CE services are running after successful package installation, use the following command

# systemctl status carbonio-*
Post-Installation tasks

Any service that is in failed status should be restarted. Most likely, one of Carbonio Monitoring’s exporters won’t start correctly, so you will have to restart it

# systemctl restart carbonio-prometheus-nginx-exporter.service
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: Carbonio Bootstrap CE

Utilise the following command to setup and run Carbonio CE after all packages have been installed.

# carbonio-bootstrap

Press Y to apply the configuration before completing the startup. Click Enter to continue, and the procedure will run until it is finished.

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

setup and configuration Mesh

The different Carbonio CE components will be configured and set up in the following phases.

Setup of Carbonio Mesh in Step 6

To enable connectivity between Carbonio CE and its components, Carbonio Mesh is necessary. Commands are used to interactively generate the configuration.

# service-discover setup-wizard

This instruction will:

  • the IP address and the netmask
  • In order to install, administer, and use the administrative GUI, you must have the Carbonio Mesh secret. For additional details, go to Section Carbonio Mesh Administration Interface.
  • MESH_SECRET will be used to refer to this password throughout the manual.

    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.

You can regenerate Carbonio Mesh Secret in the event that the password is forgotten or the credential file is damaged and rendered useless.

  • Keep the setup in the file cluster-credentials.tar.gpg at /etc/zextras/service-discover

Run to complete the installation of Carbonio Mesh.

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

Step 7: Create the Carbonio CE Main DB Role and Database

To store and keep track of all the items it needs to handle, Carbonio CE uses several databases. If you are running Carbonio CE on RHEL 8, please first configure Postgres in accordance with the instructions before configuring the primary database, which may be done in two phases.

Note

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

Making a role with administrative privileges and a related password is the first step.

# read -s -p "Password:" DB_ADM_PWD

You’ll need it for the rest of the process and may need it in the future, so make sure to update the password with a strong one of your choosing and keep it safely (ideally using a password manager). DB_ADM_PWD will be used to identify this password.

# unset $DB_ADM_PWD


# su - postgres -c "psql --command=\"CREATE ROLE carbonio_adm WITH LOGIN SUPERUSER encrypted password 'DB_ADM_PWD';\""

The database creation process is the next phase.
# su - postgres -c "psql --command=\"CREATE DATABASE carbonio_adm owner carbonio_adm;\""
Bootstrap Carbonio Files Databases in Step 8
In this stage, when we configure the database for Carbonio Files, we need the password DB_ADM_PWD that was established in the preceding phase for the carbonio_adm role. The database is bootstrapped first.
# PGPASSWORD=DB_ADM_PWD carbonio-files-db-bootstrap carbonio_adm 127.0.0.1
Then, as the zextras user, restart the primary mailbox process.
zextras$ zmcontrol stop
zextras$ zmcontrol start
 Installation Complete
 
Following the instructions in the section under “Access to the Web Interface,” Carbonio CE can now be used when the installation is complete.
 
The work of changing the password for the system user with administrative access is also strongly encouraged and is covered in the section Change Password of System User below.
Change the system user’s password
Enter these two commands while logged in as the zextras user to a shell terminal in order to modify the password that the zextras@mail.example.com user uses to access the Web. With the second, you can truly change the password whereas the first enables you to switch to the zextras user.
Make sure newpassword complies with sound security standards.
 
Users of zextras@mail.example.com and zextras
 
These two users may be distinguished clearly since they are meant to carry out various duties.
 
zextras
To do administrative actions via the command line, one must utilise the administrator’s unix account.
 
zextras@mail.example.com
This is the default administrator account that should be used to operate Carbonio CE via the web interface and access the Admin UI.
Management and troubleshooting for Arbonio CE
System tools like systemctl and journalctl, which the carbonio service smoothly connects with, make it possible to analyse the situation and look for potential issues more quickly.
 
Since the syntax is the same as that used by systemctl, you may use it to start, stop, or check the status of each Carbonio unit as well as to read the logs that each unit produces.
 
With the command below, you may get a list of all Carbonio-related units (and their state), then use only the unit you want to access to check, start, or stop it.