Install OTOBO on RHEL with Docker Compose

This guide describes the full installation of OTOBO on Red Hat Enterprise Linux (RHEL) 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 RHEL versions

• RHEL 8
• RHEL 9

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 RHEL, Docker is installed from the official Docker CE repository (the docker package from the standard repos is outdated or unavailable). First set up the repository:

sudo dnf install -y dnf-plugins-core git
sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/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

RHEL ships with SELinux enabled by default. If containers show access issues, check the audit logs (sudo ausearch -m avc -ts recent). If needed, set an appropriate SELinux boolean or temporarily switch to permissive mode for diagnosis (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 RHEL versions are supported for OTOBO using Docker Compose?

OTOBO officially supports Red Hat Enterprise Linux (RHEL) versions 8 and 9 when installed using Docker and Docker Compose. This method is highly recommended as it bundles all necessary services like the web server, database, Elasticsearch, and Redis, making the installation process consistent and straightforward across different Linux distributions. For RHEL, Docker is installed from the official Docker CE repository, as the default docker package from standard RHEL repositories might be outdated or unavailable for the required versions. This ensures you're running a current and well-supported Docker environment for OTOBO.

Quellen / Sources

• Install OTOBO with Docker (Ubuntu, Debian & more)
• OTOBO Installation on RHEL - OTOBO Documentation
• The Easy Way to Install OTOBO - Docker and Docker Compose

What are the minimum system requirements for installing OTOBO on RHEL?

For a smooth OTOBO installation on RHEL using Docker Compose, it's crucial to meet specific system requirements. The minimum recommendations include a CPU with at least 2 cores, 4 GB of RAM, and 20 GB of free disk space. However, for production environments, it's highly recommended to plan for more robust resources: 4+ CPU cores, 8 GB or more of RAM, and 40 GB+ of SSD disk space. It's particularly important to note that Elasticsearch, which is an integral part of the OTOBO Docker stack, is memory-intensive. Therefore, ensuring at least 8 GB of RAM is available for production setups is critical for optimal performance. Additionally, you'll need Docker version 19.03.13 or newer, Docker Compose v2 or newer, and Git version 2.17 or newer.

Quellen / Sources

• Install OTOBO on RHEL with Docker Compose
• OTOBO Installation Guide 11.0 documentation

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

To install Docker, Docker Compose, and Git on RHEL for OTOBO, you'll primarily use the dnf package manager and the official Docker CE repository. First, ensure dnf-plugins-core and git are installed, then add the Docker CE repository:

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

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

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

After installation, enable and start the Docker service to ensure it launches automatically on boot:

sudo systemctl enable --now docker

Optionally, add your user to the docker group to run Docker commands without sudo (requires logging out and back in):

sudo usermod -aG docker $USER

Finally, verify the installation by checking docker --version and docker compose version.

Quellen / Sources

• Install OTOBO on RHEL with Docker Compose
• OTOBO Installation Guide 11.0 documentation

What is the role of the `.env` file in an OTOBO Docker Compose installation, and how is it created?

The .env file serves as the central configuration hub for your OTOBO Docker Compose installation. It's crucial for defining environment variables that control various aspects of OTOBO and its bundled services, such as database credentials, port mappings, and other operational settings. This file is not automatically generated; instead, you create it by copying one of the provided sample files from the otobo-docker repository.
There are two primary sample files:

• .docker_compose_env_http: For OTOBO running over HTTP, which is the simplest setup, often used when OTOBO is placed behind an existing reverse proxy.
• .docker_compose_env_https: For OTOBO running over HTTPS, utilizing the built-in Nginx reverse proxy, which requires providing a valid SSL certificate.
  For a basic HTTP installation, you would typically run:

sudo cp -p .docker_compose_env_http .env

After creating the .env file, you must edit it to set a secure password for the database root user, specifically the OTOBO_DB_ROOT_PASSWORD variable, which will be needed during the web installer process.

Quellen / Sources

• Install OTOBO on RHEL with Docker Compose
• OTOBO Installation Guide 11.0 documentation
• Advanced installation of OTOBO

What steps are involved in completing the OTOBO installation via the web installer?

After starting the OTOBO Docker containers, the final step is to complete the installation through the web installer. You access this by navigating your browser to http://<your-server-ip>/otobo/installer.pl.
During the web installer process, you'll be guided through several steps:

• Welcome Screen: Accept the license agreement.
• Database Setup: Choose to create a new MySQL/MariaDB database.
• Database Credentials: When prompted for the database root password, use the secure password you previously set for the OTOBO_DB_ROOT_PASSWORD variable in your .env file. Crucially, leave the MySQL hostname set to db; this is the internal service name that Docker Compose uses to connect to the database container.
• System Settings: Configure basic system settings, including the system ID, organization name, and email addresses.
  Once all steps are completed, the installer will finalize the database setup and provide you with the default login credentials for the agent interface (typically root@localhost with a generated password displayed on the final screen). You can then log in and begin configuring your OTOBO system.

Quellen / Sources

• Install OTOBO on RHEL with Docker Compose
• OTOBO Installation Guide 11.0 documentation

What are some common troubleshooting tips for OTOBO installations on RHEL with Docker Compose?

When troubleshooting OTOBO installations on RHEL with Docker Compose, several common issues can arise.

• Elasticsearch not starting: If the Elasticsearch container exits immediately, it's often due to an insufficient vm.max_map_count value. You can set this permanently by running:

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

Then restart your Docker stack.

• SELinux blocking container access: RHEL's SELinux can sometimes restrict container operations. Check audit logs with sudo ausearch -m avc -ts recent. If SELinux is the cause, you might need to set an appropriate SELinux boolean or temporarily switch to permissive mode (sudo setenforce 0) for diagnostic purposes.
• Port 80 or 443 already in use: If these ports are occupied by another service, you can adjust the ports OTOBO uses by modifying OTOBO_WEB_HTTP_PORT or OTOBO_WEB_HTTPS_PORT in your .env file, then restart the Docker stack.
• Viewing service logs: For any service issues, checking its logs is crucial. Use sudo docker compose logs -f <service_name>, for example, sudo docker compose logs -f web or sudo docker compose logs -f elastic, to view real-time output.

Quellen / Sources

• Install OTOBO on RHEL with Docker Compose
• OTOBO Installation Guide 11.0 documentation