Geavanceerde installatie van OTOBO met Docker Compose

Deze sectie biedt verdere technische inzichten in wat er onder water gebeurt.

::: version Lijst van Docker-containers; 10+ Container otobo_web_1 : OTOBO-webserver op intern poort 5000.

Container otobo_daemon_1 : OTOBO-daemon. De OTOBO-daemon wordt gestart en periodiek gecontroleerd.

Container otobo_db_1 : Voert de MariaDB-database uit op intern poort 3306.

Container otobo_elastic_1 : Elasticsearch op interne poorten 9200 en 9300.

Container otobo_redis_1 : Voert Redis uit als cachingdienst.

Optionele container otobo_nginx_1 : Voert nginx uit als reverse proxy voor HTTPS-ondersteuning. :::

::: version Lijst van Docker-containers; 11 Container otobo-web-1 : OTOBO-webserver op intern poort 5000.

Container otobo-daemon-1 : OTOBO-daemon. De OTOBO-daemon wordt gestart en periodiek gecontroleerd.

Container otobo-db-1 : Voert de MariaDB-database uit op intern poort 3306.

Container otobo-elastic-1 : Elasticsearch op interne poorten 9200 en 9300.

Container otobo-redis-1 : Voert Redis uit als cachingdienst.

Optionele container otobo-nginx-1 : Voert nginx uit als reverse proxy voor HTTPS-ondersteuning. :::

Overzicht van Docker-volumes

Docker-volumes worden op de host aangemaakt voor persistente gegevens. Dit maakt het mogelijk om diensten te starten en stoppen zonder gegevensverlies. Houd er rekening mee dat containers tijdelijk zijn en alleen gegevens in volumes permanent zijn.

otobo_opt_otobo : bevat /opt/otobo in de containers web en daemon.

otobo_mariadb_data : bevat /var/lib/mysql in de container db.

otobo_elasticsearch_data : bevat /usr/share/elasticsearch/data in de container elastic.

otobo_redis_data : bevat gegevens voor de container redis.

otobo_nginx_ssl : bevat de TLS-bestanden, certificaat en privésleutel, moet handmatig worden geïnitialiseerd.

Docker-omgevingsvariabelen

In de instructies hebben we slechts een minimale configuratie uitgevoerd. Maar het bestand .env stelt u in staat om meer variabelen in te stellen. Hieronder een korte lijst van de belangrijkste omgevingsvariabelen. Houd er rekening mee dat de basisafbeeldingen meer omgevingsvariabelen ondersteunen.

MariaDB-instellingen

OTOBO_DB_ROOT_PASSWORD : Het rootwachtwoord voor MariaDB. Deze instelling is vereist om de dienst db te kunnen uitvoeren.

Elasticsearch-instellingen

Elasticsearch vereist enkele instellingen voor productieomgevingen. Raadpleeg https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites voor gedetailleerde informatie.

OTOBO_Elasticsearch_ES_JAVA_OPTS : Voorbeeldinstelling: OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m. Pas deze waarde aan voor productieomgevingen tot maximaal 4g.

Webserver-instellingen

OTOBO_WEB_HTTP_PORT : Stel deze waarde in als de HTTP-poort afwijkt van de standaardpoort 80. Als HTTPS is ingeschakeld, wordt de HTTP-poort omgeleid naar HTTPS.

Nginx-webproxy-instellingen : Deze instellingen worden gebruikt wanneer HTTPS is ingeschakeld.

OTOBO_WEB_HTTP_PORT : Stel deze waarde in als de HTTP-poort afwijkt van de standaardpoort 80. Wordt omgeleid naar HTTPS.

OTOBO_WEB_HTTPS_PORT : Stel deze waarde in als de HTTPS-poort afwijkt van de standaardpoort 443.

OTOBO_NGINX_SSL_CERTIFICATE : SSL-certificaat voor de Nginx-webproxy. Voorbeeld: OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt

OTOBO_NGINX_SSL_CERTIFICATE_KEY : SSL-sleutel voor de Nginx-webproxy. Voorbeeld: OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Nginx-webproxy-instellingen voor Kerberos : Deze instellingen worden gebruikt door Nginx wanneer Kerberos wordt gebruikt voor Single Sign-On.

OTOBO_NGINX_KERBEROS_KEYTAB : Kerberos-keytabbestand. Standaard is dit /etc/krb5.keytab.

OTOBO_NGINX_KERBEROS_CONFIG : Kerberos-configuratiebestand. Standaard is dit /etc/krb5.conf, meestal gegenereerd uit krb5.conf.template.

OTOBO_NGINX_KERBEROS_SERVICE_NAME : Kerberos-servicenaam. Het is onduidelijk waar deze instelling daadwerkelijk wordt gebruikt.

OTOBO_NGINX_KERBEROS_REALM : Kerberos-REALM. Wordt gebruikt in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_KDC : Kerberos kdc / AD-controller. Wordt gebruikt in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_ADMIN_SERVER : Kerberos-beheerserver. Wordt gebruikt in /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN : Standaard Kerberos-domein. Wordt gebruikt in /etc/krb5.conf.

NGINX_ENVSUBST_TEMPLATE_DIR : Biedt een aangepaste Nginx-configuratie-sjabloonmap. Biedt extra flexibiliteit.

Docker Compose-instellingen : Deze instellingen worden direct gebruikt door Docker Compose.

COMPOSE_PROJECT_NAME : De projectnaam wordt gebruikt als voorvoegsel voor volumes en containers. Standaard is dit voorvoegsel ingesteld op otobo, wat resulteert in containernamen zoals otobo_web_1 en otobo_db_1. Wijzig deze naam als u meer dan één exemplaar van OTOBO op dezelfde server wilt uitvoeren.

COMPOSE_PATH_SEPARATOR : Scheidingsteken voor de waarde van COMPOSE_FILE.

COMPOSE_FILE : Gebruik docker-compose/otobo-base.yml als basis en voeg de gewenste uitbreidingsbestanden toe. Bijvoorbeeld docker-compose/otobo-override-http.yml of docker-compose/otobo-override-https.yml.

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, \... : Wordt gebruikt om alternatieve Docker-afbeeldingen op te geven. Handig voor het testen van lokale builds of het gebruik van bijgewerkte versies van afbeeldingen.

Aangepaste configuratie van de Nginx-webproxy

De container otobo_nginx_1 biedt HTTPS-ondersteuning door Nginx als reverse proxy uit te voeren. De Docker-afbeelding die in de container draait, bestaat uit de officiële Nginx Docker-afbeelding, https://hub.docker.com/_/nginx, samen met een OTOBO-specifieke Nginx-configuratie. De standaard OTOBO-specifieke configuratie bevindt zich binnen de Docker-afbeelding op /etc/nginx/template/otobo_nginx.conf.template. Dit is eigenlijk slechts een sjabloon voor de uiteindelijke configuratie. Er is een proces, geleverd door de Nginx-basisafbeelding, dat de macro's in de sjabloon vervangt door de bijbehorende omgevingsvariabelen. Dit proces wordt uitgevoerd wanneer de container start. In het standaardsjabloon worden de volgende macro's gebruikt:

OTOBO_NGINX_SSL_CERTIFICATE : Voor SSL-configuratie.

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Voor SSL-configuratie.

OTOBO_NGINX_WEB_HOST : De intern gebruikte HTTP-host.

OTOBO_NGINX_WEB_PORT : De intern gebruikte HTTP-poort.

Zie stap [4.] voor het gebruik van deze configuratiemogelijkheid voor het instellen van het SSL-certificaat.

Als de standaardmacro's niet voldoende zijn, kan de aanpassing verder worden doorgevoerd. Dit kan worden bereikt door de standaardsjabloon te vervangen door een aangepaste versie. Het is een aanbevolen praktijk om de configuratie niet eenvoudigweg in een actieve container te wijzigen. In deze voorbeeldopdrachten gebruiken we de bestaande sjabloon als uitgangspunt.

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

Voeg de volgende regel toe aan het bestand docker-compose/otobo-override-https.yml:

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

Hiervoor kunt u uw favoriete teksteditor gebruiken met Putty of WinSCP.

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

Nu kunt u het bestand /opt/otobo-docker/nginx/otobo_nginx.conf bewerken. Om de wijzigingen toe te passen, moeten de containers opnieuw worden gestart:

docker-compose up -d --build

Single Sign-On met Kerberos-ondersteuning in Nginx

Om Kerberos-authenticatie in te schakelen, baseer uw .env-bestand op het voorbeeldbestand .docker_compose_env_https_kerberos. Dit activeert de speciale configuratie in docker-compose/otobo-override-https-kerberos.yml. Deze Docker Compose-configuratie kiest een Nginx-afbeelding die Kerberos ondersteunt. Het geeft ook enkele Kerberos-specifieke instellingen door als omgevingsvariabelen aan de actieve Nginx-container. Deze instellingen zijn hierboven vermeld. Zoals gebruikelijk kunnen de waarden voor deze instellingen in het .env-bestand worden opgegeven. De meeste van deze instellingen worden gebruikt als vervangingswaarden voor de sjabloon https://github.com/RotherOSS/otobo/blob/rel-10_1/scripts/nginx/kerberos/templates/krb5.conf.template. De vervanging vindt plaats tijdens het opstarten van de container. In de actieve container is de aangepaste configuratie beschikbaar als /etc/krb5.conf. Het leveren van een gebruikersspecifiek /etc/krb5.conf-bestand is nog steeds mogelijk. Dit kan door een volume te koppelen dat /etc/krb5.conf in de container overschrijft. Dit kan worden bereikt door OTOBO_NGINX_KERBEROS_CONFIG in het .env-bestand in te stellen en de mount-instructie in docker-compose/otobo-override-https-kerberos.yml in te schakelen. /etc/krb5.keytab is altijd installatiespecifiek en moet daarom altijd van het hostsysteem worden gekoppeld.
Kerberos SSO-installatiehandleiding
sso-kerberos

Gebruik van niet-standaardpoorten

Standaard bedienen de poorten 443 en 80 respectievelijk HTTPS en HTTP. Er kunnen gevallen zijn waarin een of beide van deze poorten al in gebruik zijn door andere diensten. In dergelijke gevallen kunnen de standaardpoorten worden overschreven door OTOBO_WEB_HTTP_PORT en OTOBO_WEB_HTTPS_PORT in het .env-bestand in te stellen.

Bepaalde diensten bij opstarten overslaan

De huidige Docker Compose-configuratie start vijf, of zes als HTTPS is ingeschakeld, diensten. Er zijn echter geldige gebruiksscenario's waarbij een of meer van deze diensten niet nodig zijn. Het belangrijkste voorbeeld is wanneer de database niet als Docker-dienst, maar als externe database wordt uitgevoerd.

docker-compose up -d web nginx daemon redis elastic

Uiteraard kan hetzelfde doel ook worden bereikt door het bestand docker-compose/otobo-base.yml te bewerken en de relevante dienstdefinities te verwijderen.

Aanpassen van OTOBO Docker Compose

In plaats van de bestanden onder docker-compose/ te bewerken en het risico te lopen dat uw eigen opties worden overschreven bij de volgende update van de otobo-docker-map, is het raadzaam om een extra YAML-bestand aan te maken waarin de specifieke diensten met extra opties worden overschreven.
Een gebruikelijk voorbeeld is het toegankelijk maken van de databasecontainer van buitenaf via poort 3306. Hiervoor kunt u een extra Docker-Compose-bestand maken dat er als volgt uitziet:

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

Nu moeten we docker-compose vertellen om ons nieuwe bestand te gebruiken. Hiervoor moet u uw YAML-bestand toevoegen aan de variabele COMPOSE_FILE in het .env-bestand, bijvoorbeeld:

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

Nu kunnen we docker-compose gebruiken om onze containers opnieuw aan te maken:

docker-compose stop
docker-compose up -d

Met deze methode kunt u elke dienst of elk volume aanpassen.

Aanpassen van het OTOBO Docker-afbeelding

Veel aanpassingen kunnen worden gedaan in het externe volume otobo_opt_otobo, dat overeenkomt met de map /opt/otobo in de Docker-afbeelding. Dit werkt bijvoorbeeld voor lokale Perl-modules die kunnen worden geïnstalleerd in /opt/otobo/local. Hieronder een voorbeeld dat de niet erg nuttige CPAN-module Acme::123 installeert.

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

Het mooie van deze aanpak is dat de Docker-afbeelding zelf niet hoeft te worden aangepast.
Het installeren van extra Debian-pakketten is iets lastiger. Een aanpak is om een aangepast Dockerfile te maken en de OTOBO-afbeelding als basisafbeelding te gebruiken. Een andere aanpak is om rechtstreeks uit een actieve container een aangepaste afbeelding te maken. Dit kan met de opdracht docker commit, https://docs.docker.com/engine/reference/commandline/commit/. Een goede beschrijving van dit proces vindt u op https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.
Voor de laatstgenoemde aanpak zijn er twee obstakels te overwinnen. Ten eerste draait de afbeelding otobo standaard als gebruiker otobo met UID 1000. Het probleem is dat de gebruiker otobo niet gemachtigd is om systeempakketten te installeren. De eerste oplossing is daarom om de optie --user root te gebruiken bij het starten van de container. Het tweede obstakel is dat het standaard startscript /opt/otobo_install/entrypoint.sh onmiddellijk stopt wanneer het als root wordt aangeroepen. De gedachte achter deze ontwerpkeuze is om onbedoeld uitvoeren als root te voorkomen. Het tweede deel van de oplossing is daarom om een ander startscript op te geven dat niet om de aanroeper geeft. Dit leidt tot de volgende voorbeeldopdrachten, waarbij we otobo Fortune Cookies toevoegen:
Haal een getagde OTOBO-afbeelding op, als we die nog niet hebben, en controleer of de afbeelding al Fortune Cookies biedt:

docker run rotheross/otobo:rel-10_0_10 /usr/games/fortune

/opt/otobo_install/entrypoint.sh: regel 57: /usr/games/fortune: Bestand of map bestaat niet

Voeg Fortune Cookies toe aan een benoemde container die de originele OTOBO-afbeelding uitvoert. Dit gebeurt in een interactieve sessie als gebruiker 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

Maak een afbeelding van de gestopte container en geef het een naam. Houd er rekening mee dat de standaardgebruiker en het startscript moeten worden hersteld:
Tot slot kunnen we het testen:

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

De aangepaste afbeelding kan in uw .env-bestand worden ingesteld en vervolgens voor plezier en winst worden gebruikt.

Lokale afbeeldingen bouwen

INFO

Het lokaal bouwen van Docker-afbeeldingen is meestal alleen nodig tijdens ontwikkeling. Andere gebruiksscenario's zijn wanneer actuelere basisafbeeldingen moeten worden gebruikt voor een installatie, of wanneer extra functionaliteit aan de afbeeldingen moet worden toegevoegd.

De Docker-bestanden die nodig zijn om Docker-afbeeldingen lokaal te bouwen, maken deel uit van de git-repository https://github.com/RotherOSS/otobo:

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

Het script voor het daadwerkelijk bouwen van de afbeeldingen is bin/docker/build_docker_images.sh.

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

Wissel naar de gewenste branch, bijvoorbeeld:

git checkout rel-10_0_11

cd otobo

Pas de Docker-bestanden indien nodig aan

bin/docker/build_docker_images.sh
docker image ls

De lokaal gebouwde Docker-afbeeldingen worden getagd als local-<OTOBO_VERSION>, waarbij de versie wordt gebruikt uit het bestand RELEASE.
Nadat de lokale afbeeldingen zijn gemaakt, kunt u terugkeren naar de map docker-compose. De lokale afbeeldingen worden gedeclareerd door OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX in .env in te stellen.

Automatische installatie

In plaats van het proces via http://yourIPorFQDN/otobo/installer.pl uit te voeren, kunt u een kortere weg nemen. Dit is handig om de testsuite op een verse installatie uit te voeren.

WARNING

docker-compose down -v verwijdert alle eerdere installaties en gegevens.

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

Lijst met nuttige opdrachten

Docker

• docker system prune -a Systeemopschoning (verwijdert alle ongebruikte afbeeldingen, containers, volumes, netwerken)
• docker version Toont de versie
• en vele andere nuttige Docker-opdrachten.

Docker Compose

• docker-compose config Controleert en toont de configuratie
• docker-compose ps Toont de actieve containers
• en verdere nuttige Docker Compose-opdrachten.