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
Bemerkung
Um die benötigten Versionen für Ubuntu 18.04 zu installieren, folgen Sie den Anweisungen unter https://www.digitalocean.com/community/tutorials/how-to-install-docker-compose-on-ubuntu-18-04 und https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-18-04.
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 von 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 das Git-Tag der aktuellsten OTOBO-Version entspricht. Ein Beispiel: Ist OTOBO 10.0.6 die aktuelle Version, verwenden Sie den Branch rel-10_0_6.
Bemerkung
Diese Anleitung wurde noch vor OTOBO 10.0.4 veröffentlicht. Das Git Label rel-10.0.4 ist also vielleicht noch gar nicht verfügbar.
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.
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
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, dass 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 exec -it otobo_web_1 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 und 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. Folgende Umgebungsvariablen werden unterstützt:
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 angelegten Volumes und Container verwendet. Hier ist eine Angabe erforderlich, weil das Compose-File in scripts/docker-compose abgelegt wird und sonst standardmäßig docker-compose verwendet würde.
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.
Weiterführende Themen¶
Individuelle Konfiguration des nginx-Webproxy¶
Die Docker-basierte OTOBO-Standardinstallation enthält den Container otobo_nginx_1. Dieser Container stellt die HTTPS-Unterstützung für die grundsätzlich HTTP-basierte Webapplikation OTOBO bereit. Sie finden das Config-Template für nginx im Docker Image in der Datei /etc/nginx/template/otobo_nginx.conf.template. Beim Start des Containers wird aus diesem Template die schließlich verwendete Konfigurationsdatei generiert. Dazu wird jedes Makro in der Datei durch die zugehörige Umgebungsvariable ersetzt. In der Standard-Template-Datei werden lediglich folgende Makros verwendet: * ${OTOBO_NGINX_SSL_CERTIFICATE} * ${OTOBO_NGINX_SSL_CERTIFICATE_KEY} * `${OTOBO_NGINX_WEB_HOST} * ${OTOBO_NGINX_WEB_PORT}
Es gibt verschiedene Möglichkeiten, die nginx-Konfiguration anzupassen. Eine besteht darin, ein lokal erstelltes Image auf Basis des Image otobo-nginx-webproxy zu verwenden. In einem solchen lokalen Image können Sie nginx sehr flexibel konfigurieren.
Warnung
Der im Folgenden beschriebene Ansatz wird erst ab OTOBO 10.0.4 unterstützt.
Diese weitere Möglichkeit besteht darin, das Standard-Config-Template mit einer individualisierten Version zu überschreiben. Dazu erstellen wir zunächst ein Volume mit einem angepassten nginx-Config-Template.
docker_admin> cd /opt/otobo-docker
docker_admin> docker-compose down
docker_admin> docker volume create otobo_nginx_custom_config
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> 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
docker_admin> # adapt the file $otobo_nginx_custom_config_mp/otobo_nginx.conf.template to your needs
docker_admin> docker-compose up --detach
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.
Ist das Volume angelegt, aktivieren Sie die angepasste Konfiguration. Löschen Sie hierzu die Auskommentierung vor den folgenden Zeilen oder ergänzen Sie diese in Ihrer .env-Datei:
NGINX_ENVSUBST_TEMPLATE_DIR=/etc/nginx/config/template-custom
COMPOSE_FILE=docker-compose/otobo-base.yml:docker-compose/otobo-override-https.yml:docker-compose/otobo-nginx-custom-config.yml
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.
Lokale Images erstellen¶
Bemerkung
Lokale Docker Images werden in der Regel nur zur Entwicklung erstellt.
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
- bin/docker/build_docker_images.sh
docker_admin> cd /opt
docker_admin> git clone https://github.com/RotherOSS/otobo.git
docker_admin> cd otobo
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. 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 schnelle Lösung 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 stop otobo_daemon_1
docker_admin> docker exec -t --user otobo otobo_web_1 bash\
-c "rm -f Kernel/Config/Files/ZZZAAuto.pm ; bin/docker/quick_setup.pl --db-password otobo_root"
docker_admin> docker exec -t --user otobo otobo_web_1 bash\
-c "bin/docker/run_test_suite.sh"
.......
docker_admin> docker start otobo_daemon_1
Einige nützliche Befehle¶
Docker
docker system prune -a
Systembereinigung (entfernt alle unbenutzten Images, Container, Volumes, Netzwerke)docker version
Version anzeigendocker build --tag otobo --file=otobo.web.Dockerfile .
Image erstellendocker run --publish 80:5000 otobo
Neues Image ausführendocker run -it -v opt_otobo:/opt/otobo otobo bash
Login auf neuem Imagedocker run -it -v opt_otobo:/opt/otobo --entrypoint bash otobo
falls das Skript entrypoint.sh nicht funktioniertdocker ps
Laufende Images anzeigendocker images
Verfügbare Images anzeigendocker volume ls
Volumes auflistendocker volume inspect otobo_opt_otobo
Informationen über ein Volume ausgebendocker volume inspect --format '{{ .Mountpoint }}' otobo_nginx_ssl
Volume Mountpoint ausgebendocker volume rm tmp_volume
Volume entfernendocker inspect <container>
Informationen zu einem Container anzeigendocker save --output otobo.tar otobo:latest && tar -tvf otobo.tar
Liste aller Dateien in einem Image anzeigendocker exec -it nginx-server nginx -s reload
nginx-Reload
Docker Compose
docker-compose config
Informationen zur Konfiguration anzeigendocker-compose ps
Informationen zu laufenden Containern anzeigen
Ressourcen¶
- Perl Maven
- Docker Compose-Schnellstart
- Neuere Docker-Compose-Version unter Ubuntu 18.04 LTS installieren
- Neuere Docker-Version unter Ubuntu 18.04 LTS installieren
- docker-otrs
- Cleanup
- Dockerfile Best Practices
- Docker Cache Entwertung
- Docker Host IP
- Umgebung
- Selbstsigniertes Zertifikat erstellen
- Informationen zu fehlgeschlagenen Builds