Guide pratique pour l’installation d’un Agent IKAN ALM via la console

Objectif

Si des actions de construction ou de déploiement sont planifiées sur un environnement local ou distant requérant une interaction avec le système Cible, un Agent IKAN ALM doit être installé sur cette Machine. Ce document technique explique la procédure d’installation d’un Agent IKAN ALM via la console (c’est-à-dire sans interface graphique). Nous décrirons également comment définir l’administration globale et celle des projets de façon à ce que le système local/distant soit repris dans le(s) cycle de vie(s) du Projet Cible.

Le terme "environnement distant" s’applique à un autre système que le système du Serveur IKAN ALM. Une construction locale sera exécutée sur la Machine Serveur IKAN ALM elle-même.

En conséquence, ce document peut servir des objectifs différents. Vérifiez si votre cas correspond à une des situations suivantes:

  • Vous avez installé l’application IKAN ALM Démo (qui installe le Serveur ainsi que l’Agent dans un conteneur Serveur Web Tomcat/Karaf OSGi) et vous voulez exécutez des Constructions et/ou des Déploiements sur une autre Machine que celle sur laquelle est installée cette l’application.

    Pour une installation Démo, l’Agent et le Serveur sont tous les deux exécutés sur la machine virtuelle Java du même conteneur OSGi. Notez que cela n’est pas la configuration recommandée pour un système de production puisqu’une Construction nécessitant beaucoup de mémoire peut causer l’arrêt du conteneur OSGi à cause d’erreurs OutOfMemory.

  • Vous avez installé, ou vous avez l’intention d’installer, le Serveur IKAN ALM et vous voulez installer un Agent IKAN ALM sur la même Machine (en même temps que l’installation Serveur ou comme installation séparée), pour que vous puissiez exécuter des Constructions locales (ou même des Déploiements dans certain cas) sur la Machine Serveur. C’est la méthode conseillée pour exécuter des Constructions locales.

  • Vous avez installé le Serveur IKAN ALM et vous voulez installer un Agent IKAN ALM sur une autre Machine distante pour pouvoir exécuter des Constructions distribuées ou déployer et contrôler des Machines distantes.

Prérequis

Les exigences de matériel

  • RAM: minimum 250 Mo (mégaoctets), recommandé 0,5 Go (gigaoctets) ou plus.

    Notez qu’il ne s’agit que de valeurs indicatives. Un Serveur de construction ou de déploiement peut avoir des exigences de mémoire plus élevées en fonction du nombre de Constructions ou de Déploiements exécutés simultanément. Pour une approche plus mathématique, se référer à l’article Capacity Planning For Software Build Management Servers sur le site de CM Crossroads: http://www.cmcrossroads.com/cm-journal-articles/6671-capacity-planning-for-software-build-management-servers.

  • Espace de stockage disque minimum 1 Go (gigaoctets).

    Il n’existe pas de règle absolue sur l’espace de stockage disque requis. L’espace occupé d’une installation simple d’un Agent IKAN ALM est inférieur à 40 Mo (mégaoctets). L’espace réel requis par un Agent dépend du nombre et de la taille des Projets gérés par cet Agent, et de la taille des ressources nécessaires pour exécuter une Construction ou un Déploiement. Plus il y a des projets et plus les constructions sont larges, plus d’espace de stockage sera nécessaire sur le disque.

Java Virtual Machine version1.7 ou 1.8

Tous les composants IKAN ALM nécessitent au moins un Kit de développement Java (JDK) ou un Serveur Java Runtime (Serveur JRE).

IKAN ALM a été testé pour fonctionner avec Oracle Java ainsi qu’avec OpenJDK. Le Java SE Server Runtime Environment (Serveur JRE) et le Kit de développement logiciel (SDK) peuvent être obtenus gratuitement via le site Web d’Oracle. Les version 32 bits et 64 bits sont toutes les deux supportées. La dernière version de Java SE peut être téléchargée sur http://www.oracle.com/technetwork/java/javase/downloads/index.html

Connexion HTTP ou HTTPS avec le Serveur IKAN ALM

La communication entre le Serveur et les Agents se fait via le protocole XML-RPC. Cela signifie qu’IKAN ALM permet de l’informatique distribuée (des appels de procédure à distance) en utilisant HTTP ou HTTPS comme protocole de transport et XML pour l’encodage (pour plus d’informations, se référer au site http://www.xmlrpc.com

Pour pouvoir activer l’interaction XML-RPC, une connexion TCP/IP correcte doit être établie entre la Machine Cible pour le nouvel Agent et la Machine Serveur.

Outil de script

Pour pouvoir exécuter un script de construction ou de déploiement sur la Machine distante, l’Outil de script approprié doit être installé sur le système Cible de l’Agent. IKAN ALM supporte les Outils de script Ant, Gradle, NAnt et Maven2. Les autres scripts (Perl, make, …​) peuvent être appelés facilement via ces Outils de script supportés.

Si vous avez besoin de plus d’informations, contactez le service de support (support@ikanalm.com). Consultez les sites Web spécifiques (http://ant.apache.org, http://gradle.org, http://maven.apache.org et http://nant.sourceforge.net) pour télécharger et installer l’Outil de script approprié.

L’installation de l’Agent peut être lancée sans qu’un Outil de script ne soit installé sur la Machine Cible. Une fois l’Agent installé et en cours d’exécution, vous pouvez toujours installer et configurer l’Outil de script.

Installation de l’Agent IKAN ALM

IKAN ALM comprend un installateur basé sur Ant. Pour l’installer, vous devez configurer les propriétés d’installation dans le script d’installation. Les sections suivantes décrivent les étapes nécessaires pour installer un Agent IKAN ALM.

Configurer et exécuter l’installateur Ant

Les scripts d’installation sont livrés sous forme d’un fichier IKAN_ALM_5.8_console_win.zip ou IKAN_ALM_5.8_console_linux.tar.gz. Développez ce fichier quelque part sur le système Cible. Le répertoire développé contenant les fichiers de l’installation IKAN ALM (les scripts Ant) sera nommé INSTALL_DIR.

L’installateur Ant inclus installera les composants de l’Agent IKAN ALM dans les répertoires Cible spécifiés.

Configurer le fichier install.properties

Configurez les différentes propriétés qui seront utilisées par les scripts d’installation en éditant le fichier INSTALL_DIR/install.properties.

N’utilisez PAS de barres obliques inverses ('\') dans les propriétés du chemin, sinon l’installation peut échouer. Ou alors, vous devrez les doubler: "\" , car dans ce cas Ant considérera détecter un caractère spécial.

Utilisez des barres obliques normales ('/') à la place!

Paramètres généraux

L’installateur via la console peut installer tous les composants IKAN ALM (Serveur IKAN ALM, IKAN ALM, Interface de ligne de commande IKAN ALM) en un seul passage. Puisqu’il ne faut installer que l’Agent IKAN ALM sur la Machine Cible, modifiez les paramètres comme suit:

Pour installer uniquement l’Agent, définissez la propriété alm.agent.install=true et établissez les propriétés alm.server.install et alm.commandline.install=false

# General Settings : Specify which components
of IKAN ALM to install
# ---------------------------------------------------------------------------
# Flag to specify whether to install IKAN ALM Server or not:
install : true
# no install : false
alm.server.install=false
# Flag to specify whether to install the IKAN ALM Agent or
not : install : true
# no install : false
alm.agent.install=true
# Flag to specify whether to install the IKAN ALM Commandline
or not : install : true
# no install : false
alm.commandline.install=false

Une autre propriété générale permet de définir la communication sécurisée via HTTPS entre les composants IKAN ALM. N’établissez cette propriété à "true" que si le Serveur IKAN ALM a également été défini pour supporter une communication sécurisée. Le document HowToALM 5.8_Secure.pdf décrit comment définir la communication sécurisée entre les différents composant d’IKAN ALM.

# Flag to specify whether the communication
between the IKAN ALM components must
# be secured. Note that if one IKAN ALM component is installed
secured, all components
# must be installed secured.
alm.xmlrpc.secure=false

Propriétés de l’Agent

Modifiez les propriétés nécessaires pour réussir l’installation de l’Agent IKAN ALM.

Propriété Explication

alm.agent.installLocation

L’emplacement où l’Agent sera installé, par exemple,/opt/ikan/alm ou C:/alm.

Dans la suite de ce guide, cet emplacement s’appellera ALM_HOME.

alm.agent.javaHome

L’emplacement de la Machine Virtuelle Java est utilisé pour lancer l’Agent.

Cela peut être un JDK Java ou un Serveur JRE, version 1.7.x ou 1.8.x (voir Prérequis).

Par exemple: D:/java/jdk1.8 or /opt/java/jdk1.8.

Note: Sous Unix ou Linux, spécifiez le chemin réel de l’installation Java (ne spécifiez pas de symlink) car l’installation vérifiera l’existence de certains jars spécifiques avec le chemin saisi.

alm.agent.agentPort

Le Port écouté par l’Agent. La valeur par défaut est "20020".

Si vous modifiez cette valeur, vous devez également modifier, dans l’Administration globale d’IKAN ALM, la propriété "Agent Port" de la machine représentant cet Agent.

alm.agent.serverHost

Le nom de Machine (ou l’Adresse IP) de la Machine Serveur IKAN ALM.

L’Agent essaiera de se connecter au Serveur en utilisant ce nom ou cette Adresse IP et en utilisant le protocole HTTP ou HTTPS.

La valeur par défaut est "localhost".

alm.agent.serverPort

Le Port écouté par le Serveur IKAN ALM.

L’Agent essaiera de se connecter au Serveur via ce Port. La valeur par défaut est "20021".

Vous pouvez vérifier ce paramètre dans la section Administration globale d’IKAN ALM.

. Naviguez vers Administration globale > Paramètres système + Onglet Environnement local: la valeur du champ "Serveur IKAN ALM" représente la Machine Serveur IKAN ALM . Naviguez vers Administration globale > Machines > Aperçu + Vérifiez la propriété "Port du Serveur" de la Machine Serveur IKAN ALM.

alm.agent.hostname

Optionnel.

Laissez ce champ vide sauf si vous voulez écraser le nom de Machine automatiquement détecté de l’Agent.

Par exemple, si vous voulez utiliser un nom de domaine complet, tel que almAgent.your.domain pour la communication avec le Serveur IKAN ALM. Il est important que le nom de Machine saisi corresponde au nom DHCP de la Machine Agent (spécifié dans l’interface IKAN ALM).

alm.agent.hostaddress

Optionnel.

Laissez ce champ vide sauf si vous voulez écraser l’adresse IP automatiquement détectée de l’Agent.

Par exemple, si vous voulez utiliser une adresse IP différente des adresses IP internes pour la communication avec le Serveur IKAN ALM. Il est important que l’adresse IP saisie corresponde à l’adresse IP de la Machine Agent (spécifiée dans l’interface IKAN ALM).

Voici les numéros de port qui sont spécifiques au conteneur Karaf dans lequel est hébergé l’Agent IKAN ALM. En principe vous ne devez pas modifier ces numéros de port sauf en cas de conflits. Pour plus d’informations, se référer à la documentation concernant Karaf Container 4.0: https://karaf.apache.org/manual/latest/#_instances/

Propriété Explication

alm.agent.karaf.rmiRegistryPort

Port de Karaf RMI Registry.

La valeur par défaut est "1099".

alm.agent.karaf.rmiServerPort

Port de Karaf RMI Server.

La valeur par défaut est "44444".

alm.agent.karaf.sshPort

Port de Karaf SSH

La valeur par défaut est "8101".

alm.agent.logfilepath

Le chemin relatif du journal Karaf du journal de l’Agent IKAN ALM.

Ce paramètre est utilisé par le Serveur IKAN ALM au moment d’afficher la Trace de la Machine d’un Agent dans la fenêtre "Statut détaillé de la Machine".

Voici un exemple d’une configuration d’installation d’un Agent:

# ---------------------------------------------------------------------------
# IKAN ALM Agent Settings, when alm.agent.install=true :
# ---------------------------------------------------------------------------
# Destination folder of the IKAN ALM Agent files :
# Recommended : use the IKAN ALM Server installLocation
alm.agent.installLocation=C:/alm
# Java Runtime to run the IKAN ALM Agent with (may be JRE
or JDK):
alm.agent.javaHome=d:/java/jdk1.8
# IKAN ALM Agent Runtime parameters :
# agentPort : port Agent should be listening on (default=20020)
# serverPort : port Server is listening on (default=20021)
# serverHost : host Server is running on (default=localhost)
# hostname: optional, leave empty unless you want to override
the system hostname
# retrieved as InetAddress.getHostName(), e.g. to use a fully
qualified domain name like
# almAgent.your.domain for communication with the IKAN ALM
server
# hostaddress: optional, leave empty unless you want to override
the system hostaddress
# retrieved as InetAddress.getHostAddress(), e.g. to use a
IP Address which differs from
# the internal IP Address for communication with the IKAN
ALM server
alm.agent.agentPort=20020
alm.agent.serverHost=localhost
alm.agent.serverPort=20021
alm.agent.hostname=
alm.agent.hostaddress=
# Karaf ports, no need to change unless you have port conflicts
alm.agent.karaf.rmiRegistryPort=1099
alm.agent.karaf.rmiServerPort=44444
alm.agent.karaf.sshPort=8101
# relative path to the Karaf log of the IKAN ALM Agent
alm.agent.logfilepath=log/alm_agent.log

Vérifiez les paramètres de l’Agent ALM avant d’exécuter l’installateur.

Astuce: ne supprimez pas le fichier install.properties après l’installation. Vous pouvez le réutiliser pour des installations futures d’IKAN ALM.

Exécuter l’installateur Ant

Normalement, le script d’installation détecte le défaut système JAVA_HOME et utilise ce défaut pour lancer l’installation. Si la détection échoue, vous devez modifier le fichier INSTALL_DIR\install.cmd (Windows) ou INSTALL_DIR/install.sh (Unix/Linux) et pointer JAVA_HOME vers le répertoire d’installation d’un Java Runtime, par exemple, SET JAVA_HOME=D:\java\jdk1.8

Ou sur une Machine Unix/Linux: JAVA_HOME="/opt/jdk1.8

Avant de commencer l’installation, vérifiez une dernière fois les paramètres d’installation:

  1. Vérifiez encore une fois les emplacements d’installation.

  2. Assurez-vous que l’utilisateur exécutant l’installation dispose des droits d’écriture sur les emplacements requis.

  3. Si le Contrôle de compte d’utilisateur (UAC) est activé (Windows Vista et supérieur), la fenêtre de commande nécessite des droits d’accès d’Administrateur (l’intitulé de la fenêtre doit commencer par "Administrateur:"). Si la fenêtre de commande ne dispose pas de droits d’accès d’Administrateur, l’installation pourrait réussir, mais l’Agent IKAN ALM ne sera pas enregistré comme Service Windows.

figure1

Exécutez le fichier INSTALL_DIR/install.cmd (Windows) ou INSTALL_DIR/install.sh (Unix/Linux), de préférence à partir d’une fenêtre de commande MSDOS ou d’une fenêtre de terminal pour que vous puissiez suivre le progrès des différentes tâches.

Si l’installation réussit, le message "BUILD SUCCESSFUL" s’affichera.

Démarrer l’Agent IKAN ALM

Linux/Unix

Lancez le script shell qui est installé sous: ALM_HOME/daemons/agent/startAgent.sh.

Utilisez la commande ALM_HOME /daemons/agent/stopAgent.sh pour arrêter l’Agent IKAN ALM.

Commande Windows

Lancez le fichier de commande qui est installé sous: ALM_HOME/daemons/agent/startAgent.cmd.

Service Windows

Par défaut, l’Agent est enregistré comme un service Windows qui sera démarré automatiquement lors de la mise en marche du système.

Alternativement, vous pouvez vérifier le service via Démarrer > Paramètres > Panneau de configuration >Outils d’administration > Services.

Le nom de service de l’Agent est "IKAN ALM 5.8 Agent".

Journaux

Toutes les activités de l’Agent IKAN ALM sont enregistrées dans un fichier journal dont l’emplacement est spécifié dans le fichier de propriétés de configuration log4j suivant: ALM_HOME/daemons/agent/karaf/etc/org.ops4j.pax.logging.cfg.

Normalement, le fichier FileAppender Log4j spécifie l’emplacement par défaut du journal comme suit: “${karaf.base}/log/karaf.log” ce qui signifie: ALM_HOME /daemons/agent/karaf/log/karaf.log

Notez que le fichier de configuration de l’Agent ALM_HOME /daemons/agent/karaf/etc/agent.cfg a une propriété qui pointe également vers le fichier journal de l’Agent alm.agent.logfilepath=log/alm_agent.log

Ce paramètre est utilisé par le Serveur IKAN ALM au moment d’afficher la Trace de la Machine d’un Agent dans la fenêtre "Statut détaillé de la Machine". Notez que ce paramètre doit correspondre à l’emplacement actuel du fichier journal de l’Agent spécifié dans le fichier org.ops4j.pax.logging.cfg.

Si l’Agent IKAN ALM est exécuté comme un Service Windows, un fichier journal de service additionnel nommé "wrapper.log" est créé. Les paramètres de l’emplacement du journal, la taille et les autres propriétés du journal sont spécifiés dans le fichier de configuration du service: ALM_HOME /daemons/agent/karaf/etc/karaf-wrapper.conf

Désinstaller IKAN ALM

Pour complètement désinstaller un agent IKAN ALM de votre système, faites ce qui suit:

  1. Normalement, le script de désinstallation détecte le système JAVA_HOME par défaut et utilise ce défaut pour lancer la désinstallation.

    Si la détection échoue, vous devrez modifier le fichier INSTALL_DIR\uninstall.cmd (Windows) ou INSTALL_DIR/uninstall.sh (Unix/Linux) et pointer JAVA_HOME vers le répertoire d’installation d’un Java Runtime.

    Par exemple: SET JAVA_HOME=D:\java\jdk1.8

    Ou sur une Machine Unix/Linux: JAVA_HOME="/opt/jdk1.8"

  2. Ensuite, configurez le fichier INSTALL_DIR/uninstall.properties.

    Spécifiez alm.agent.uninstall=true. Comme vous désinstallez uniquement l’Agent, assurez-vous que les paramètres alm.server.uninstall and alm.commandline.uninstall sont tous les deux établis à false.

    Établissez alm.agent.installLocation à l’emplacement d’installation spécifié dans INSTALL_DIR/install.properties.

  3. Finalement, exécutez le désinstalleur.

    Exécutez INSTALL_DIR/uninstall.cmd (Windows) ou INSTALL_DIR/uninstall.sh (Linux/Unix).

  4. Si le Contrôle de compte d’utilisateur (UAC) est activé (Windows Vista et supérieur), la fenêtre de commande nécessite des droits d’accès d’Administrateur (l’intitulé de la fenêtre doit commencer par "Administrateur:").

    Si la fenêtre de commande ne dispose pas de droits d’accès d’Administrateur, la désinstallation pourrait réussir, mais l’Agent IKAN ALM ne sera pas supprimé comme Service Windows.

Mettre à jour IKAN ALM

La procédure générale d’actualisation d’IKAN ALM est très simple. D’abord vous devez sauvegarder l’installation. Ensuite, réinstallez l’application avec une version supérieure.

Si le processus de mise à jour échoue, vous pouvez restaurer la sauvegarde et continuer à utiliser la version précédente d’IKAN ALM (et contacter le service de support).

Tout d’abord vous devez mettre à jour le Serveur IKAN ALM et la Base de données (en fonction du type d’installation Serveur effectuée (graphique ou via une console)). Vous trouverez la procédure pour ce faire dans les documents IKAN ALM 5.8 Installation guide_FR.pdf ou HowToALM 5.8_Tomcat_Install_FR.pdf.

Pour des raisons de sécurité, il est hautement recommandé de sauvegarder le répertoire ALM_HOME dans sa totalité.

L’expérience nous a montré que, parfois, il faut restaurer une configuration comme par exemple un paramètre de sécurité ou la configuration des journaux.

  1. Arrêtez l’Agent IKAN ALM et effectuez une sauvegarde.

    Cela est important pour vous assurer que vous disposez de la dernière version de tout.

  2. Désinstaller l’Agent IKAN ALM distant

    Configurez et exécutez l’installateur sur la Machine Agent IKAN ALM.

    Vous trouverez plus d’informations sur cette procédure dans la section Désinstaller IKAN ALM.

    Astuce: Sauvegardez une copie du fichier INSTALL_DIR/install.properties après avoir exécuté l’installation. Vous pouvez réutiliser les valeurs dans le fichier si vous devez configurer l’installateur pour une nouvelle version. Veillez à ne pas écraser le vieux fichier install.properties! Certaines propriétés peuvent être renommées, supprimées ou ajoutées.

  3. Configurez et exécutez l’installateur de la version plus récente de l’Agent ALM.

    Pour plus d’informations, se référer à la section indiquée Configurer et exécuter l’installateur Ant.