Advanced installation of OTOBO with Docker Compose

This guide covers advanced configuration for the official otobo-docker stack. It assumes you have already completed the basic Docker Compose installation and want to enable HTTPS, tune the stack, or adapt it to your infrastructure.

[!NOTE] All commands below use docker compose (Compose v2). On older systems you can replace it with docker-compose.

Prerequisites

• A working OTOBO installation with the official otobo-docker repository cloned to /opt/otobo-docker
• SSH access to the host
• For HTTPS: a valid TLS certificate and private key (e.g. from Let’s Encrypt or your CA)

Understanding the Docker stack

The Compose stack runs five services for HTTP, or six when HTTPS is enabled:

Service	Container (OTOBO 11)	Purpose
web	otobo-web-1	OTOBO web server (internal port 5000)
daemon	otobo-daemon-1	Background tasks (mail fetch, escalations, cron)
db	otobo-db-1	MariaDB database (internal port 3306)
elastic	otobo-elastic-1	Elasticsearch (ports 9200/9300)
redis	otobo-redis-1	Redis cache
nginx (HTTPS only)	otobo-nginx-1	Nginx reverse proxy with TLS

[!NOTE] On OTOBO 10.x installations, container names use underscores instead of hyphens (e.g. otobo_web_1).

Verify running containers:

cd /opt/otobo-docker
sudo docker compose ps

Docker volumes

Docker volumes persist data on the host. Containers can be recreated without losing application data:

Volume	Mount point	Used by
otobo_opt_otobo	/opt/otobo	web, daemon
otobo_mariadb_data	/var/lib/mysql	db
otobo_elasticsearch_data	/usr/share/elasticsearch/data	elastic
otobo_redis_data	Redis data directory	redis
otobo_nginx_ssl	TLS certificate and key	nginx (HTTPS)

[!WARNING] Never delete volumes unless you have a verified backup. See Backup & Restore for guidance.

Enable HTTPS with the built-in Nginx proxy

For production environments, run OTOBO over HTTPS using the Nginx container included in the stack.

Step 1: Switch to the HTTPS environment file

cd /opt/otobo-docker
sudo cp -p .docker_compose_env_https .env

If you already have a .env file from an HTTP installation, back it up first or merge your existing settings (especially OTOBO_DB_ROOT_PASSWORD) into the new file.

Step 2: Configure TLS certificate paths

Edit .env and set the paths to your certificate and private key inside the Nginx container:

sudo nano .env

OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt
OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Place your certificate files in the otobo_nginx_ssl volume or mount them from the host. The exact mount is defined in docker-compose/otobo-override-https.yml.

Step 3: Start or restart the stack

sudo docker compose up --detach

With HTTPS enabled, six containers should be running (including nginx). Open the installer or agent interface at:

https://<your-server-fqdn>/otobo/

Step 4: Complete the web installer

If this is a fresh installation, follow the web installer steps and use the same database settings as for HTTP (db as hostname, OTOBO_DB_ROOT_PASSWORD as root password).

Environment variables

The .env file controls the entire stack. The sample files .docker_compose_env_http and .docker_compose_env_https are starting points; adjust values as needed.

Database

Variable	Description
OTOBO_DB_ROOT_PASSWORD	MariaDB root password. Required for the db service and the web installer.

Elasticsearch

Elasticsearch needs adequate memory in production. See the Elasticsearch Docker production guide for host-level requirements.

Variable	Description
OTOBO_Elasticsearch_ES_JAVA_OPTS	JVM heap settings, e.g. -Xms512m -Xmx512m. Increase up to 4 GB for larger installations.

Web server and Nginx

Variable	Description
OTOBO_WEB_HTTP_PORT	External HTTP port (default 80). Redirects to HTTPS when Nginx is enabled.
OTOBO_WEB_HTTPS_PORT	External HTTPS port (default 443).
OTOBO_NGINX_SSL_CERTIFICATE	Path to the TLS certificate inside the Nginx container.
OTOBO_NGINX_SSL_CERTIFICATE_KEY	Path to the TLS private key inside the Nginx container.
OTOBO_NGINX_WEB_HOST	Internal HTTP host used by Nginx to reach the web service.
OTOBO_NGINX_WEB_PORT	Internal HTTP port of the web service.

Kerberos SSO (optional)

Variable	Description
OTOBO_NGINX_KERBEROS_KEYTAB	Kerberos keytab file (default /etc/krb5.keytab). Must be mounted from the host.
OTOBO_NGINX_KERBEROS_CONFIG	Kerberos config file (default /etc/krb5.conf).
OTOBO_NGINX_KERBEROS_REALM	Kerberos realm, used in /etc/krb5.conf.
OTOBO_NGINX_KERBEROS_KDC	KDC / Active Directory controller.
OTOBO_NGINX_KERBEROS_ADMIN_SERVER	Kerberos admin server.
OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN	Default domain for Kerberos.

Use .docker_compose_env_https_kerberos as the base and follow the dedicated Kerberos SSO guide for Active Directory setup.

Docker Compose settings

Variable	Description
COMPOSE_PROJECT_NAME	Prefix for container and volume names (default otobo). Change this to run multiple OTOBO instances on one host.
COMPOSE_FILE	Colon-separated list of Compose files, e.g. docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml.
COMPOSE_PATH_SEPARATOR	Separator character for COMPOSE_FILE (default : on Linux).
OTOBO_IMAGE_OTOBO	Override the OTOBO web/daemon image tag.
OTOBO_IMAGE_OTOBO_ELASTICSEARCH	Override the Elasticsearch image.
OTOBO_IMAGE_OTOBO_NGINX	Override the Nginx image.

Custom Nginx configuration

The nginx container uses an OTOBO-specific template at /etc/nginx/template/otobo_nginx.conf.template. Environment variables are substituted when the container starts.

For changes beyond what the .env file supports, export the active configuration and mount your own file:

cd /opt/otobo-docker
mkdir -p nginx
sudo docker cp otobo-nginx-1:/etc/nginx/conf.d/otobo_nginx.conf nginx/otobo_nginx.conf

Add a volume mount in a custom override file (do not edit files under docker-compose/ directly — see below):

custom_nginx.yml

services:
  nginx:
    volumes:
      - /opt/otobo-docker/nginx/otobo_nginx.conf:/etc/nginx/conf.d/otobo_nginx.conf:ro

Include the file via COMPOSE_FILE in .env, then restart:

sudo docker compose up --detach

For a fully custom Nginx setup, start from .docker_compose_env_https_custom_nginx.

Non-standard ports

If ports 80 or 443 are already in use, set alternative ports in .env:

OTOBO_WEB_HTTP_PORT=8080
OTOBO_WEB_HTTPS_PORT=8443

Restart the stack after changing port values.

Using an external database

By default, all five (or six) services start together. If MariaDB runs outside Docker, start only the services you need:

sudo docker compose up --detach web nginx daemon redis elastic

Alternatively, create a custom Compose override that removes or disables the db service, then point OTOBO to your external database during installation.

Custom Compose overrides

Avoid editing files in docker-compose/ directly — they are overwritten when you update the otobo-docker repository. Instead, add your own YAML file and reference it in COMPOSE_FILE.

Example: expose the database on port 3306 for external access.

Create custom_db.yml:

services:
  db:
    ports:
      - "0.0.0.0:3306:3306"

Add it to .env:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-http.yml:custom_db.yml

Recreate the containers:

sudo docker compose stop
sudo docker compose up --detach

This pattern works for any service or volume customization.

Customizing the OTOBO application

Most application-level changes belong in the otobo_opt_otobo volume (/opt/otobo inside the container), not in a modified Docker image.

Install a local Perl module without rebuilding the image:

sudo docker compose exec web bash
cd /opt/otobo
cpanm -l local Some::Module
exit

Modules installed under /opt/otobo/local persist across container restarts.

To add system packages (e.g. extra Debian tools), build a custom image from a Dockerfile based on rotheross/otobo, or use docker commit on a temporary root session. This is rarely needed for production installations.

Building local Docker images

[!NOTE] Building images locally is mainly useful for OTOBO development or when you need a patched base image.

Dockerfiles live in the OTOBO source repository:

cd /opt
git clone https://github.com/RotherOSS/otobo.git
cd otobo
git checkout rel-11_0
bin/docker/build_docker_images.sh
docker image ls

Built images are tagged as local-<OTOBO_VERSION>. Reference them in .env:

OTOBO_IMAGE_OTOBO=local-11.0.x
OTOBO_IMAGE_OTOBO_ELASTICSEARCH=local-11.0.x
OTOBO_IMAGE_OTOBO_NGINX=local-11.0.x

Automatic installation (development)

For test environments, skip the web installer and use the built-in setup script:

[!WARNING] docker compose down -v deletes all volumes and data. Use only on disposable test systems.

cd /opt/otobo-docker
sudo docker compose down -v
sudo docker compose up --detach
sudo docker compose stop daemon
sudo docker compose exec web bash -c \
  "rm -f Kernel/Config/Files/ZZZAAuto.pm ; bin/docker/quick_setup.pl --db-password otobo_root"
sudo docker compose start daemon

Useful commands

Stack management

sudo docker compose ps              # show running containers
sudo docker compose logs -f web     # follow web server logs
sudo docker compose logs -f elastic # follow Elasticsearch logs
sudo docker compose restart         # restart all services
sudo docker compose stop            # stop all services
sudo docker compose config          # validate and display merged config

Inside the OTOBO container

sudo docker compose exec web bash   # open a shell in the web container

System maintenance

docker system prune -a   # remove unused images, containers, and networks (use with care)

Further topics

• Backup & Restore — protect database and Docker volumes
• Updating OTOBO — upgrade to a new release safely
• Performance optimization — tune Elasticsearch and OTOBO for high volume
• Kerberos SSO — Single Sign-On with Active Directory
• Basic Docker Compose installation — return to the standard install guide

For professional support with installation or integration, 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

How do I enable HTTPS for my OTOBO Docker Compose installation using the built-in Nginx proxy?

To enable HTTPS for your OTOBO Docker Compose installation, you need to leverage the built-in Nginx container. First, navigate to your otobo-docker directory, typically /opt/otobo-docker. Then, switch to the HTTPS environment file by copying it: sudo cp -p .docker_compose_env_https .env. If you have an existing .env file, ensure you back it up or merge your critical settings, like OTOBO_DB_ROOT_PASSWORD, into the new HTTPS-specific file.

Next, you must configure the paths to your TLS certificate and private key within the Nginx container. Edit the .env file (sudo nano .env) and set the OTOBO_NGINX_SSL_CERTIFICATE and OTOBO_NGINX_SSL_CERTIFICATE_KEY variables to the correct internal paths, for example: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt and OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key. These certificate files should be placed in the otobo_nginx_ssl Docker volume or mounted from the host, as defined in docker-compose/otobo-override-https.yml. Finally, start or restart your OTOBO stack with sudo docker compose up --detach. After this, six containers, including nginx, should be running, and you can access OTOBO via https://<your-server-fqdn>/otobo/.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• Installing using Docker and Docker Compose

What are the essential Docker services and their purposes in an OTOBO Docker Compose stack?

The OTOBO Docker Compose stack is designed to run multiple interconnected services, ensuring all components of the OTOBO system function correctly. For an HTTP setup, there are five core services, which expand to six when HTTPS is enabled. The primary services include web, which hosts the OTOBO web server, typically listening internally on port 5000. The daemon service is crucial for handling background tasks such as mail fetching, escalations, and cron jobs, ensuring OTOBO's automated processes run smoothly.

The db service provides the MariaDB database, which is the backbone for storing all OTOBO application data, accessible internally on port 3306. For efficient search and indexing capabilities, the elastic service runs Elasticsearch, utilizing ports 9200 and 9300. Caching is managed by the redis service, which provides a Redis cache to improve performance. When HTTPS is enabled, an additional nginx service is introduced. This service acts as an Nginx reverse proxy, handling TLS encryption and secure communication for your OTOBO instance. It's important to note that container names might vary slightly between OTOBO versions, with OTOBO 10.x using underscores (e.g., otobo_web_1) and OTOBO 11 using hyphens (e.g., otobo-web-1). You can verify running containers using sudo docker compose ps from your otobo-docker directory.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• RotherOSS/otobo-docker: OTOBO Docker and Docker Compose files.

How do Docker volumes ensure data persistence for OTOBO in a Docker Compose environment, and what data is stored?

Docker volumes are fundamental to ensuring data persistence in an OTOBO Docker Compose setup, allowing containers to be recreated, updated, or replaced without any loss of critical application data. This mechanism detaches the data storage from the lifecycle of the containers themselves, mounting specific host directories or managed volumes into the containers.

For OTOBO, several key volumes are utilized:

• otobo_opt_otobo: This volume is mounted to /opt/otobo within the web and daemon containers. It stores the core OTOBO application files, configurations, and attachments.
• otobo_mariadb_data: Mounted to /var/lib/mysql in the db container, this volume is dedicated to storing all MariaDB database files, ensuring your OTOBO ticketing data, user information, and system settings are preserved.
• otobo_elasticsearch_data: This volume is used by the elastic container, typically mounted to /usr/share/elasticsearch/data, and holds all Elasticsearch indices and data.
• otobo_redis_data: This volume stores the Redis cache data, used by the redis service to enhance OTOBO's performance.
• otobo_nginx_ssl: Specifically for HTTPS installations, this volume stores your TLS certificate and private key, which are used by the nginx container.

It is critically important to never delete these volumes unless you have a verified backup, as doing so would result in irreversible data loss. For guidance on protecting your data, refer to the OTOBO backup and restore documentation.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• OTOBO Installation Guide 11.1 documentation

Which environment variables are crucial for configuring the OTOBO Docker Compose stack, particularly for database, Elasticsearch, and Nginx settings?

The .env file is the central configuration point for the entire OTOBO Docker Compose stack, allowing you to customize various aspects of your installation. Several environment variables are crucial for the proper functioning and tuning of OTOBO.

For the database, OTOBO_DB_ROOT_PASSWORD is essential as it sets the MariaDB root password, which is required by the db service and during the initial web installer setup.

Regarding Elasticsearch, OTOBO_Elasticsearch_ES_JAVA_OPTS is vital for performance tuning. This variable allows you to configure JVM heap settings, such as -Xms512m -Xmx512m. For larger installations, it's recommended to increase these values, potentially up to 4 GB, to ensure Elasticsearch has adequate memory.

For the web server and Nginx, several variables control external access and HTTPS:

• OTOBO_WEB_HTTP_PORT defines the external HTTP port (default 80), which typically redirects to HTTPS when Nginx is active.
• OTOBO_WEB_HTTPS_PORT sets the external HTTPS port (default 443).
• OTOBO_NGINX_SSL_CERTIFICATE and OTOBO_NGINX_SSL_CERTIFICATE_KEY specify the internal paths to your TLS certificate and private key within the Nginx container, respectively.
• OTOBO_NGINX_WEB_HOST and OTOBO_NGINX_WEB_PORT define how Nginx internally communicates with the web service.

Additionally, COMPOSE_PROJECT_NAME (default otobo) is important if you plan to run multiple OTOBO instances on a single host, as it prefixes container and volume names. COMPOSE_FILE allows you to specify a colon-separated list of Compose files, enabling custom overrides. The sample files .docker_compose_env_http and .docker_compose_env_https serve as excellent starting points for your .env configuration.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• Installing using Docker and Docker Compose
• Elasticsearch Docker production guide

What are the prerequisites for an advanced OTOBO Docker Compose installation, especially when enabling HTTPS?

Before embarking on an advanced OTOBO Docker Compose installation, particularly if you intend to enable HTTPS, several prerequisites must be met to ensure a smooth setup.

Firstly, you need a working OTOBO installation that has been set up using the official otobo-docker repository. This repository should be cloned to a standard location, typically /opt/otobo-docker, as many commands and configurations assume this path. This ensures you have the base Docker Compose files and scripts necessary for the advanced configuration.

Secondly, SSH access to the host machine where OTOBO is installed is essential. This allows you to execute necessary commands, manage files, and troubleshoot issues directly on the server, which is crucial for tasks like copying environment files, editing configurations, and interacting with Docker Compose.

Finally, and most importantly for HTTPS, you must have a valid TLS certificate and its corresponding private key. These can be obtained from a reputable Certificate Authority (CA) or generated using services like Let's Encrypt. The certificate and key are critical for encrypting traffic between your users and the OTOBO instance, ensuring secure communication. Without these, enabling HTTPS with the built-in Nginx proxy will not be possible. These files will later be configured in your .env file and mounted into the nginx container.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• Install OTOBO on Debian with Docker Compose

Can I customize the Nginx configuration for OTOBO beyond the provided environment variables?

Yes, you can customize the Nginx configuration for OTOBO beyond what is directly controlled by the environment variables in the .env file. The nginx container in the OTOBO Docker Compose stack uses a specific template located at /etc/nginx/template/otobo_nginx.conf.template. This template processes environment variables during container startup to generate the active Nginx configuration.

If your customization needs go beyond simple variable substitutions, you can export the currently active Nginx configuration and then mount your own custom file. To do this, first navigate to your otobo-docker directory, typically /opt/otobo-docker. Then, create a directory for your custom Nginx configuration, for example, mkdir -p nginx. Next, copy the active configuration from the running nginx container to your host machine: sudo docker cp otobo-nginx-1:/etc/nginx/conf.d/otobo_nginx.conf nginx/otobo_nginx.conf.

Once you have this file on your host, you can modify nginx/otobo_nginx.conf as needed. After making your changes, you will need to add a volume mount in a custom Docker Compose override file. It is crucial not to directly edit the files located under docker-compose/, as these are part of the official stack and may be overwritten during updates. Instead, create a new override file (e.g., docker-compose/otobo-override-custom-nginx.yml) and add a volume mount that replaces the default Nginx configuration with your customized version. This approach allows you to maintain your specific Nginx settings while still benefiting from the official otobo-docker stack.

Quellen / Sources:

• Advanced installation of OTOBO with Docker Compose
• RotherOSS/otobo-docker: OTOBO Docker and Docker Compose files.