Zaawansowana instalacja OTOBO z Docker Compose

Ta sekcja zawiera dodatkowe informacje techniczne dotyczące działania wewnętrznych mechanizmów.

::: version Lista kontenerów Docker; 10+ Kontener otobo_web_1 : Serwer WWW OTOBO na wewnętrznym porcie 5000.

Kontener otobo_daemon_1 : Demon OTOBO. Demon OTOBO jest uruchamiany i cyklicznie monitorowany.

Kontener otobo_db_1 : Uruchamia bazę danych MariaDB na wewnętrznym porcie 3306.

Kontener otobo_elastic_1 : Elasticsearch na wewnętrznych portach 9200 i 9300.

Kontener otobo_redis_1 : Uruchamia Redis jako usługę buforowania.

Opcjonalny kontener otobo_nginx_1 : Uruchamia nginx jako reverse proxy w celu zapewnienia obsługi HTTPS. :::

::: version Lista kontenerów Docker; 11 Kontener otobo-web-1 : Serwer WWW OTOBO na wewnętrznym porcie 5000.

Kontener otobo-daemon-1 : Demon OTOBO. Demon OTOBO jest uruchamiany i cyklicznie monitorowany.

Kontener otobo-db-1 : Uruchamia bazę danych MariaDB na wewnętrznym porcie 3306.

Kontener otobo-elastic-1 : Elasticsearch na wewnętrznych portach 9200 i 9300.

Kontener otobo-redis-1 : Uruchamia Redis jako usługę buforowania.

Opcjonalny kontener otobo-nginx-1 : Uruchamia nginx jako reverse proxy w celu zapewnienia obsługi HTTPS. :::

Przegląd woluminów Docker

Woluminy Docker są tworzone na hoście w celu zapewnienia trwałości danych. Pozwalają one na uruchamianie i zatrzymywanie usług bez utraty danych. Należy pamiętać, że kontenery są tymczasowe, a trwałe dane przechowywane są wyłącznie w woluminach.

otobo_opt_otobo : zawiera katalog /opt/otobo w kontenerach web i daemon.

otobo_mariadb_data : zawiera katalog /var/lib/mysql w kontenerze db.

otobo_elasticsearch_data : zawiera katalog /usr/share/elasticsearch/data w kontenerze elastic.

otobo_redis_data : zawiera dane dla kontenera redis.

otobo_nginx_ssl : zawiera pliki TLS, certyfikat i klucz prywatny, które należy zainicjować ręcznie.

Zmienne środowiskowe Docker

W instrukcjach wykonaliśmy jedynie minimalną konfigurację. Jednak plik .env pozwala na ustawienie większej liczby zmiennych. Poniżej znajduje się krótki przegląd najważniejszych zmiennych środowiskowych. Należy pamiętać, że obrazy bazowe obsługują więcej zmiennych środowiskowych.

Ustawienia MariaDB

OTOBO_DB_ROOT_PASSWORD : Hasło root dla MariaDB. To ustawienie jest wymagane do działania usługi db.

Ustawienia Elasticsearch

Elasticsearch wymaga dodatkowych ustawień w środowiskach produkcyjnych. Szczegółowe informacje dostępne są pod adresem: https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites.

OTOBO_Elasticsearch_ES_JAVA_OPTS : Przykładowe ustawienie: OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m. W środowiskach produkcyjnych zaleca się dostosowanie tej wartości do maksymalnie 4g.

Ustawienia serwera WWW

OTOBO_WEB_HTTP_PORT : Ustaw tę wartość, jeśli port HTTP ma się różnić od domyślnego portu 80. Gdy HTTPS jest włączone, port HTTP przekierowuje na HTTPS.

Ustawienia proxy WWW Nginx : Te ustawienia są używane, gdy włączone jest HTTPS.

OTOBO_WEB_HTTP_PORT : Ustaw tę wartość, jeśli port HTTP ma się różnić od domyślnego portu 80. Przekierowuje na HTTPS.

OTOBO_WEB_HTTPS_PORT : Ustaw tę wartość, jeśli port HTTPS ma się różnić od domyślnego portu 443.

OTOBO_NGINX_SSL_CERTIFICATE : Certyfikat SSL dla proxy WWW Nginx. Przykład: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Klucz SSL dla proxy WWW Nginx. Przykład: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Ustawienia Nginx dla Kerberos : Te ustawienia są używane przez Nginx, gdy Kerberos jest stosowany do Single Sign-On.

OTOBO_NGINX_KERBEROS_KEYTAB : Plik keytab Kerberos. Domyślnie: /etc/krb5.keytab.

OTOBO_NGINX_KERBEROS_CONFIG : Plik konfiguracyjny Kerberos. Domyślnie: /etc/krb5.conf, zazwyczaj generowany z pliku krb5.conf.template.

OTOBO_NGINX_KERBEROS_SERVICE_NAME : Nazwa usługi Kerberos. Nie jest jasne, gdzie dokładnie ta opcja jest używana.

OTOBO_NGINX_KERBEROS_REALM : Realm Kerberos. Używany w pliku /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_KDC : Serwer KDC Kerberos / kontroler AD. Używany w pliku /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_ADMIN_SERVER : Serwer administracyjny Kerberos. Używany w pliku /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN : Domyślna domena Kerberos. Używana w pliku /etc/krb5.conf.

NGINX_ENVSUBST_TEMPLATE_DIR : Określa niestandardowy katalog szablonów konfiguracyjnych Nginx. Zapewnia dodatkową elastyczność.

Ustawienia Docker Compose : Te ustawienia są używane bezpośrednio przez Docker Compose.

COMPOSE_PROJECT_NAME : Nazwa projektu używana jako prefiks dla woluminów i kontenerów. Domyślnie ustawiona na otobo, co daje nazwy kontenerów takie jak otobo_web_1 i otobo_db_1. Zmień tę nazwę, jeśli chcesz uruchamiać więcej niż jedną instancję OTOBO na tym samym serwerze.

COMPOSE_PATH_SEPARATOR : Separator dla wartości zmiennej COMPOSE_FILE.

COMPOSE_FILE : Użyj docker-compose/otobo-base.yml jako podstawy i dodaj żądane pliki rozszerzeń. Na przykład: docker-compose/otobo-override-http.yml lub docker-compose/otobo-override-https.yml.

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, \... : Używane do określania alternatywnych obrazów Docker. Przydatne do testowania lokalnych kompilacji lub używania zaktualizowanych wersji obrazów.

Niestandardowa konfiguracja proxy WWW Nginx

Kontener otobo_nginx_1 zapewnia obsługę HTTPS poprzez uruchomienie Nginx jako reverse proxy. Obraz Docker używany w kontenerze opiera się na oficjalnym obrazie Nginx: https://hub.docker.com/_/nginx, z dodatkową konfiguracją specyficzną dla OTOBO. Domyślna konfiguracja OTOBO znajduje się w obrazie Docker pod ścieżką /etc/nginx/template/otobo_nginx.conf.template. W rzeczywistości jest to jedynie szablon dla końcowej konfiguracji. Istnieje proces dostarczany przez obraz bazowy Nginx, który podczas uruchamiania kontenera zastępuje makra w szablonie odpowiednimi zmiennymi środowiskowymi. W domyślnym pliku szablonu używane są następujące makra:

OTOBO_NGINX_SSL_CERTIFICATE : Do konfiguracji SSL.

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Do konfiguracji SSL.

OTOBO_NGINX_WEB_HOST : Wewnętrzny host HTTP.

OTOBO_NGINX_WEB_PORT : Wewnętrzny port HTTP.

Zobacz krok [4.] w celu wykorzystania tej możliwości konfiguracyjnej do ustawienia certyfikatu SSL.

Jeśli domyślne makra nie są wystarczające, można dokonać dalszych dostosowań, zastępując domyślny szablon niestandardową wersją. Dobrą praktyką jest nie modyfikowanie konfiguracji bezpośrednio w działającym kontenerze. W poniższych przykładach użyjemy istniejącego szablonu jako punktu wyjścia.

cd /opt/otobo-docker
mkdir nginx
docker cp otobo_nginx_1:/etc/nginx/conf.d/otobo_nginx.conf /opt/otobo-docker/nginx/otobo_nginx.conf
docker exec otobo_nginx_1 rm /etc/nginx/conf.d/otobo_nginx.conf

Dodaj następującą linię do pliku docker-compose/otobo-override-https.yml:

volumes:
  - /opt/otobo-docker/nginx/otobo_nginx.conf:/opt/otobo-docker/nginx/otobo_nginx.conf

Możesz użyć swojego ulubionego edytora tekstu z Putty lub WinSCP.

nano docker-compose/otobo-override-https.yml

Teraz możesz edytować plik /opt/otobo-docker/nginx/otobo_nginx.conf. Aby zastosować zmiany, kontenery należy ponownie uruchomić:

docker-compose up -d --build

Single Sign-On z obsługą Kerberos w Nginx

Aby włączyć uwierzytelnianie Kerberos, należy opierać się na pliku .env przygotowanym na podstawie przykładu .docker_compose_env_https_kerberos. To aktywuje specjalną konfigurację w pliku docker-compose/otobo-override-https-kerberos.yml. Ta Docker Compose konfiguracja wybiera obraz Nginx z obsługą Kerberos oraz przekazuje kilka ustawień specyficznych dla Kerberos jako zmienne środowiskowe do działającego kontenera Nginx. Wartości tych ustawień można określić w pliku .env, jak zwykle. Większość z nich służy jako wartości zastępcze dla szablonu: https://github.com/RotherOSS/otobo/blob/rel-10_1/scripts/nginx/kerberos/templates/krb5.conf.template. Zastąpienie odbywa się podczas uruchamiania kontenera. W działającym kontenerze dostosowana konfiguracja jest dostępna pod ścieżką /etc/krb5.conf. Możliwe jest również dostarczenie niestandardowego pliku /etc/krb5.conf poprzez zamontowanie woluminu, który nadpisze ten plik w kontenerze. Można to osiągnąć poprzez ustawienie zmiennej OTOBO_NGINX_KERBEROS_CONFIG w pliku .env oraz aktywację dyrektywy mount w pliku docker-compose/otobo-override-https-kerberos.yml. Plik /etc/krb5.keytab jest zawsze specyficzny dla instalacji i musi być zawsze montowany z systemu hosta.
Instrukcja instalacji Kerberos SSO
sso-kerberos

Użycie niestandardowych portów

Domyślnie porty 443 i 80 obsługują odpowiednio HTTPS i HTTP. Mogą wystąpić przypadki, w których jeden lub oba porty są już używane przez inne usługi. W takich sytuacjach domyślne porty można nadpisać, ustawiając OTOBO_WEB_HTTP_PORT i OTOBO_WEB_HTTPS_PORT w pliku .env.

Pomijanie uruchamiania wybranych usług

Obecna konfiguracja Docker Compose uruchamia pięć usług (lub sześć, jeśli włączone jest HTTPS). Istnieją jednak przypadki użycia, w których jedna lub więcej z tych usług nie jest potrzebna. Głównym przykładem jest sytuacja, gdy baza danych ma być uruchomiona jako usługa zewnętrzna, a nie jako kontener Docker.

docker-compose up -d web nginx daemon redis elastic

Oczywiście tego samego efektu można również osiągnąć, edytując plik docker-compose/otobo-base.yml i usuwając odpowiednie definicje usług.

Dostosowywanie OTOBO Docker Compose

Zamiast edytować pliki w katalogu docker-compose/ i ryzykować nadpisanie własnych ustawień podczas kolejnej aktualizacji folderu otobo-docker, zaleca się utworzenie dodatkowego pliku YAML, w którym można nadpisać konkretne usługi z dodatkowymi opcjami. Typowym przykładem jest udostępnienie kontenera bazy danych z zewnątrz przez port 3306. Można w tym celu utworzyć dodatkowy plik Docker Compose o następującej treści:

cat custom_db.yml
services:
  db:
    ports:
      - "0.0.0.0:3306:3306"

Teraz należy poinformować docker-compose, aby uwzględnił nowy plik. W tym celu należy dodać plik YAML do zmiennej COMPOSE_FILE w pliku .env, na przykład:

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

Teraz możemy użyć docker-compose do ponownego utworzenia kontenerów:

docker-compose stop
docker-compose up -d

Tą metodą można dostosować dowolną usługę lub wolumin.

Dostosowywanie obrazu Docker OTOBO

Wiele dostosowań można wykonać w zewnętrznym woluminie otobo_opt_otobo, odpowiadającym katalogowi /opt/otobo w obrazie Docker. Działa to np. dla lokalnych modułów Perl, które mogą być instalowane w katalogu /opt/otobo/local. Poniżej przykład instalacji mało przydatnego modułu CPAN Acme::123.

docker exec -it ${COMPOSE_PROJECT_NAME:=otobo}_web_1 bash
pwd

/opt/otobo

cpanm -l local Acme::123

--> Working on Acme::123

Fetching http://www.cpan.org/authors/id/N/NA/NATHANM/Acme-123-0.04.zip ... OK
Configuring Acme-123-0.04 ... OK
Building and testing Acme-123-0.04 ... OK
Successfully installed Acme-123-0.04
1 distribution installed

Zaletą tego podejścia jest to, że sam obraz Docker nie musi być modyfikowany.
Instalacja dodatkowych pakietów Debiana jest nieco trudniejsza. Jednym ze sposobów jest utworzenie niestandardowego Dockerfile z wykorzystaniem obrazu OTOBO jako obrazu bazowego. Innym podejściem jest bezpośrednie utworzenie zmodyfikowanego obrazu z działającego kontenera, co można zrobić za pomocą polecenia docker commit: https://docs.docker.com/engine/reference/commandline/commit/. Szczegółowy opis tej metody dostępny jest pod adresem: https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.
Dla drugiego podejścia istnieją dwa utrudnienia. Po pierwsze, obraz otobo domyślnie działa jako użytkownik otobo z UID 1000. Problem polega na tym, że użytkownik otobo nie ma uprawnień do instalowania pakietów systemowych. Pierwszą częścią rozwiązania jest więc użycie opcji --user root podczas uruchamiania kontenera. Drugim utrudnieniem jest to, że domyślne skrypt wejściowy /opt/otobo_install/entrypoint.sh natychmiast kończy działanie, gdy jest uruchamiany jako root. Ta decyzja projektowa ma na celu zapobieganie przypadkowemu uruchamianiu jako root. Drugą częścią rozwiązania jest więc określenie innego skryptu wejściowego, który nie sprawdza tożsamości użytkownika. Otrzymujemy wtedy następujące przykładowe polecenia, w których dodajemy do OTOBO ciasteczka losu (fortune cookies):

Pobierz oznaczony obraz OTOBO, jeśli jeszcze go nie masz, i sprawdź, czy obraz oferuje już ciasteczka losu:

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

Dodaj ciasteczka losu do nazwanego kontenera uruchamiającego oryginalny obraz OTOBO. Wykonaj to w sesji interaktywnej jako użytkownik root:

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

Utwórz obraz z zatrzymanego kontenera i nadaj mu nazwę. Należy pamiętać, że domyślny użytkownik i skrypt wejściowy muszą zostać przywrócone:

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

Na końcu możemy to przetestować:

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

Zmodyfikowany obraz można określić w pliku .env i używać go do zabawy i korzyści.

Tworzenie lokalnych obrazów

INFO

Tworzenie lokalnych obrazów Docker jest zazwyczaj potrzebne tylko podczas rozwoju. Inne przypadki użycia to użycie nowszych obrazów bazowych w instalacji lub dodanie dodatkowych funkcjonalności do obrazów.

Pliki Docker potrzebne do lokalnego budowania obrazów są częścią repozytorium git: https://github.com/RotherOSS/otobo:

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

Skrypt do rzeczywistego budowania obrazów to bin/docker/build_docker_images.sh.

cd /opt
git clone https://github.com/RotherOSS/otobo.git

Przejdź do odpowiedniego brancha, np.:

git checkout rel-10_0_11

cd otobo

W razie potrzeby zmodyfikuj pliki Docker:

bin/docker/build_docker_images.sh
docker image ls

Lokalnie zbudowane obrazy Docker są oznaczane jako local-<OTOBO_VERSION>, przy czym wersja pochodzi z pliku RELEASE.
Po utworzeniu lokalnych obrazów można wrócić do katalogu docker-compose. Lokalne obrazy są deklarowane poprzez ustawienie OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX w pliku .env.

Automatyczna instalacja

Zamiast przeprowadzać instalację przez http://yourIPorFQDN/otobo/installer.pl, można skorzystać ze skrótu. Jest to przydatne do uruchomienia testów na świeżej instalacji.

WARNING

docker-compose down -v usunie wszystkie poprzednie konfiguracje i dane.

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

Lista przydatnych poleceń

Docker

• docker system prune -a – czyszczenie systemu (usuwa wszystkie nieużywane obrazy, kontenery, woluminy, sieci)
• docker version – wyświetla wersję
• i wiele innych przydatnych poleceń Docker.

Docker Compose

• docker-compose config – sprawdza i wyświetla konfigurację
• docker-compose ps – wyświetla działające kontenery
• i inne przydatne polecenia Docker Compose.