• Requirements
  • Browser requirements
  • Server requirements
• Log in to your server
• Download the source code from GitHub
• Set permissions
• Create the database
• Run the guided installer
  • Step 1: Requirements Check
  • Step 2: License
  • Step 3: Database Setup
  • Step 4: Save Configuration File
  • Step 5: Database Initialization
  • Step 6: General Settings
  • Step 7: Outgoing Mail
  • Step 8: Admin Account
  • Step 9: Testing Mode
  • Step 10: Security
  • Step 11: Finished
• References

Requirements

Browser requirements

• An Internet or intranet connection to the server (e.g. Ethernet, Wi-Fi, mobile data)
• The latest version of any of these modern HTML5 web browsers, with Javascript enabled:
  • Mozilla Firefox
  • Apple Safari
  • Brave
  • Opera
  • Google Chrome
  • Microsoft Edge
  • (Internet Explorer is no longer supported)

Server requirements

• Any of these 64-bit operating systems:
  • Linux (recommended, using Ubuntu 23.10)
  • BSD
  • macOS
  • Windows
• Any of these webserver applications:
  • Nginx (recommended, using PHP-FPM)
  • Apache
  • lighttpd
  • Microsoft Internet Information Server (IIS)
  • Built-in PHP webserver (for development and evaluation)
• PHP 8.2 (64-bit) or later
  • With the following extensions enabled:
    • curl
    • dom
    • gd
    • json
    • mailparse
    • mbstring
    • mysqli
    • openssl
    • pcre
    • session
    • simplexml
    • spl
    • yaml
    • xml
    • tidy (recommended)
    • gmp (recommended)
    • memcached (optional)
    • redis (optional)
  • With these php.ini settings:
    • file_uploads = On
    • memory_limit = 128M (or higher)
    • upload_max_filesize = 32M (or higher)
    • post_max_size = 32M (or higher)
• Any of these database servers:
  • MySQL 8.0 or later
  • MariaDB 10.5 or later
  • Amazon Aurora

Log in to your server

The following general instructions assume that you have console access to a Linux-based server that meets the above requirements. You should already have a webserver, database, and PHP installed before proceeding.

You can follow one of these guides to set up a new server:

• Installing Cerb on Ubuntu 23.10 LTS with Nginx and PHP-FPM

Download the source code from GitHub

Navigate to your website’s document directory on the filesystem. The directory will usually be named something like htdocs, httpdocs, public_html, or www.

cd /path/to/example.com/httpdocs

When deploying Cerb on a production server you should use Git to manage the project files. This provides many useful capabilities:

• Quickly upgrade by just fetching files that have changed since your last update.
• See the local changes that you have made to any project files.
• Easily reset files back to their default condition.
• See what changes would occur before performing an upgrade.
• Continuously merge your local changes with our future updates.

You won’t need to download the entire project again after your initial installation. You also won’t have to hassle with copying your framework.config.php configuration file or storage directory when upgrading, or repeating any of your custom modifications to the source code.

You can download Cerb into a specific directory with a single command:

git clone git://github.com/cerb/cerb-release.git cerb

You would access Cerb at a URL with a base path like https://example.com/cerb. You can change the last argument above to whatever path you want: support, helpdesk, etc.

To download Cerb into the root of your domain instead, use:

git clone git://github.com/cerb/cerb-release.git .

This results in a URL without a base path, like https://support.example.com/

Set permissions

Next, we need to make sure that Cerb’s files are owned by the webserver’s user and group. The default user and group are both www-data when using Apache or Nginx on Ubuntu. If you’re using something different, you should consult your configuration for the proper values.

You only need to enable write access to the webserver in two locations:

• framework.config.php This is your configuration file.
• storage/ This is where any data unique to your installation is stored: third-party plugins, attachments, temporary files, caches, etc.

Give ownership of all the files to the webserver daemon using chown, and make the two locations above writable using chmod:

cd cerb
chown -R www-data:www-data .
chmod -R u+w framework.config.php storage

You must use your own user and group for www-data in the example above.

Create the database

Create a new MySQL database using the console or your favorite GUI tool.

From the MySQL console, you can issue the following SQL statements:

CREATE DATABASE cerb CHARACTER SET utf8;

CREATE USER cerb@localhost IDENTIFIED BY 'secret_password';

GRANT ALL PRIVILEGES ON cerb.* TO cerb@localhost;

Substitute your own database name and login in place of cerb, and replace secret_password with something that’s actually a secret. If you’re connecting to a remote database, change @localhost to the network address of the webserver where you’ll be connecting from.

If you’re concerned about granting ALL PRIVILEGES, the minimum required privileges for the database user are: SELECT, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, INDEX, CREATE TEMPORARY TABLES.

Run the guided installer

Cerb has a guided installer that verifies your requirements, initializes the database, and walks you through the initial configuration of the software.

To start the installer, open your browser to the location where you downloaded Cerb. For instance, https://example.com/cerb or https://support.example.com/.

Step 1: Requirements Check

The first step of the installer checks if your server meets the requirements for installing Cerb. Correct any problems before proceeding, and then click the Next Step button.

Step 2: License

Review the software license agreement and then click the I Accept button.

Step 3: Database Setup

Driver

Leave this at the default of MySQLi (the MySQL Improved extension).

Cerb currently only supports MySQL¹ databases. You can also use one of the MySQL-based forks², like Amazon Aurora, MariaDB, Percona, or WebScaleSQL. We recommend MySQL or Amazon Aurora, as they receive the most testing.

Engine

MySQL supports many storage engines³ that offer different functionality, strengths, and trade-offs. Of those, Cerb is well-tested with the two most common:

• InnoDB: This is the default and recommended storage engine in recent versions of MySQL. It is transactional and designed to recover gracefully from unexpected interruptions. It implements row-based locking on writes, which reduces resource contention at scale in high-volume environments. It has slightly higher overhead than MyISAM due to transactions, durability, and indexing. It may require more resources, and more experience to maintain and tune performance.

• MyISAM: This is the legacy storage engine in MySQL, and it is no longer under active development. It’s simpler to configure and maintain than InnoDB, and has slightly less overhead for some workloads (due to being non-transactional), but it risks data loss and corruption when the server is unexpectedly interrupted. It also implements table-based locking on writes, which generally doesn’t scale well and may lead to resource contention in high volume environments.

In general, we recommend that you use InnoDB. If you’re in an environment that only supports MyISAM, or you just feel more comfortable with it, then go ahead and use it.

This isn’t a life-or-death decision. You can easily switch between storage engines at any time (and even use different storage engines for each table).

Host

This is the IP or hostname of your MySQL server.

If MySQL is installed on the same server as your web server, this value is usually localhost.

Database Name

The name of the database on the MySQL server that you created earlier with the CREATE DATABASE statement.

Username

The username that you created earlier with the GRANT ALL PRIVILEGES ... TO <user>@host statement.

Password

The password that you created earlier with the GRANT ALL PRIVILEGES ... IDENTIFIED BY '<password>' statement.

Test Settings

Once you’ve entered your database connection details, click the Test Settings button to verify them.

Step 4: Save Configuration File

If the web server has write access to the framework.config.php file then it will automatically handle this for you and skip to the next step.

If it can’t write the file, it will generate the file for you to manually copy and paste.

Step 5: Database Initialization

If successful, the installer will create your initial database structure. This may take a while because the database is created by incrementally running the updates from each previous version. Don’t worry if it doesn’t look like anything is happening right away.

Step 6: General Settings

Browser Title

This is the page title that shows up by default on browser tabs and in URL bookmarks.

Default Sender

This establishes your first shared outgoing email address. You’ll probably want to use something like support@example.com (where example.com is your own domain name).

You can also configure a personalized name for the email address, such as your organization name.

Once you’re done, click the Continue button.

Step 7: Outgoing Mail

This step configures your first outgoing mail transport. Once you become familiar with Cerb, you can configure several outgoing mail transports for fail-over, branding, etc.

Mail Transport Type

When you intend to deliver real email to your contacts, you’ll be using an SMTP⁴ transport.

If you use a mail delivery service like Google Apps⁵ or Mailgun⁶, these settings will have been provided to you.

If this is going to be a development or evaluation instance, you can select None to discard all outgoing mail without delivering it. You won’t need to enter any other details with this option.

Host

This is the IP or hostname of your SMTP server.

For Google Apps, you would use smtp.gmail.com.

If you want to use a local mail server (like Postfix) that is installed on the same server as Cerb, you can usually enter localhost here.

Port

This is the port where your SMTP server accepts new mail for relay.

The legacy port is 25, although this is now intended for mail delivery and not relaying.

Generally, you’ll use port 465 or 587, depending on your configuration.

With Google Apps, 465 is used for SSL and 587 for TLS.

Authentication User

This is your username when SMTP Authentication is required.

With Google Apps (and many other providers), it’s your full Gmail or Google Apps email address.

Authentication Password

This is the password established by your SMTP provider.

Encryption

It is highly recommended that you enable encryption if you use a remote SMTP server. Cerb supports both TLS⁷ and SSL⁸ encryption, and your selection will depend on the configuration of your email provider. Given recent SSL vulnerabilities, TLS is considered to be more secure.

As mentioned in the port configuration above, Google Apps requires you to pair the right encryption method to the corresponding port. With Google Apps, we recommend port 587 for the port and TLS for encryption.

Step 8: Admin Account

In this step you’ll create the administrator account that you use to log in.

Name

This is simply your first and last name (given and surname).

Email Address

Your personal email address. This is how you will authenticate during logins, and it’s where your notifications and account recovery details will be sent. For that reason, this should not be an email address managed by Cerb.

This will likely be something like you@company.com or you@gmail.com.

Password

It is recommended that you choose a strong password here that you don’t use anywhere else. It should be fairly long, contain a mix of alphanumeric characters and symbols, in both upper and lower cases.

We highly recommend using a password manager like 1Password⁹ to maintain strong password security practices. You can also enable two-factor authentication for even stronger security.

Timezone

Cerb will use your timezone setting to display and interpret dates using your local timezone. The installer attempts to automatically detect this for you, but you can adjust it as necessary.

Step 9: Testing Mode

Without a license, Cerb operates in testing mode. This allows full functionality with a single seat.

You can install a purchased license in Setup » Configure » License.

Click the Continue button.

Step 10: Security

Review the security recommendations.

Step 11: Finished

That’s it! You’re ready to start using Cerb.

Click the Log in and get started link.

References