Install OTOBO on CentOS with Docker Compose

This guide describes the full installation of OTOBO on CentOS using Docker and Docker Compose. The official otobo-docker stack bundles every required service (web server, database, Elasticsearch, Redis and optionally Nginx for HTTPS), so you can have OTOBO up and running within minutes.

Supported CentOS versions

• CentOS Stream 8
• CentOS Stream 9

[!NOTE] CentOS Linux 8 has reached end of life. For production systems we recommend CentOS Stream 9, a compatible distribution such as AlmaLinux/Rocky Linux, or RHEL.

System requirements

Component	Minimum	Recommended (production)
CPU	2 cores	4+ cores
RAM	4 GB	8 GB or more
Disk	20 GB free	40 GB+ (SSD)
Docker	19.03.13	latest version
Docker Compose	v2	latest version
Git	2.17	latest version

[!NOTE] Elasticsearch is part of the stack and requires a fair amount of memory. For production environments, plan for at least 8 GB of RAM.

Step 1: Install Docker, Docker Compose and Git

On CentOS, Docker is installed from the official Docker CE repository. First set up the repository:

sudo dnf install -y dnf-plugins-core git
sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

Then install Docker Engine, the CLI and the Compose plugin:

sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

Enable and start the Docker service so it launches automatically on boot:

sudo systemctl enable --now docker

Optional: add your user to the docker group so you can run Docker commands without sudo (log out and back in afterwards):

sudo usermod -aG docker $USER

Verify the installation:

docker --version
docker compose version

Step 2: Clone the OTOBO Docker repository

The otobo-docker repository contains the Docker Compose configuration and helper scripts. Use the tag that matches the OTOBO version you want (e.g. rel-11_0 for the current 11.0 series).

cd /opt
sudo git clone https://github.com/RotherOSS/otobo-docker.git --branch rel-11_0 /opt/otobo-docker
cd /opt/otobo-docker
ls -a   # sanity check: README.md and the .docker_compose_env_* files should be present

Step 3: Create the .env file

The .env file is the central configuration file for your OTOBO installation. It is not created automatically; instead you copy it from one of the provided sample files:

• .docker_compose_env_http – OTOBO over HTTP (simplest option, e.g. behind your own reverse proxy)
• .docker_compose_env_https – OTOBO over HTTPS with the built-in Nginx reverse proxy

For a simple HTTP installation:

sudo cp -p .docker_compose_env_http .env

For HTTPS, use .docker_compose_env_https instead and provide a certificate (see Advanced installation).

Step 4: Set the database root password

Open the .env file and set a secure password for the database administrator:

sudo vi .env

Adjust the following line:

OTOBO_DB_ROOT_PASSWORD=<your_secure_password>

You will need this password later in the web installer to create the database and the OTOBO schema.

Step 5: Start the containers

Start the whole stack in the background:

sudo docker compose up --detach

On first start the Docker images are downloaded from Docker Hub – depending on your connection this can take a few minutes.

Then verify that all services are running (five for HTTP, six for HTTPS):

sudo docker compose ps

Step 6: Complete the installation via the web installer

Open the OTOBO installer in your browser:

http://<your-server-ip>/otobo/installer.pl

Follow the installer steps and note the following:

• Choose a new MySQL/MariaDB database.
• As the database root password, use the value from OTOBO_DB_ROOT_PASSWORD.
• Leave the MySQL hostname set to db – this is the internal service name of the database container.

When finished you can log in to the agent interface (default user root@localhost; the password is shown at the end of the installer).

After the installation

• Check the OTOBO daemon: the daemon container handles background tasks (email fetching, escalations, cron jobs). It runs as its own container and should be shown as “running”.
• Firewall: open the required ports. With firewalld:

sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

• Enter the container (for CLI tasks):

sudo docker compose exec web bash

Troubleshooting

Elasticsearch does not start / the container exits immediately

Elasticsearch requires an increased vm.max_map_count value. Set it permanently:

sudo sysctl -w vm.max_map_count=262144
echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-otobo-elasticsearch.conf

SELinux blocks container access

CentOS ships with SELinux enabled by default. If containers show access issues, check the audit logs (sudo ausearch -m avc -ts recent). For diagnosis, permissive mode can help (sudo setenforce 0).

Port 80 or 443 already in use

Set different ports in the .env file via OTOBO_WEB_HTTP_PORT or OTOBO_WEB_HTTPS_PORT and restart the stack.

View the logs of a service

sudo docker compose logs -f web
sudo docker compose logs -f elastic

Further topics

For HTTPS configuration, Nginx customization, environment variables, updates and backups, read the Advanced installation of OTOBO.

If you want to combine OTOBO with AI-powered ticket classification, see OTOBO AI & Open Ticket AI.

Get OTOBO professionally installed

Save time and reduce risks: Softoft handles turnkey installation, Docker deployment, hardening, and configuration for your production environment.

Request installation

Frequently asked questions

Which CentOS versions are supported for OTOBO installation using Docker Compose?

OTOBO supports installation on CentOS Stream 8 and CentOS Stream 9 when utilizing Docker and Docker Compose. It's important to note that CentOS Linux 8 has reached its end of life, so for any production environments, it is strongly recommended to use CentOS Stream 9 or a compatible distribution like AlmaLinux, Rocky Linux, or even Red Hat Enterprise Linux (RHEL). The use of Docker Compose is the recommended approach for OTOBO installation on CentOS because it efficiently bundles all necessary services, including the web server, database, Elasticsearch, Redis, and optionally Nginx for HTTPS, into a single, easily manageable stack. This simplifies the setup process significantly, allowing OTOBO to be operational quickly.Quellen:- Install OTOBO on CentOS with Docker Compose- Install OTOBO with Docker (Ubuntu, Debian & more)- OTOBO Installation on RHEL

How do I install Docker, Docker Compose, and Git on CentOS for OTOBO?

To install Docker, Docker Compose, and Git on CentOS for your OTOBO setup, you first need to configure the official Docker CE repository. Begin by installing dnf-plugins-core and git, then add the Docker CE repository using sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo. After the repository is set up, proceed to install Docker Engine, its CLI, containerd.io, and the Docker Compose plugin with the command sudo dnf install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin. Once installed, ensure Docker starts automatically on boot and is running by executing sudo systemctl enable --now docker. Optionally, you can add your user to the docker group (sudo usermod -aG docker $USER) to run Docker commands without sudo, remembering to log out and back in for changes to take effect. Finally, verify the installations with docker --version and docker compose version.Quellen:- Install OTOBO on CentOS with Docker Compose- Installing using Docker and Docker Compose

What are the system requirements for running OTOBO on CentOS with Docker?

For a smooth OTOBO installation on CentOS using Docker, specific system requirements should be met to ensure optimal performance, especially in production environments. The minimum CPU requirement is 2 cores, but 4 or more cores are recommended for production. For RAM, a minimum of 4 GB is needed, with 8 GB or more highly recommended for production, largely due to Elasticsearch, which is part of the stack and demands a fair amount of memory. Disk space should be at least 20 GB free, with 40 GB or more (preferably SSD) for production systems. Regarding software versions, Docker 19.03.13 is the minimum, but the latest version is recommended, along with Docker Compose v2 (latest version recommended) and Git 2.17 (latest version recommended). Planning for at least 8 GB of RAM is crucial for production due to Elasticsearch's memory footprint.Quellen:- Install OTOBO on CentOS with Docker Compose

What is the purpose of the `.env` file in an OTOBO Docker Compose installation?

The .env file serves as the central configuration hub for your OTOBO installation when using Docker Compose. It's crucial because it dictates various settings for the OTOBO services. Unlike some configuration files, it is not generated automatically. Instead, you create it by copying one of the provided sample files from the otobo-docker repository. You have two primary options: .docker_compose_env_http for a simpler setup where OTOBO runs over HTTP (often used when behind your own reverse proxy), or .docker_compose_env_https if you intend to use OTOBO over HTTPS with the built-in Nginx reverse proxy, which requires providing a certificate. This file is also where you configure critical parameters like the OTOBO_DB_ROOT_PASSWORD, which is essential for the web installer to create the database and OTOBO schema.Quellen:- Install OTOBO on CentOS with Docker Compose- Installing using Docker and Docker Compose

What are the essential steps to complete the OTOBO installation using the web installer?

After successfully starting the OTOBO containers, the next essential step is to complete the installation through the web installer. You access this by navigating to http://<your-server-ip>/otobo/installer.pl in your web browser. During the installer's guided steps, you will need to make a few key selections. First, choose the option to create a new MySQL/MariaDB database. When prompted for the database root password, you must enter the secure password you previously set in the .env file for the OTOBO_DB_ROOT_PASSWORD variable. It is vital to leave the MySQL hostname set to db; this is the internal service name that Docker Compose uses to identify the database container within the OTOBO stack. Upon successful completion of these steps, the installer will provide you with the credentials to log in to the agent interface, typically using root@localhost with the password displayed at the end of the installation process.Quellen:- Install OTOBO on CentOS with Docker Compose- OTOBO Installation Guide 10.1 documentation

What post-installation checks and troubleshooting tips are important for OTOBO on CentOS?

After installing OTOBO on CentOS, several post-installation checks and troubleshooting steps are important to ensure smooth operation. First, verify the OTOBO daemon is running, as it handles critical background tasks like email fetching and cron jobs. Next, configure your firewall to open necessary ports; for firewalld, use sudo firewall-cmd --permanent --add-service=http and sudo firewall-cmd --permanent --add-service=https, followed by sudo firewall-cmd --reload. For CLI tasks, you can enter the OTOBO container using sudo docker compose exec web bash. If Elasticsearch fails to start, increase vm.max_map_count permanently with sudo sysctl -w vm.max_map_count=262144 and echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-otobo-elasticsearch.conf. If SELinux causes access issues, check audit logs (sudo ausearch -m avc -ts recent) or temporarily set permissive mode (sudo setenforce 0). Port conflicts (80/443) can be resolved by adjusting OTOBO_WEB_HTTP_PORT or OTOBO_WEB_HTTPS_PORT in the .env file and restarting. Finally, view service logs for diagnosis using sudo docker compose logs -f <service_name>, e.g., web or elastic.Quellen:- Install OTOBO on CentOS with Docker Compose- Advanced installation of OTOBO