OTOBO Docker Compose: Install the Official Stack

Installing OTOBO with Docker Compose is the recommended method for production environments. 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 on any Linux distribution that supports Docker.

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

Install Docker and Docker Compose on your server. The exact commands depend on your Linux distribution:

• Ubuntu
• Debian
• CentOS
• RHEL
• SUSE

On Windows or macOS, install Docker Desktop and enable WSL 2 integration (Windows). Then follow the steps below inside a terminal.

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 nano .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 (port 80 for HTTP or 443 for HTTPS).
• 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

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

Restart or stop the stack

sudo docker compose restart
sudo docker compose stop

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.

For professional support with installation or integration, please contact Softoft.de.

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

What are the system requirements for installing OTOBO with Docker Compose?

The official OTOBO Docker Compose stack requires a supported Linux host with Docker, Docker Compose, and Git installed. For optimal performance, especially in production environments, specific resource allocations are recommended. You'll need at least 2 CPU cores (4+ recommended), 4 GB RAM (8 GB or more recommended), and 20 GB free disk space (40 GB+ SSD recommended). Docker version 20.10+, Docker Compose v2+, and Git 2.17+ are the minimum software versions. It's crucial to note that Elasticsearch, a component of the OTOBO stack, is memory-intensive. Therefore, planning for at least 8 GB of RAM is strongly advised for production setups to ensure stable operation.

Quellen

• OTOBO Docker Compose: Install the Official Stack
• Install OTOBO on Debian with Docker Compose

How do I prepare the OTOBO Docker environment before starting the containers?

To prepare your OTOBO Docker environment, first, navigate to the /opt directory and clone the official otobo-docker repository from GitHub. It's important to specify the branch corresponding to the OTOBO version you intend to install, for example, rel-11_0 for the 11.0 series. After cloning, change into the newly created otobo-docker directory. The next critical step is to create your .env configuration file. This file is not automatically generated; instead, you copy it from one of the provided templates: .docker_compose_env_http for a simple HTTP setup or .docker_compose_env_https if you plan to use the built-in Nginx for HTTPS. Finally, open your new .env file and set a secure password for the database root user by adjusting the OTOBO_DB_ROOT_PASSWORD variable. This password will be required during the web installer process.

Quellen

• OTOBO Docker Compose: Install the Official Stack
• OTOBO Docker and Docker Compose files. · GitHub
• Installing using Docker and Docker Compose

What are the steps to start the OTOBO Docker containers and complete the web installation?

Once your .env file is configured, start the OTOBO Docker stack by running sudo docker compose up --detach. This command downloads the necessary Docker images from Docker Hub on the first run and starts all services in the background. After a few minutes, verify that all containers are running by executing sudo docker compose ps. You should see five services for an HTTP setup or six for HTTPS.

Next, open your web browser and navigate to the OTOBO installer at http://<your-server-ip>/otobo/installer.pl. Follow the on-screen instructions:

• When prompted, choose to create a new MySQL/MariaDB database.
• For the database root password, use the value you set for OTOBO_DB_ROOT_PASSWORD in your .env file.
• Crucially, leave the MySQL hostname as db, as this is the internal service name for the database container within the Docker network.

Upon completion, you can log in to the agent interface using the default user root@localhost and the password displayed at the end of the installer.

Quellen

• OTOBO Docker Compose: Install the Official Stack
• The Easy Way to Install OTOBO - Docker and Docker Compose

What common issues might I encounter during OTOBO Docker Compose installation and how can I troubleshoot them?

During OTOBO Docker Compose installation, you might encounter a few common issues.

• Elasticsearch does not start: If the Elasticsearch container exits immediately, it's likely due to an insufficient vm.max_map_count value. You can resolve this by permanently setting it to 262144 using sudo sysctl -w vm.max_map_count=262144 and echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-otobo-elasticsearch.conf.
• Port 80 or 443 already in use: If these standard web ports are already occupied by another service on your host, OTOBO's web server won't start. To fix this, modify the .env file and set different ports using OTOBO_WEB_HTTP_PORT or OTOBO_WEB_HTTPS_PORT, then restart your Docker stack.
• Viewing logs: For any service that isn't behaving as expected, you can view its real-time logs using sudo docker compose logs -f <service_name>, replacing <service_name> with web, elastic, db, etc.
• Restarting or stopping the stack: To apply configuration changes or resolve transient issues, you can restart the entire stack with sudo docker compose restart or stop it completely with sudo docker compose stop.

Quellen

• OTOBO Docker Compose: Install the Official Stack

What are important considerations after successfully installing OTOBO with Docker Compose?

After successfully completing the OTOBO installation via the web installer, there are several important post-installation considerations.

• Check the OTOBO daemon: Ensure the OTOBO daemon container is running. This daemon handles essential background tasks like email fetching, escalations, and cron jobs, and its proper functioning is critical for OTOBO's operation.
• Firewall configuration: Remember to open the necessary ports on your server's firewall. This typically means port 80 for HTTP access or port 443 if you configured OTOBO for HTTPS.
• Entering the container: For command-line interface (CLI) tasks, such as running OTOBO scripts or performing maintenance, you can enter the web container using sudo docker compose exec web bash. This provides a shell environment within the running OTOBO application.
• Further topics: For advanced configurations like detailed HTTPS setup, Nginx customization, managing environment variables, performing updates, and implementing backup strategies, consult the Advanced installation of OTOBO guide. Additionally, if you're interested in AI-powered ticket classification, explore the documentation on OTOBO AI & Open Ticket AI.

Quellen

• OTOBO Docker Compose: Install the Official Stack
• Advanced installation of OTOBO
• OTOBO AI & Open Ticket AI