Installation avancée d'OTOBO avec Docker Compose

Cette section fournit des détails techniques supplémentaires sur ce qui se passe en arrière-plan.

::: version Liste des conteneurs Docker ; 10+ Conteneur otobo_web_1 : Serveur web OTOBO sur le port interne 5000.

Conteneur otobo_daemon_1 : Démon OTOBO. Le démon OTOBO est démarré et vérifié périodiquement.

Conteneur otobo_db_1 : Exécute la base de données MariaDB sur le port interne 3306.

Conteneur otobo_elastic_1 : Elasticsearch sur les ports internes 9200 et 9300.

Conteneur otobo_redis_1 : Exécute Redis en tant que service de cache.

Conteneur optionnel otobo_nginx_1 : Exécute nginx en tant que proxy inverse pour fournir le support HTTPS. :::

::: version Liste des conteneurs Docker ; 11 Conteneur otobo-web-1 : Serveur web OTOBO sur le port interne 5000.

Conteneur otobo-daemon-1 : Démon OTOBO. Le démon OTOBO est démarré et vérifié périodiquement.

Conteneur otobo-db-1 : Exécute la base de données MariaDB sur le port interne 3306.

Conteneur otobo-elastic-1 : Elasticsearch sur les ports internes 9200 et 9300.

Conteneur otobo-redis-1 : Exécute Redis en tant que service de cache.

Conteneur optionnel otobo-nginx-1 : Exécute nginx en tant que proxy inverse pour fournir le support HTTPS. :::

Aperçu des volumes Docker

Les volumes Docker sont créés sur l'hôte pour les données persistantes. Cela permet de démarrer et d'arrêter les services sans perte de données. Notez que les conteneurs sont temporaires et seules les données dans les volumes sont durables.

otobo_opt_otobo : contient /opt/otobo dans les conteneurs web et daemon.

otobo_mariadb_data : contient /var/lib/mysql dans le conteneur db.

otobo_elasticsearch_data : contient /usr/share/elasticsearch/data dans le conteneur elastic.

otobo_redis_data : contient les données du conteneur redis.

otobo_nginx_ssl : contient les fichiers TLS, certificat et clé privée, doit être initialisé manuellement.

Variables d’environnement Docker

Dans les instructions, nous n’avons effectué qu’une configuration minimale. Mais le fichier .env permet de définir davantage de variables. Voici une courte liste des variables d’environnement les plus importantes. Notez que les images de base prennent en charge davantage de variables d’environnement.

Paramètres MariaDB

OTOBO_DB_ROOT_PASSWORD : Mot de passe root pour MariaDB. Ce paramètre est nécessaire pour exécuter le service db.

Paramètres Elasticsearch

Elasticsearch nécessite certains paramètres pour les environnements de production. Veuillez consulter https://www.elastic.co/guide/en/elasticsearch/reference/7.8/docker.html#docker-prod-prerequisites pour des informations détaillées.

OTOBO_Elasticsearch_ES_JAVA_OPTS : Exemple de configuration : OTOBO_Elasticsearch_ES_JAVA_OPTS=-Xms512m -Xmx512m. Veuillez adapter cette valeur jusqu'à 4g pour les environnements de production.

Paramètres du serveur web

OTOBO_WEB_HTTP_PORT : Définissez cette valeur si le port HTTP doit différer du port par défaut 80. Si HTTPS est activé, le port HTTP est redirigé vers HTTPS.

Paramètres du proxy web Nginx : Ces paramètres sont utilisés lorsque HTTPS est activé.

OTOBO_WEB_HTTP_PORT : Définissez cette valeur si le port HTTP doit différer du port par défaut 80. Il sera redirigé vers HTTPS.

OTOBO_WEB_HTTPS_PORT : Définissez cette valeur si le port HTTPS doit différer du port par défaut 443.

OTOBO_NGINX_SSL_CERTIFICATE : Certificat SSL pour le proxy web Nginx. Exemple : OTOBO_NGINX_SSL_CERTIFICATE=/etc/nginx/ssl/acme.crt

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Clé SSL pour le proxy web Nginx. Exemple : OTOBO_NGINX_SSL_CERTIFICATE_KEY=/etc/nginx/ssl/acme.key

Paramètres Nginx pour Kerberos : Ces paramètres sont utilisés par Nginx lorsque Kerberos est utilisé pour le SSO (Single Sign-On).

OTOBO_NGINX_KERBEROS_KEYTAB : Fichier keytab Kerberos. Par défaut : /etc/krb5.keytab.

OTOBO_NGINX_KERBEROS_CONFIG : Fichier de configuration Kerberos. Par défaut : /etc/krb5.conf, généralement généré à partir de krb5.conf.template.

OTOBO_NGINX_KERBEROS_SERVICE_NAME : Nom du service Kerberos. L’utilisation exacte de ce paramètre n’est pas claire.

OTOBO_NGINX_KERBEROS_REALM : Domaine Kerberos. Utilisé dans /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_KDC : Contrôleur Kerberos KDC / AD. Utilisé dans /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_ADMIN_SERVER : Serveur d’administration Kerberos. Utilisé dans /etc/krb5.conf.

OTOBO_NGINX_KERBEROS_DEFAULT_DOMAIN : Domaine par défaut Kerberos. Utilisé dans /etc/krb5.conf.

NGINX_ENVSUBST_TEMPLATE_DIR : Fournit un répertoire personnalisé pour les modèles de configuration Nginx. Offre une flexibilité supplémentaire.

Paramètres Docker Compose : Ces paramètres sont utilisés directement par Docker Compose.

COMPOSE_PROJECT_NAME : Le nom du projet est utilisé comme préfixe pour les volumes et conteneurs. Par défaut, ce préfixe est défini sur otobo, ce qui donne des noms de conteneurs comme otobo_web_1 et otobo_db_1. Modifiez ce nom si vous souhaitez exécuter plusieurs instances d’OTOBO sur le même serveur.

COMPOSE_PATH_SEPARATOR : Séparateur pour la valeur de COMPOSE_FILE.

COMPOSE_FILE : Utilisez docker-compose/otobo-base.yml comme base et ajoutez les fichiers d’extension souhaités. Par exemple, docker-compose/otobo-override-http.yml ou docker-compose/otobo-override-https.yml.

OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX, \... : Utilisé pour spécifier des images Docker alternatives. Utile pour tester des builds locaux ou utiliser des versions mises à jour des images.

Configuration personnalisée du proxy web Nginx

Le conteneur otobo_nginx_1 fournit le support HTTPS en exécutant Nginx comme proxy inverse. L’image Docker utilisée dans le conteneur est basée sur l’image officielle Nginx, https://hub.docker.com/_/nginx, complétée par une configuration Nginx spécifique à OTOBO. La configuration par défaut se trouve dans l’image Docker sous /etc/nginx/template/otobo_nginx.conf.template. En réalité, il s’agit d’un modèle pour la configuration finale. Un processus fourni par l’image de base Nginx remplace les macros du modèle par les variables d’environnement correspondantes lors du démarrage du conteneur. Dans le fichier modèle par défaut, les macros suivantes sont utilisées :

OTOBO_NGINX_SSL_CERTIFICATE : Pour la configuration SSL.

OTOBO_NGINX_SSL_CERTIFICATE_KEY : Pour la configuration SSL.

OTOBO_NGINX_WEB_HOST : Hôte HTTP interne utilisé.

OTOBO_NGINX_WEB_PORT : Port HTTP interne utilisé.

Voir l’étape [4.] pour utiliser cette possibilité de configuration afin de définir le certificat SSL.

Si les macros par défaut ne suffisent pas, une personnalisation plus poussée est possible en remplaçant le modèle de configuration par une version personnalisée. Il est recommandé de ne pas modifier directement la configuration dans un conteneur en cours d’exécution. Dans les commandes d’exemple suivantes, nous utilisons le modèle existant comme point de départ.

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

Ajoutez la ligne suivante au fichier docker-compose/otobo-override-https.yml :

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

Vous pouvez utiliser votre éditeur de texte préféré via Putty ou WinSCP.

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

Vous pouvez maintenant modifier le fichier /opt/otobo-docker/nginx/otobo_nginx.conf. Pour appliquer les modifications, redémarrez les conteneurs :

docker-compose up -d --build

Authentification unique (SSO) avec support Kerberos dans Nginx

Pour activer l’authentification Kerberos, basez votre fichier .env sur l’exemple .docker_compose_env_https_kerberos. Cela active la configuration spéciale dans docker-compose/otobo-override-https-kerberos.yml. Ce fichier de configuration Docker Compose sélectionne une image Nginx compatible Kerberos et transmet des paramètres spécifiques à Kerberos comme variables d’environnement au conteneur Nginx en cours d’exécution. Ces paramètres sont listés ci-dessus. Comme d’habitude, les valeurs peuvent être définies dans le fichier .env. La plupart de ces paramètres servent de valeurs de remplacement pour le modèle https://github.com/RotherOSS/otobo/blob/rel-10_1/scripts/nginx/kerberos/templates/krb5.conf.template. Le remplacement a lieu au démarrage du conteneur. Dans le conteneur en cours d’exécution, la configuration personnalisée est disponible sous /etc/krb5.conf. Il est toujours possible de fournir un fichier /etc/krb5.conf personnalisé en montant un volume qui remplace /etc/krb5.conf dans le conteneur. Cela peut être réalisé en définissant OTOBO_NGINX_KERBEROS_CONFIG dans le fichier .env et en activant la directive de montage dans docker-compose/otobo-override-https-kerberos.yml. Le fichier /etc/krb5.keytab est toujours spécifique à l’installation et doit donc toujours être monté depuis le système hôte.
Guide d’installation SSO Kerberos
sso-kerberos

Utilisation de ports non standard

Par défaut, les ports 443 et 80 servent respectivement HTTPS et HTTP. Il peut arriver que l’un ou les deux ports soient déjà utilisés par d’autres services. Dans ce cas, les ports par défaut peuvent être remplacés en définissant OTOBO_WEB_HTTP_PORT et OTOBO_WEB_HTTPS_PORT dans le fichier .env.

Ignorer le démarrage de certains services

La configuration actuelle de Docker Compose démarre cinq services, six si HTTPS est activé. Cependant, il existe des cas d’usage valides où un ou plusieurs de ces services ne sont pas nécessaires. Le cas principal est lorsque la base de données est externe et non gérée comme un service Docker.

docker-compose up -d web nginx daemon redis elastic

Bien sûr, le même objectif peut être atteint en modifiant le fichier docker-compose/otobo-base.yml et en supprimant les définitions de service concernées.

Personnalisation d’OTOBO Docker Compose

Plutôt que de modifier directement les fichiers dans docker-compose/ et risquer de perdre vos modifications lors de la prochaine mise à jour du dossier otobo-docker, il est conseillé de créer un fichier YAML supplémentaire pour remplacer les services spécifiques avec des options personnalisées. Un exemple courant consiste à rendre le conteneur de base de données accessible depuis l’extérieur via le port 3306. Pour cela, vous pouvez créer un fichier Docker Compose supplémentaire comme suit :

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

Nous devons maintenant indiquer à docker-compose d’inclure notre nouveau fichier. Pour cela, ajoutez votre fichier YAML à la variable COMPOSE_FILE dans le fichier .env, par exemple :

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

Nous pouvons maintenant utiliser docker-compose pour recréer nos conteneurs :

docker-compose stop
docker-compose up -d

Avec cette méthode, vous pouvez personnaliser n’importe quel service ou volume.

Personnalisation de l’image Docker OTOBO

De nombreuses personnalisations peuvent être effectuées dans le volume externe otobo_opt_otobo, qui correspond au répertoire /opt/otobo dans l’image Docker. Cela fonctionne par exemple pour les modules Perl locaux, qui peuvent être installés dans /opt/otobo/local. Voici un exemple qui installe le module CPAN peu utile 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

L’avantage de cette approche est que l’image Docker elle-même n’a pas besoin d’être modifiée.
Installer des paquets Debian supplémentaires est un peu plus délicat. Une approche consiste à créer un Dockerfile personnalisé en utilisant l’image OTOBO comme image de base. Une autre approche consiste à créer directement une image modifiée à partir d’un conteneur en cours d’exécution, via la commande docker commit : https://docs.docker.com/engine/reference/commandline/commit/. Une bonne explication de ce processus est disponible sur https://phoenixnap.com/kb/how-to-commit-changes-to-docker-image.
Pour cette dernière approche, deux obstacles doivent être surmontés. Premièrement, l’image otobo s’exécute par défaut sous l’utilisateur otobo avec l’UID 1000. Le problème est que l’utilisateur otobo n’a pas les droits pour installer des paquets système. La première partie de la solution consiste donc à utiliser l’option --user root lors du démarrage de l’image. Le second obstacle est que le script d’entrée par défaut /opt/otobo_install/entrypoint.sh se termine immédiatement s’il est appelé en tant que root. Cette décision de conception vise à éviter une exécution accidentelle en tant que root. La deuxième partie de la solution est donc de spécifier un autre script d’entrée qui ne se soucie pas de l’utilisateur appelant. Cela nous amène aux commandes d’exemple suivantes, où nous ajoutons des « cookies de fortune » à otobo :
Téléchargez une image OTOBO taguée si vous ne l’avez pas encore, et vérifiez si l’image fournit déjà des cookies de fortune :

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

Ajoutez des cookies de fortune à un conteneur nommé exécutant l’image OTOBO d’origine. Cela se fait dans une session interactive en tant qu’utilisateur 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

Créez une image à partir du conteneur arrêté et donnez-lui un nom. Notez que l’utilisateur par défaut et le script d’entrée doivent être restaurés :
Enfin, nous pouvons le tester :

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

L’image modifiée peut être définie dans votre fichier .env et ensuite utilisée à des fins ludiques ou autres.

Création d’images locales

INFO

La création locale d’images Docker est généralement nécessaire uniquement pendant le développement. D’autres cas d’usage incluent l’utilisation d’images de base plus récentes pour une installation, ou l’ajout de fonctionnalités supplémentaires aux images.

Les fichiers Docker nécessaires à la création locale d’images sont inclus dans le dépôt git https://github.com/RotherOSS/otobo :

• otobo.web.dockerfile
• otobo.nginx.dockerfile
• otobo.elasticsearch.dockerfile
  Le script réel de création des images est bin/docker/build_docker_images.sh.

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

Passez à la branche souhaitée, par exemple :

git checkout rel-10_0_11

cd otobo

Modifiez les fichiers Docker si nécessaire

bin/docker/build_docker_images.sh
docker image ls

Les images Docker créées localement sont taguées local-<OTOBO_VERSION>, où la version est extraite du fichier RELEASE.
Une fois les images locales créées, vous pouvez revenir au répertoire docker-compose. Les images locales sont déclarées en définissant OTOBO_IMAGE_OTOBO, OTOBO_IMAGE_OTOBO_ELASTICSEARCH, OTOBO_IMAGE_OTOBO_NGINX dans .env.

Installation automatique

Plutôt que de passer par http://yourIPorFQDN/otobo/installer.pl, vous pouvez utiliser un raccourci. Cela est utile pour exécuter la suite de tests sur une installation fraîchement configurée.

WARNING

docker-compose down -v supprimera tous les paramètres et données précédents.

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

Liste des commandes utiles

Docker

• docker system prune -a Nettoyage du système (supprime toutes les images, conteneurs, volumes et réseaux inutilisés)
• docker version Affiche la version
• et bien d’autres commandes Docker utiles.

Docker Compose

• docker-compose config Vérifie et affiche la configuration
• docker-compose ps Affiche les conteneurs en cours d’exécution
• et d’autres commandes Docker Compose utiles.