Install OTOBO on Ubuntu with Docker Compose

This guide describes the full installation of OTOBO on Ubuntu 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 Ubuntu versions

• Ubuntu 20.04 LTS
• Ubuntu 22.04 LTS
• Ubuntu 24.04 LTS

Newer and some older versions work as well, as long as a current Docker version is available.

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

First update the package sources and install the required packages:

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

[!NOTE] The docker-compose-v2 package is available from Ubuntu 22.04 onwards. On older versions, install the official Docker repository (see docs.docker.com) or use the legacy docker-compose package.

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 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), e.g. sudo ufw allow 80/tcp.
• 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.

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 Ubuntu versions are officially supported for OTOBO installation using Docker Compose?

OTOBO supports installation on several Ubuntu LTS (Long Term Support) versions, specifically Ubuntu 20.04 LTS, 22.04 LTS, and 24.04 LTS. While these are the explicitly listed versions, OTOBO can also function on newer Ubuntu releases and some older versions, provided that a current and compatible Docker version is available on the system. The key requirement is the availability of a stable Docker environment to run the OTOBO Docker Compose stack effectively. This flexibility ensures that users can deploy OTOBO across a range of Ubuntu server environments.

• Install OTOBO with Docker (Ubuntu, Debian & more)
• Install OTOBO on Ubuntu with Docker Compose

What are the recommended system requirements for installing OTOBO on Ubuntu with Docker Compose, especially for production?

For a production OTOBO environment on Ubuntu using Docker Compose, it's crucial to meet specific system requirements to ensure optimal performance and stability. The recommended specifications include at least 4+ CPU cores, 8 GB of RAM or more, and 40 GB+ of SSD disk space. For Docker, Docker Compose, and Git, it's advised to use the latest available versions. A critical consideration is Elasticsearch, which is an integral part of the OTOBO stack and consumes a significant amount of memory. Therefore, the 8 GB RAM recommendation is primarily driven by Elasticsearch's needs in a production setting. Meeting these recommendations helps prevent performance bottlenecks and ensures a smooth operation of your OTOBO instance.

• Install OTOBO on Ubuntu with Docker Compose

How do I install Docker, Docker Compose, and Git on Ubuntu to prepare for OTOBO installation?

To prepare your Ubuntu system for OTOBO, you first need to install Docker, Docker Compose, and Git. Begin by updating your package sources with sudo apt update. Then, install the necessary packages using sudo apt install -y docker.io docker-compose-v2 git. Note that docker-compose-v2 is typically available on Ubuntu 22.04 and newer; for older versions, you might need to install the official Docker repository or use the legacy docker-compose package. After installation, enable and start the Docker service to ensure it launches automatically on boot with sudo systemctl enable --now docker. Optionally, 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 installation by checking docker --version and docker compose version.

• Install OTOBO on Ubuntu with Docker Compose
• Install OTOBO with Docker (Ubuntu, Debian & more)

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

The .env file is the central configuration file for your OTOBO Docker Compose installation, acting as the primary interface for managing various settings. It is not automatically generated; instead, you create it by copying one of the provided sample files from the otobo-docker repository. You have two main options: .docker_compose_env_http for OTOBO over HTTP, which is the simplest choice often used behind an existing reverse proxy, or .docker_compose_env_https for OTOBO over HTTPS, which leverages the built-in Nginx reverse proxy. For a basic HTTP setup, you would use the command sudo cp -p .docker_compose_env_http .env. If you opt for HTTPS, you'll also need to provide a valid SSL certificate. After copying, you'll edit this .env file to set critical parameters, such as the database root password.

• Install OTOBO on Ubuntu with Docker Compose
• Installing using Docker and Docker Compose

How do I complete the OTOBO installation using the web installer after starting the Docker containers?

After successfully starting your OTOBO Docker containers, the final step involves completing the installation through the web installer. Open your web browser and navigate to http://<your-server-ip>/otobo/installer.pl. Follow the on-screen prompts, paying close attention to specific details. When prompted, choose to create a new MySQL/MariaDB database. For the database root password, you must use the value you previously set for OTOBO_DB_ROOT_PASSWORD in your .env file. Crucially, leave the MySQL hostname set to db; this is the internal service name that allows the OTOBO web container to communicate with the database container within the Docker network. Once the installer finishes, you can log in to the agent interface using the default user root@localhost and the password provided at the end of the installation process.

• Install OTOBO on Ubuntu with Docker Compose

What are common troubleshooting steps for OTOBO Docker Compose installations on Ubuntu?

Several common issues can arise during an OTOBO Docker Compose installation on Ubuntu, each with straightforward troubleshooting steps. If Elasticsearch does not start or exits immediately, it often requires an increased vm.max_map_count value. You can set this permanently with sudo sysctl -w vm.max_map_count=262144 followed by echo "vm.max_map_count=262144" | sudo tee /etc/sysctl.d/99-otobo-elasticsearch.conf. If port 80 or 443 is already in use, you can modify OTOBO_WEB_HTTP_PORT or OTOBO_WEB_HTTPS_PORT in your .env file to use different ports, then restart the stack. To view logs of a specific service for debugging, use sudo docker compose logs -f <service_name>, for example, sudo docker compose logs -f web or sudo docker compose logs -f elastic. Finally, to restart or stop the entire OTOBO stack, use sudo docker compose restart or sudo docker compose stop respectively.

• Install OTOBO on Ubuntu with Docker Compose

Is Ubuntu a good choice for hosting OTOBO in a production environment using Docker Compose?

Yes, Ubuntu is an excellent and highly recommended choice for hosting OTOBO in a production environment, especially when utilizing Docker Compose. This setup provides a common, stable, and well-documented path for deploying the official OTOBO stack. Ubuntu's long-term support (LTS) releases offer stability and security updates over extended periods, making it a reliable foundation for critical applications like OTOBO. Combining Ubuntu with Docker Compose simplifies the management of OTOBO and its dependencies (like the web server, database, Elasticsearch, and Redis) by encapsulating them in containers. This approach ensures consistency, portability, and ease of updates, making it a robust solution for production-grade OTOBO deployments.

• Install OTOBO on Ubuntu with Docker Compose
• Install OTOBO with Docker (Ubuntu, Debian & more)