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.

Frequently asked questions

When should I use the advanced Docker Compose guide?

Use it after the basic Docker Compose install when you need HTTPS, Nginx, custom overrides, or stack tuning.

Does the otobo-docker stack include an Nginx reverse proxy?

Yes. For HTTPS you enable the built-in Nginx container with TLS certificate paths in the .env file.

Will Docker volumes keep my OTOBO data if containers are recreated?

Yes. Application, database, Elasticsearch, and Redis data live in named Docker volumes and persist across recreations.