Operating System CentOS

How to Install Cerb 12 With Docker on Ubuntu 26.04

Deploy Cerb 12 with the project's Docker Compose files, Caddy and MySQL on Ubuntu 26.04, with notes for AlmaLinux 9.

Cerb is a web-based shared inbox and automation platform for support teams. By the end of this guide you will have Cerb 12 running behind Caddy with MySQL in Docker containers on Ubuntu 26.04 LTS, reachable over HTTPS at your own hostname. The same steps work on Ubuntu 24.04, and on AlmaLinux 9 or Rocky Linux 9 once Docker is installed. CentOS 7 reached end of life in June 2024; the RHEL 9 family replaces it.

Docker is used because it is the installation method the Cerb project recommends: its documentation advises against installing the components one by one on the host and treats its Docker files as the reference for anyone who does.

Requirements

  • A server with Ubuntu 26.04 LTS and a user with sudo rights.
  • A DNS record such as cerb.example.com pointing to the server, and ports 80 and 443 open to the internet (Caddy needs both to obtain a Let's Encrypt certificate).
  • A mailbox or mail service for Cerb to send and receive mail through; you connect it inside Cerb after installation.

Self-hosting Cerb is free with unlimited workers according to the project; a paid subscription raises how much background work runs concurrently.

Step 1: Install Docker and Git

On Ubuntu 26.04 and 24.04, Docker Engine and the Compose plugin are in the distribution's repositories:

sudo apt update
sudo apt install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker

On AlmaLinux 9 or Rocky Linux 9, use Docker's repository. Docker documents these commands for CentOS Stream 9; they are commonly used unchanged on the other RHEL 9 rebuilds:

sudo dnf -y install dnf-plugins-core git
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo
sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker

Step 2: Get the Cerb Docker files

The cerb-docker repository contains ready-made Compose projects. Use the Caddy and MySQL one:

cd ~
git clone https://github.com/cerb/cerb-docker.git
cd cerb-docker/cerb-caddy-mysql
cp .env-template .env

Do not skip the last command. Without a .env file the installer is disabled and unreachable.

Step 3: Configure the environment

nano .env

Change at least these values:

CERB_HOSTNAME=cerb.example.com
CERB_SERVICE_TOKEN=replace-with-a-long-random-string
MYSQL_PASSWORD=replace-with-a-strong-password

The published defaults for the token and the password are public, so replace both before the first start. You can generate random values with openssl rand -hex 24. Decide on MYSQL_DATABASE and MYSQL_USER now as well; changing them after the first start means migrating the database. Leave CERB_INSTALL=yes in place for the moment.

VariablePurpose
CERB_VERSIONImage tag of the Cerb release to run (12.0 in the template)
CERB_PORT, CERB_PORT_SSLHost ports published by Caddy (80 and 443)
CERB_INSTALLyes enables the /install/ page
CERB_SERVICE_TOKENBearer token that may call /cron and /update without a login
MYSQL_VERSIONMySQL image tag (8.4 in the template)

Step 4: Enable HTTPS

The default Caddyfile serves plain HTTP for local testing. Switch to the HTTPS example:

cp caddy/Caddyfile.ssl.example caddy/Caddyfile
nano caddy/Caddyfile

Near the top of the file, comment out the line auto_https disable_redirects by putting a # in front of it, as the comment in the file advises for production. With a publicly resolvable hostname Caddy requests a Let's Encrypt certificate on its own.

Step 5: Start the stack

sudo docker compose up -d
sudo docker compose ps

Four services start: caddy (the only one with published ports), cerb for page loads, cerb-background for queued and scheduled work, and mysql. Uploaded files and the database live in the Docker volumes storage and db.

Step 6: Run the guided installer

Open https://cerb.example.com/ in a browser. Cerb redirects to the guided installer, which checks the environment, creates the database tables and takes you through the initial setup, including the first administrator account. If the first request returns an error, wait a few seconds: MySQL is still initializing.

When the installer has finished, disable it. Edit .env, put a # in front of CERB_INSTALL=yes, and apply the change:

sudo docker compose up -d

Leaving the installer enabled exposes /install/ and details of your environment to anyone.

Step 7: Schedule background jobs

Cerb fetches mail and runs maintenance when its /cron URL is requested. The service token authorizes that request. Add a cron job for your user:

crontab -e
* * * * * curl -fsS -o /dev/null -H "Authorization: Bearer replace-with-a-long-random-string" https://cerb.example.com/cron

Use the same token you set in .env.

Maintenance

Follow the logs of all containers or a single one:

sudo docker compose logs -f
sudo docker compose logs -f cerb

Back up the database with the credentials already present inside the MySQL container:

sudo docker compose exec mysql sh -c 'mysqldump --no-tablespaces -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' > cerb-$(date +%F).sql

Back up the storage volume too; it holds attachments. To move to a newer Cerb release, read the upgrade notes for that release, take a backup, change CERB_VERSION in .env and recreate the containers:

sudo docker compose pull
sudo docker compose up -d

Never run docker compose down --volumes on a system you want to keep: it deletes the database and all stored files.

Frequently asked questions

Can I install Cerb without Docker?

Yes, but the project discourages it. A manual installation needs PHP 8.5 or later with the curl, dom, gd, json, mailparse, mbstring, mysqli, openssl, pcre, session, simplexml, spl, yaml and xml extensions, plus MySQL 8.0 or later or MariaDB 10.5 or later, and a web server (Caddy or Nginx with PHP-FPM are recommended). The source is cloned from the cerb/cerb-release repository on GitHub.

Is this Compose project suitable for production?

Its README describes it as a template for evaluation, development and testing. For production, at minimum change the default secrets, disable the installer, enable HTTPS, take regular backups, and consider an external managed database. The cerb containers listen on port 9000 (FastCGI), which must never be published to the internet.

How do I add capacity for background work?

Run more background containers rather than enlarging one: sudo docker compose up -d --scale cerb-background=3. Each background worker uses roughly 50–60 MB of memory and one database connection.

Port 443 is already in use on my server. What now?

Change CERB_PORT and CERB_PORT_SSL in .env. Automatic Let's Encrypt certificates still require the public ports 80 and 443 to reach Caddy, so on a shared host put Cerb behind your existing reverse proxy instead.

Share story:

Continue reading other guides on How VPS.