Installation mit Docker und Docker Compose

Mit der Docker-basierten Installation können Sie Ihre komplette OTOBO-Instanz innerhalb weniger Minuten aufsetzen. Alle Abhängigkeiten sind in den Docker Images bereits enthalten.

  • Als Standard-Datenbank ist MariaDB integriert.
  • Elasticsearch unterstützt die OTOBO-Schnellsuche.
  • Redis sorgt für schnelles Caching.
  • Gazelle dient als schneller Perl-Webserver.
  • nginx wird als optionaler Reverseproxy für die HTTPS-Unterstützung eingesetzt.

Wir denken: Das wird die perfekte Umgebung für eine OTOBO-Installation.

Technische Voraussetzungen

Hier sind die bisher getesteten Mindestanforderungen an die verwendete Software aufgeführt:

  • Docker 19.03.13
  • Docker Compose 1.25.0
  • Git 2.17.1

git, Docker und Docker Compose können mit den Standard-Systemtools installiert werden. Ein Beispiel für die Installation unter Ubuntu 20.04:

root> apt-get install git docker docker-compose
root> systemctl enable docker

Informationen zum weiteren Septup entnehmen Sie bitte der Git- und Docker-Dokumentation.

Installation

Wir gehen im Folgenden davon aus, dass alle erforderlichen Softwaremodule installiert sind und eine funktionierende Docker-Umgebung zur Verfügung steht. Außerdem, dass zur Interaktion mit Docker der Benutzer docker_admin verwendet wird. Der Docker-Admin kann entweder der root-Benutzer des Docker-Host oder ein spezieller Benutzer mit den erforderlichen Berechtigungen sein.

1. Clone the otobo-docker repo

Die Docker Images werden letztlich aus dem Image Repository https://hub.docker.com heruntergeladen. Doch einige Einstellungs- und Befehlsdateien müssen aus dem otobo-docker-Github-Repository geklont werden. Achten Sie hierbei darauf, dass der ausgewählte Branch der aktuellsten OTOBO-Version entspricht. Ein Beispiel: Ist OTOBO 10.0.10 die aktuelle Version, verwenden Sie den Branch rel-10_0.

Bemerkung

Wo das geklonte Repository liegt, spielt keine Rolle. In dieser Anleitung wählen wir /opt/otobo-docker als Arbeitsverzeichnis.

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo-docker.git --branch <BRANCH> --single-branch
docker_admin> ls otobo-docker    # just a sanity check, README.md should exist

2. Create an initial .env file

In der Docker Compose Konfigurationsdatei .env werden die Einstellungen für die OTOBO-Umgebung vorgenommen. Diese Datei muss von Ihnen erstellt und individualisiert werden. Um Ihnen die Aufgabe zu erleichtern, werden zwei Beispieldateien mitausgeliefert, die Sie als Ausgangspunkt verwenden können. Soll per HTTPS auf die OTOBO Webapplikation via HTTPS zugegriffen werden, verwenden Sie bitte .docker_compose_env_https. Wir empfehlen, über HTTPS zuzugreifen. Wird kein HTTPS benötigt, verwenden Sie .docker_compose_env_http als Ausgangspunkt.

.docker_compose_env_http
Die OTOBO Oberfläche ist über HTTP erreichbar.
.docker_compose_env_https
Die OTOBO Oberfläche ist über Nginx als Reverse-Proxy per HTTPS erreichbar.
.docker_compose_env_https_custom_nginx
Ähnlich zu .docker_compose_env_https, aber mit Unterstützung einer individuellen Nginx Konfiguration.
.docker_compose_env_https_kerberos
Ähnlich zu .docker_compose_env_https, aber mit Beispiel Konfiguration für Single-Sign-On.
.docker_compose_env_http_selenium und .docker_compose_env_https_selenium
Diese werden nur für Entwicklungszwecke genutzt, wenn Selenium Tests aktiviert sind.

Bemerkung

ls -a zeigt die ausgeblendete Template-Dateien an.

In der Grundeinstellung erfolgt die Verbindung zu OTOBO über die Standardports: Port 443 für HTTPS und Port 80 für HTTP. Auch bei aktiviertem HTTPS, läuft die OTOBO Webapplikation via HTTP. Die HTTPS-Unterstützung erfolgt über einen zusätzlichen Reverseproxy, der als nginx-Service vorgeschaltet wird.

Für die folgenden Befehle gehen wir davon aus, dass HTTPS unterstützt werden soll.

docker_admin> cd /opt/otobo-docker
docker_admin> cp -p .docker_compose_env_https .env # or .docker_compose_env_http for HTTP

3. Configure the password for the database admin user

Ändern Sie folgenden Wert in der .env-Datei:

OTOBO_DB_ROOT_PASSWORD=<Ihr_geheimes_Passwort>

Das Passwort für den Datenbankadministrator ist frei wählbar. Dieser wird benötigt, um den Datenbankbenutzer otobo und das Datenbankschema otobo anzulegen.

4. Set up a volume with SSL configuration for the nginx webproxy (optional)

Dieser Schritt kann entfallen, wenn nur per HTTP auf OTOBO zugegriffen werden soll.

nginx erfordert für die SSL-Verschlüsselung ein Zertifikat sowie einen privaten Schlüssel.

Bemerkung

Für Testzwecke und beim Entwickeln kann ein selbst signiertes Zertifikat verwendet werden. Grundsätzlich sind jedoch offizielle Zertifikate erforderlich.

Mehr dazu, wie Sie ein selbst signiertes Zertifikat erstellen, erfahren Sie z. B. unter https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-18-04.

Bemerkung

Um in nginx eine CA-Chain zusammen mit einem Zertifikat anzugeben, muss das CA-Chain-File mit dem eigentlichen Zertifikat in eine Datei kopiert werden.

Das Zertifikat und der private Schlüssel werden in einem Volume hinterlegt, um später von nginx verwendet werden zu können. Legen Sie zunächst das Volume an und kopieren Sie anschließend Zertifikat und Schlüssel hinein:

docker_admin> docker volume create otobo_nginx_ssl
docker_admin> otobo_nginx_ssl_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl)
docker_admin> echo $otobo_nginx_ssl_mp  # just a sanity check
docker_admin> cp /PathToYourSSLCert/ssl-cert.crt /PathToYourSSLCert/ssl-key.key $otobo_nginx_ssl_mp

Die Namen der kopierten Dateien müssen in die eben angelegte .env-Datei eingegeben werden. Beispiel:

OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/ssl-cert.crt und OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/ssl-key.key

Bitte passen Sie nur die Dateinamen an. Der Pfad /etc/nginx/ssl/ ist im Docker Image festgeschrieben.

5. Start the Docker containers with Docker Compose

Jetzt starten wir die Docker Container mit docker-compose. Standardmäßig werden die Docker Images von https://hub.docker.com/u/rotheross heruntergeladen.

docker_admin> docker-compose up --detach

Geben Sie folgende Befehle ein, um sicherzustellen, dass die sechs erforderlichen Dienste (fünf, wenn nur HTTP verwendet werden soll) wirklich laufen :

docker_admin> docker-compose ps
docker_admin> docker volume ls

6. Install and start OTOBO

Führen Sie den OTOBO Installer von http://IhreIPoderFQDN/otobo/installer.pl aus.

Bemerkung

Konfigurieren Sie OTOBO im Installer mit einer neuen MySQL-Datenbank. Geben Sie als Root-Passwort für die MySQL-Datenbank das Passwort ein, das Sie für die Variable OTOBO_DB_ROOT_PASSWORD in die .env-Datei eingegeben haben. Bitte behalten Sie den Wert db für den MySQL-Hostnamen unverändert bei.

Viel Vergnügen mit OTOBO!

Bemerkung

Um im laufenden Container in das OTOBO-Verzeichnis zu wechseln und wie gewohnt in der Kommandozeile zu arbeiten, können Sie folgenden Docker-Befehl nutzen: docker-compose exec web bash.

Ergänzende technische Informationen

Dieser Abschnitt bietet einige Zusatzinformationen zu den technischen Hintergründen.

Liste der Docker Container

Container otobo_web_1
OTOBO-Webserver über den internen Port 5000.
Container otobo_daemon_1
OTOBO Daemon. Der OTOBO Daemon wird gestartet und regelmäßig geprüft.
Container otobo_db_1
Betreibt die Datenbank MariaDB über den internen Port 3306.
Container otobo_elastic_1
Elasticsearch über die internen Ports 9200 und 9300.
Container otobo_redis_1
Betreibt Redis als Caching-Dienst.
Optionaler Container otobo_nginx_1
Setzt nginx als Reverseproxy für HTTPS-Verbindungen ein.

Übersicht über die Docker Volumes

Die Docker Volumes werden auf dem Host erstellt, um persistente Daten darin zu speichern. So können die Dienste ohne Datenverlust gestartet und gestoppt werden. Bedenken Sie, dass Container nur begrenzte Zeit verfügbar sind, Volumes dagegen dauerhaft.

otobo_opt_otobo
enthält /opt/otobo in den Containern web and daemon.
otobo_mariadb_data
beinhaltet /var/lib/mysql im Container db.
otobo_elasticsearch_data
enthält /usr/share/elasticsearch/datal im Container elastic.
otobo_redis_data
enthält Daten für den Container redis.
otobo_nginx_ssl
enthält die TLS-Dateien, das Zertifikat und den privaten Schlüssel. Muss von Hand initialisiert werden.

Docker-Umgebungsvariablen

Bisher haben wir nur das Nötigste konfiguriert. In der .env-Datei können weitere Konfigurationen vorgenommen werden. Im Folgenden finden Sie eine Auswahl der wichtigsten Umgebungsvariablen.

MariaDB Einstellungen

OTOBO_DB_ROOT_PASSWORD
Das Root-Passwort für MySQL. Ohne Root-Passwort kann die OTOBO DB nicht eingesetzt werden.

Elasticsearch Einstellungen

Damit Elasticsearch in Produktivumgebungen optimal läuft, sind einige Einstellungen vorzunehmen. Detaillierte Informationen entnehmen Sie bitte der Elasticsearch-Dokumentation unter https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites.

OTOBO_Elasticsearch_ES_JAVA_OPTS
Beispieleinstellung: OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m Bitte setzen Sie diesen Wert in Produktivumgebungen auf einen Wert bis 4g.

Webserver Einstellungen

OTOBO_WEB_HTTP_PORT
Hier sind Angaben nötig, falls der HTTP-Port vom Standardport 80 abweicht. Ist HTTPS aktiv, wird der HTTP-Port auf HTTPS umgeleitet.

Einstellungen für den nginx-Webproxy

Diese Einstellungen werden angewendet, wenn HTTPS aktiv ist.

OTOBO_WEB_HTTP_PORT
Hier sind Angaben nötig, falls der HTTP-Port vom Standardport 80 abweicht.
OTOBO_WEB_HTTPS_PORT
Bitte anpassen, falls der HTTPS-Port vom Standardport 443 abweicht.
OTOBO_NGINX_SSL_CERTIFICATE
SSL-Zertifikat für den nginx-Webproxy. Beispiel: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt
OTOBO_NGINX_SSL_CERTIFICATE_KEY
SSL-Schlüssel für den nginx-Webproxy. Beispiel: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Docker Compose-Einstellungen

Diese Einstellungen werden direkt von Docker Compose verwendet.

COMPOSE_PROJECT_NAME
Der Projektname wird als Präfix für die Docker Volumes und Container verwendet. Als Standardwert wird otobo verwendet, sodass die Container z.B. otobo_web_1 und otobo_db_1 heißen. Wenn Sie mehrere OTOBO Instanzen auf dem selben Server betreiben, passen Sie den Projektnamen bitte jeweils individuell an.
COMPOSE_PATH_SEPARATOR
Separator für die Werte im COMPOSE_FILE
COMPOSE_FILE
Verwenden Sie docker-compose/otobo-base.yml als Grundlage und ergänzen Sie die erforderlichen Extension Files wie docker-compose/otobo-override-http.yml oder docker-compose/otobo-override-https.yml.
OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, …
Werden verwendet, um alternative Docker Images zu deklarieren. Nützlich zum Testen lokaler Builds oder aktuellerer Versionen der Images.

Weiterführende Themen

Individuelle Konfiguration des nginx-Webproxy

Der Container otobo_nginx_1 bietet HTTPS Unterstützung über einen Nginx als Reverse Proxy. Das Docker Image des Containers besteht aus dem offiziellen Nginx Image, https://hub.docker.com/_/nginx, zusammen mit einer OTOBO spezifischen Nginx Konfiguration.

The default OTOBO specific configuration can be found within the Docker image at /etc/nginx/template/otobo_nginx.conf.template. Actually, this is only a template for the final configuration. There is a process, provided by the Nginx base image, that replaces the macros in the template with the corresponding environment variable. This process runs when the container starts up. In the default template file, the following macros are used:

OTOBO_NGINX_SSL_CERTIFICATE
Um SSL zu konfigurieren.
OTOBO_NGINX_SSL_CERTIFICATE_KEY
Um SSL zu konfigurieren.
OTOBO_NGINX_WEB_HOST
Der intern benutzte HTTP Hostname.
OTOBO_NGINX_WEB_PORT
Der intern benutzte HTTP Port.

Wie diese Konfigurationsmöglichkeit genutzt werden kann, um ein SSL-Zertifikat zu installieren, lesen Sie in Schritt 4..

Warnung

Der im Folgenden beschriebene Ansatz wird erst ab OTOBO 10.0.4 unterstützt.

When the standard macros are not sufficient, then the customisation can go further. This can be achieved by replacing the default config template with a customized version. It is best practice to not simple change the configuration in the running container. Instead we first create a persistent volume that contains the custom config. Then we tell the otobo_nginx_1 to mount the new volume and to use the customized configuration.

Zuerst muss ein neues Volume erstellt werden. In den Beispielbefehlen benutzen wir das bestehende Template als Ausgangspunkt.

# stop the possibly running containers
docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose down

# create a volume that is initially not connected to otobo_nginx_1
docker_admin> docker volume create otobo_nginx_custom_config

# find out where the new volume is located on the Docker host
docker_admin> otobo_nginx_custom_config_mp=$(docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_custom_config)
docker_admin> echo $otobo_nginx_custom_config_mp  # just a sanity check
docker_admin> ls $otobo_nginx_custom_config_mp    # another sanity check

# copy the default config into the new volume
docker_admin> docker create --name tmp-nginx-container rotheross/otobo-nginx-webproxy:latest  # use the appropriate label
docker_admin> docker cp tmp-nginx-container:/etc/nginx/templates/otobo_nginx.conf.template $otobo_nginx_custom_config_mp # might need 'sudo'
docker_admin> ls -l $otobo_nginx_custom_config_mp/otobo_nginx.conf.template # just checking, might need 'sudo'
docker_admin> docker rm tmp-nginx-container

# adapt the file $otobo_nginx_custom_config_mp/otobo_nginx.conf.template to your needs
docker_admin> vim $otobo_nginx_custom_config_mp/otobo_nginx.conf.template

Warnung

Die angepasste nginx-Konfiguration enthält in der Regel die Anweisung listen, in der die Ports für den Webserver definiert werden. Die internen Ports haben sich von OTOBO 10.0.3 zu OTOBO 10.0.4 geändert. Diese Veränderung muss in die nginx-Konfiguration übernommen werden. In Version 10.0.3 und früher lauscht OTOBO auf den Ports 80 und 443. In OTOBO 10.0.4 sind es die Ports 8080 und 8443.

After setting up the volume, the adapted configuration must be activated. The new volume is set up in docker-compose/otobo-nginx-custom-config.yml. Therefore this file must be added to COMPOSE_FILE. Then Nginx must be directed to use the new config. This is done by setting NGINX_ENVSUBST_TEMPLATE_DIR in the environment. In order to achieve this, uncomment or add the following lines in your .env file:

COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml:docker-compose/otobo-nginx-custom-config.yml
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom

Verwenden Sie den folgenden Befehl, um Informationen zur angepassten Docker-Compose-Konfiguration anzuzeigen:

docker_admin> docker-compose config | more

Schließlich können Sie die Container wieder starten:

docker_admin> docker-compose up --detach

Weitere Informationen dazu finden Sie auf https://hub.docker.com/_/nginx im Abschnitt zur Verwendung von Umgebungsvariablen in der nginx-Konfiguration („Using environment variables in nginx configuration (new in 1.19)“).

Individuelle Ports definieren

Standardmäßig nutzt OTOBO die Ports 443 und 80 für HTTPS und HTTP. In manchen Systemen werden dieses Ports jedoch bereits von anderen Diensten verwendet. In diesem Fall können Sie über die Variablen OTOBO_WEB_HTTP_PORT und OTOBO_WEB_HTTPS_PORT in der .env-Datei andere Ports definieren.

Docker Image individualisieren

Viele Anpassungen können im externen Volume otobo_opt_otobo vorgenommen werden, das dem Verzeichnis /opt/otobo im Docker Image entspricht. So können Sie z. B. lokale Perl-Module in /opt/otobo/local installieren. Der Vorteil dieser Vorgehensweise besteht darin, dass das Image selbst dabei nicht verändert wird.

Zusätzliche Debian-Pakete zu installieren ist etwas aufwändiger. Sie können dazu entweder ein individuelles Dockerfile auf Grundlage des OTOBO Image erzeugen. Oder Sie erstellen das angepasste Image direkt aus einem laufenden Container heraus. Nutzen Sie dazu den Befehl docker commit – mehr dazu unter https://docs.docker.com/engine/reference/commandline/commit/. Eine gute Anleitung mit Beispielen (auf Englisch) finden Sie auch unter https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.

But for the latter approach there are two hurdles to overcome. First, the image otobo runs per default as the user otobo with the UID 1000. The problem is that the user otobo is not allowed to install system packages. Thus, the first part of the solution is to pass the option –user root when running the image. However the second hurdle is that the default entrypoint script /opt/otobo_install/entrypoint.sh exits immediately when it is called as root. The reasoning behind that design decision is that running inadvertently as root should be discouraged. So, the second part of the solution is to specify a different entrypoint script that does not care who the caller is. This leaves us with following example commands, where we add fortune cookies to otobo:

Pullen Sie ein getaggtes OTOBO Image (sofern nicht bereits vorhanden), und prüfen Sie, ob im Image schon Fortune Cookies bereitgestellt werden:

$ docker run rotheross/otobo:rel-10_0_10 /usr/games/fortune
/opt/otobo_install/entrypoint.sh: line 57: /usr/games/fortune: No such file or directory

Ergänzen Sie die Fortune Cookies in einem benannten Container im originalen OTOBO Image. Dazu nutzen wir eine interaktive Session und den User root:

$ docker run -it --user root --entrypoint /bin/bash --name otobo_orig rotheross/otobo:rel-10_0_10
root@50ac203409eb:/opt/otobo# apt update
root@50ac203409eb:/opt/otobo# apt install fortunes
root@50ac203409eb:/opt/otobo# exit
$ docker ps -a | head

Erzeugen Sie ein Image auf Basis des gestoppten Containers und vergeben Sie einen Namen. Beachten Sie, dass der Standardbenutzer und das Entrypoint-Skript wiederhergestellt werden müssen:

$ docker commit -c 'USER otobo'  -c 'ENTRYPOINT ["/opt/otobo_install/entrypoint.sh"]' otobo_orig otobo_with_fortune_cookies

Schließlich prüfen wir, ob alles funktioniert hat:

$ docker run otobo_with_fortune_cookies /usr/games/fortune
A platitude is simply a truth repeated till people get tired of hearing it.
                -- Stanley Baldwin

Das modifizierte Image kann in Ihrer .env-Datei angegeben und frei verwendet werden.

Lokale Images erstellen

Bemerkung

Lokale Docker Images werden in der Regel nur zur Entwicklung erstellt. Weitere Anwendungsfälle sind z.B. wenn aktuellere Basis Images benötigt werden oder wenn Images um zusätzliche Funktionalität erweitert werden sollen.

Die zum Erstellen lokaler Docker Images benötigten Dateien finden Sie im Git Repository unter https://github.com/RotherOSS/otobo:

  • otobo.web.dockerfile
  • otobo.nginx.dockerfile
  • otobo.elasticsearch.dockerfile

Das Script zum Erstellen der Images finden Sie unter bin/docker/build_docker_images.sh.

docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo.git
docker_admin> # checkout the wanted branch. e.g. git checkout rel-10_0_11
docker_admin> cd otobo
docker_admin> # modify the docker files if necessary
docker_admin> bin/docker/build_docker_images.sh
docker_admin> docker image ls

Lokal erstellte Images werden auf Basis der in der Datei RELEASE angegebenen Versionsdaten als local-<OTOBO_VERSION> getaggt.

Nach dem Erstellen der lokalen Images können Sie in das docker-compose Verzeichnis zurückkehren. Neu erstellte Images können mit den entsprechenden Vorgaben in OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX in .env ausgewählt werden.

Automatische Installation

Anstatt die URL http://yourIPorFQDN/otobo/installer.pl zu verwenden, können Sie auch eine Abkürzung wählen. Diese Möglichkeit eignet sich besonders, um die Testsuite auf einem frisch installierten System laufen zu lassen.

Warnung

docker-compose down -v löscht alle vorhandenen Einstellungen und Daten.

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

Einige nützliche Befehle

Docker

  • docker system prune -a Systembereinigung (entfernt alle unbenutzten Images, Container, Volumes, Netzwerke)
  • docker version Version anzeigen
  • docker build --tag otobo --file=otobo.web.Dockerfile . Image erstellen
  • docker run --publish 80:5000 otobo Neues Image ausführen
  • docker run -it -v opt_otobo:/opt/otobo otobo bash Login auf neuem Image
  • docker run -it -v opt_otobo:/opt/otobo --entrypoint bash otobo falls das Skript entrypoint.sh nicht funktioniert
  • docker ps Laufende Images anzeigen
  • docker images Verfügbare Images anzeigen
  • docker volume ls Volumes auflisten
  • docker volume inspect otobo_opt_otobo Informationen über ein Volume ausgeben
  • docker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl Volume Mountpoint ausgeben
  • docker volume rm tmp_volume Volume entfernen
  • docker inspect <container> Informationen zu einem Container anzeigen
  • docker save --output otobo.tar otobo:latest && tar -tvf otobo.tar Liste aller Dateien in einem Image anzeigen
  • docker exec -it nginx-server nginx -s reload nginx-Reload

Docker Compose

  • docker-compose config Informationen zur Konfiguration anzeigen
  • docker-compose ps Informationen zu laufenden Containern anzeigen
  • docker-compose exec nginx nginx -s reload nginx-Reload