Guide de mise en route

Notez que l’installation de la Démo IKAN ALM répond également aux exigences suivantes: le Serveur et l’Agent IKAN ALM seront installés, et l’outil de script Ant et le Référentiel Subversion seront installés et configurés. Sous Windows, le Serveur Subversion est également compris; sous Linux, vous devez installer Subversion séparément.

Ce Guide de mise en route inclut la création d’un Référentiel Subversion. Pour se connecter à ce référentiel, la version 1.6 (ou ultérieure) de Subversion doit être installée sur le Serveur IKAN ALM. Le Site Web Apache Subversion fournit des liens pour télécharger un paquet binaire de Subversion pour votre système.

Par exemple, sous un Système d’exploitation Windows vous pouvez facilement installer le paquet Win32Svn. Si vous téléchargez l’archive actuelle svn-win32-1.8.16.zip (novembre 2017), l’installation est aussi simple qu’une action "Dézipper".

L’installation sous Linux se fait via un Gestionnaire de paquets. Par exemple, sous Linux Suse, vous pouvez la faire en utilisant zypper.

Pour plus d’informations concernant l’usage de Subversion, se référer au guide Subversion Quick Start Guide sur http://svnbook.red-bean.com/en/1.7/svn.intro.html.

Les informations additionnelles suivantes sont nécessaires pour compléter les procédures expliquées dans ce Guide de mise en route.

Commençons par vérifier ce qui est déjà configuré dans la section "Administration globale" dans IKAN ALM après une première installation. Nous donnerons une brève explication sans trop entrer dans les détails, car, après tout, nous sommes impatients de créer notre propre projet. Cependant, si vous voulez en savoir plus sur un sujet spécifique, référez-vous aux chapitres respectifs dans la partie Administration globale du Guide de l’Utilisateur IKAN ALM.

Connectez-vous à IKAN ALM avec l’utilisateur global et le mot de passe global, et sélectionnez Administration globale à partir du Menu Principal. À partir d’ici (ou à partir d’un des sous-menus) vous pouvez vérifier les paramètres suivants:

Après avoir vérifié les paramètres d’Administration globale, nous sommes presque prêts à créer un Projet et à démarrer une Construction. Presque …​ car nous avons évidemment besoin de Sources pour pouvoir exécuter une Construction. Nous les récupérerons à partir du Référentiel Subversion que nous créerons et définirons dans la section suivante.

L’archive délivrée avec ce Guide de mise en route contient les scripts et les Sources nécessaires pour créer un Référentiel Subversion auquel nous allons nous connecter via le protocole de fichier. Comme spécifié dans les prérequis, nous supposons que Subversion est installé sur votre Serveur IKAN ALM. Extrayez le fichier GettingStarted.zip dans un répertoire temporaire dans le dossier d’installation IKAN ALM.

Modifiez les variables JAVA_HOME et ANT_HOME dans le fichier init_svn/init_svn_repo.cmd (Windows) ou init_svn/init_svn_repo.cmd/sh (Linux). Pointez JAVA_HOME vers le chemin utilisé pour IKAN ALM et utilisez la version de Ant qui est installée en même temps que le Serveur IKAN ALM sous ALM_HOME/ant.

Fichier d’exemple:

Modifiez l’emplacement du référentiel (le chemin d’accès et l’URL svn; assurez-vous d’avoir des droits d’écriture) et le chemin d’accès svn bin dans le fichier init_svn/init_svn_repo.properties .

Exemple de fichier de propriétés:

Retenez les propriétés svn.bin.path et svn.repo.remote.URL car nous en aurons besoin lors de la définition du Référentiel Subversion dans IKAN ALM.

Exécutez init_svn_repo.cmd (Windows) ou init_svn_repo.sh (Linux):

Maintenant que le référentiel est créé, nous devons le définir dans IKAN ALM. Dans le contexte de l’Administration globale, sélectionnez Référentiels de contrôle de version > Créer un Référentiel.

L’écran suivant s’affiche:

Sélectionnez Subversion à partir de la liste déroulante dans le champ Type. Le panneau Détails de connexion s’affiche.

Dans le panneau Détails de connexion Subversion, définissez le Chemin de commande et l'URL du Référentiel Subversion tels qu’ils étaient définis dans le fichier des propriétés (svn.bin.path et svn.repo.remote.url). L'ID Utilisateur et le Mot de Passe ne sont pas nécessaires car nous établirons la connexion en utilisant un fichier URL. Établissez la Structure du Référentiel à Orienté projet et le Délai d’expiration à 30 secondes.

Maintenant, nous pouvons réellement entamer la création de notre projet de type Édition versions.

Dans le contexte de l’Administration globale, sélectionnez Projet > Créer un nouveau Projet et remplissez les champs comme indiqué.

Spécifiez le référentiel SVN contenant le projet Docgen et son nom de projet dans le RCV (Docgen). Choisissez ANT comme type d’outil de Construction et Déploiement. En même temps que le Projet, une Branche Principale est créée pointant vers le trunk dans le Projet Docgen dans Subversion. Fournissez un Préfixe de Construction, assurez-vous que le Type de Construction soit établi à Construction complète et établissez le paramètre "Construction forcée autorisée" à Oui.

Sous Cycles de vie > Aperçu, vous verrez que le Cycle de Vie BASE a été créé et qu’il est associé à la Branche Principale HEAD. Cliquez sur le lien Modifier disponible devant le Cycle de vie.

Pour pouvoir exécuter une Construction, nous devons d’abord créer une première étape (un Niveau) dans le Cycle de vie en sélectionnant le lien Créer un Niveau de Construction en-dessous de l’aperçu vide des Niveaux associés.

La plupart des champs sont immédiatement compréhensibles (pour l’instant nous ignorerons les champs "Critère de notification", "Plan horaire" et "Groupe d’utilisateurs du demandeur"). Si vous activez l’option Débogage, il sera plus facile de tracer les actions au début, surtout en cas d’une Construction échouée. Dès que tout se déroulera bien, vous rétablirez l’option à Non. En même temps que le Niveau, les Phases associées au Niveau seront créées. Ces Phases seront exécutées quand une Requête de Niveau sera exécutée sur le Serveur IKAN ALM (à voir plus tard).

Vous pouvez vérifier ces Phases en sélectionnant le lien _ Éditer les Phases_ en-dessous du Niveau de construction sous Niveaux > Aperçu.

Un Niveau est une étape conceptuelle dans le Cycle de Vie. Parce qu’une Machine concrète est nécessaire pour exécuter notre Construction, nous devons établir le lien entre l’Environnement de construction et son Niveau.

Sélectionnez Créer dans le sous-menu Environnements de construction.

La Construction sera exécutée par l’Agent IKAN ALM sur la Machine que nous sélectionnons, et plus précisément par l’Outil de script Ant (1.9.3). Le fichier build.xml est un script Ant que vous pouvez consulter dans les Sources sous /init_svn/source et qui est importé dans le trunk de Subversion du projet Docgen. Le script n’est pas très compliqué: il exécutera quatre cibles Ant: (1) générer un fichier HTML et (2) générer un fichier PDF sur la base du fichier docbook.xml, (3) copier les fichiers résultants vers l’emplacement Cible pour qu’ils soient repris dans le résultat de Construction et, finalement, (4) générer une archive Web pouvant être déployée dans la Cible que nous pourrons déployer (à voir plus tard).

Les Sources seront transférées vers un sous-répertoire dans l’Emplacement Source. Les résultats devront être placés dans l’Emplacement Cible. Notez que, normalement, ces emplacements seront nettoyés après la Construction, sauf si vous activez l’option Débogage, ce que nous faisons pour la même raison que celle que nous avons expliquée pour le Niveau de Construction.

Établissez Construction chargeable à Oui pour que nous puissions télécharger et vérifier le Résultat de construction.

Tout comme pour le Niveau, les Phases associées à l’Environnement sont créées en même temps que l’Environnement de Construction. Elles seront exécutées lorsque la Requête de Niveau de Construction sera exécutée sur l’Agent IKAN ALM (à voir plus tard). Vous pouvez vérifier ces Phases en sélectionnant le lien _ Éditer les Phases_ à côté de l’Environnement de Construction sous Environnements de construction > Aperçu.

Tout est prêt pour démarrer une Construction, sauf que le Niveau a été verrouillé lors de la création: d’abord nous devons vérifier si nos définitions sont cohérentes. Pour ce faire, sélectionnez Auditer le Projet dans le Menu Principal.

Dans l’aperçu, vous verrez la plupart des différents objets que nous venons de créer.

La fenêtre d’information pour le Projet Docgen affiche l’emplacement des Archives de construction de la Branche Principale (où les Constructions futures seront sauvegardées) et le Niveau de Construction contenant un Environnement de Construction sur l’Agent IKAN ALM, où le script build.xml sera exécuté par un Outil de script Ant.

Cliquez sur le lien Déverrouiller et nous sommes prêts à construire!

D’abord nous ajouterons la Branche Principale du Projet Docgen à notre "Bureau". Naviguez vers votre Bureau et cliquez sur le bouton Ajouter au Bureau en bas de l’écran. Dans la fenêtre de sélection, cherchez la Branche Principale (1) du Projet Docgen, sélectionnez-la et cliquez sur Ajouter au Bureau.

Cliquez sur l’icône _ Demander_ dans la colonne Action de notre Branche.

Cliquez sur le lien Montrer les Infos additionnelles.

Notez que l’Environnement de construction est associé au Niveau. Saisissez une description utile, ne modifiez pas la Balise RCV indicative qui sera créée dans Subversion si la Construction réussit, cliquez sur le lien Montrer les Modifications et vérifiez toutes les Sources que nous avons importées dans Docgen/trunk (notre fichier docbook.xml, les scripts de construction et de déploiement, …​) lors de la création du Référentiel Subversion.

Finalement, sélectionnez le bouton Créer.

Vous êtes renvoyés au Bureau en tête duquel est affiché la Requête de niveau que vous avez créée. Cliquez sur son OID ("H_1_b1" si c’est une première installation d’IKAN ALM) pour vérifier ce qui s’est passé lors de la Construction.

Dans la section de l’Administration des projets, éditez le Projet Docgen.

Naviguez vers Cycles de vie > Aperçu, modifiez le Cycle de vie BASE et sélectionnez le lien Créer un Niveau de Test en bas de l’écran.

La création d’un Niveau de Test est très similaire à la création d’un Niveau de Construction. Il y a quelques champs supplémentaires pour la notification que nous ignorerons pour le moment. Le nouveau Niveau sera automatiquement positionné après le Niveau de construction.

Tout comme le Niveau de construction, le Niveau de Test n’est qu’une étape conceptuelle dans le Cycle de vie. Comme une Machine concrète est nécessaire pour déployer notre Résultat de construction, nous devons établir le lien entre l’Environnement de déploiement et son Niveau.

Sélectionnez Créer dans le sous-menu Environnements de déploiement.

Ceci est également très similaire à la création d’un Environnement de construction.

Le Déploiement sera exécuté par l’Agent IKAN ALM sur la Machine sélectionnée, et plus précisément par l’Outil de script Ant (1.9.3) sélectionné.

Nous spécifions que nous déployons le résultat de notre Environnement de construction en l’associant à notre Environnement de déploiement. Le fichier deploy.xml est un script Ant que vous pouvez consulter dans les Sources sous /init_svn/source et qui est également importé dans le trunk de Subversion du projet Docgen.

Le script n’est pas très compliqué: il existe une cible spécifique pour une restauration que nous ignorerons pour le moment; la vraie action est située dans la cible de déploiement vers laquelle l’archive web docgen.war sera copiée sous la cible Tomcat, et nous utiliserons l’application Tomcat manager app pour "recharger" notre archive Web.

Le Résultat de construction précédemment créé sera extrait dans l’Emplacement Source. L’Emplacement Cible doit pointer vers notre Serveur Web Tomcat (TOMCAT_HOME). C’est vers cet emplacement-là que le script deploy.xml transférera le résultat de construction (docgen.war).

Ne vous préoccupez pas des détails à ce sujet. Elle ne fait que placer les fichiers HTML et PDF générés sur le Serveur Web pour que nous puissions les visualiser.

En même temps que l’Environnement de déploiement, des Phases y seront associées également. Elles seront exécutées lorsque la Requête de Niveau de Déploiement sera exécutée sur l’Agent IKAN ALM. Vous pouvez vérifier ces Phases en sélectionnant le lien _ Éditer les Phases_ à côté de l’Environnement de déploiement sous Environnements de déploiement > Aperçu.

Si vous avez déjà vérifié le script de déploiement, vous avez peut-être constaté que certains paramètres doivent être fournis à la tâche de rechargement appliquée à l’application de gestion Tomcat: un URL, et un Utilisateur et un Mot de passe pour l’authentification.

L’application de gestion de Tomcat doit être correctement configurée pour qu’un Utilisateur, ayant des droits de gestionnaire de scripts, puisse faire l’authentification. Au fond, cela revient à configurer le fichier TOMCAT_HOME/conf/tomcat-users.xml comme suit:

Nous devons redémarrer Tomcat pour que ces paramètres soient appliqués. Pour ce faire, vous pouvez exécuter les scripts d’arrêt et de démarrage (si Tomcat est exécuté dans un prompt/shell) ou vous pouvez arrêter et redémarrer le service/daemon Tomcat (si Tomcat est exécuté comme un Service Windows/daemon Unix). Pour plus d’informations, se référer à la Documentation Tomcat.

Pour pouvoir fournir les paramètres au script, au moment où il sera exécuté, nous devons les définir dans notre Environnement de déploiement.

Sélectionnez Environnements de déploiement > Paramètres de déploiement.

Dans l'Aperçu des Paramètres, cliquez sur l’icône _ Créer un Paramètre_ devant l’Environnement de déploiement TST_Tomcat.

D’abord nous spécifierons son URL comme paramètre obligatoire dans le Paramètre tomcat.manager.url. Il utilise la même machine et le même port que l’URL pour l’application Web IKAN ALM (par exemple, http://localhost:9080) suivi de /manager/text.

Ensuite, créez les Paramètres obligatoires tomcat.manager.username (valeur tomcat) et tomcat.manager.password (valeur tomcat), et activez l’option Sécurisé pour le mot de passe (notez qu’il faut saisir le mot de passe deux fois).

Tout comme pour le Niveau de construction, nous devons déverrouiller le Niveau TST_Tomcat.

Sélectionnez Auditer le Projet à partir du menu et cliquez sur le bouton Déverrouiller après avoir vérifié la définition du Projet modifiée qui contient maintenant le Niveau de Test avec l’Environnement de déploiement TST_Tomcat.

Tout comme lors de la création de la Requête de niveau de construction, nous créerons la Requête de niveau de déploiement via le "Bureau".

Sélectionnez l’icône _ Délivrer_ dans la colonne Action du Niveau de Test pour créer la Requête de Niveau pour délivrer.

Saisissez une description utile, sélectionnez la Construction créée précédemment sur notre Niveau de construction, et vérifiez les paramètres de gestion Tomcat que nous avons créés sur notre Environnement de déploiement. Si tout est OK, cliquez sur le bouton Créer.

Pour notre exemple, nous avons créé deux Phases qui reprennent le travail fait par le script build.xml: Generate Doc sur la base du fichier docbook.xml et Generate a simple war. Vous pouvez les trouver dans le fichier Getting Started.zip extrait sous /phases.

Importons d’abord les Phases via Administration globale > Phases > Importer.

Cliquez sur le bouton Sélectionner le Fichier et sélectionnez le fichier associé à la phase Generate Doc (com.ikanalm.generate.doc-1.0.0.jar).

Après l’avoir importée, toutes les informations concernant la Phase, les fichiers y contenus (le fichier generatedoc.xml, qui est un fichier Ant, et la librairie dépendante ant4docbook) seront affichés, ainsi que les paramètres parmi lesquels sourcefile, targetfile.name et targetfile.type sont spécifiques pour la Phase Generate Doc.

Répétez le processus pour la Phase Generate Simple War.

Dans la section "Administration des projets" du Projet Docgen, sélectionnez Environnements de construction > Aperçu.

Ensuite, sélectionnez l’icône _ Éditer les Phases_ à côté de l’Environnement de construction “build”.

Comme les Phases remplaceront notre script, vous pouvez retirer les Phases Vérification du script de construction et Exécution du script, en cliquant sur l’icône _ Retirer_ dans l'Aperçu des Phases.

Maintenant, nous pouvons insérer les Phase requises. Cliquez sur le lien Insérer une Phase en-dessous de l'Aperçu des Phases.

La Phase Generate Doc générera le fichier HTML:

Sélectionnez-la dans la liste des Phases disponibles, établissez la valeur de Abandon si erreur à Oui et insérez-la après la Phase Transfert des Sources (position 2). Si une erreur se produit, nous passerons immédiatement au nettoyage en sélectionnant la Phase Nettoyage Emplacement Source comme Phase suivante si erreur. Puisque nous utiliserons deux fois la Phase "Generate Doc", une première fois pour générer le fichier HTLM et ensuite pour générer le fichier PDF, il sera utile d’ajouter un libellé (dans notre exemple: Generate Doc (HTML)) pour faire la distinction entre les deux Phases.

Répétez ces étapes pour insérer la Phase "Generate Doc" une deuxième fois. Insérez-la après la précédente: cela générera le Fichier PDF. Utilisez les mêmes paramètres pour Abandon si erreur (Oui) et Phase suivante si erreur (Nettoyage Emplacement Source) et ajoutez un libellé (par exemple: Generate Doc (PDF)

Insérez la Phase "Generate Simple War" après la deuxième Phase "Generate Doc".

Ici aussi, utilisez les mêmes paramètres pour Abandon si erreur (Oui) et Phase suivante si erreur (Nettoyage Emplacement Source). Cette Phase ne sera utilisée qu’une seule fois. L’ajout d’un libellé n’est donc pas vraiment nécessaire.

Voilà le résultat dans l'Aperçu des Phases:

Pour que les Phases puissent fonctionner correctement, nous devons modifier quelques paramètres spécifiques.

Cliquez sur l’icône _ Voir les Paramètres_ devant les Phases insérées.

D’abord nous modifierons les paramètres pour la Phase Generate Doc (la première pour générer le fichier HTML): cliquez sur le lien _ Éditer_ à côté du paramètre targetfile.name et établissez sa valeur à "index". La valeur par défaut de target.type est établie à html et ne peut doit être modifiée. En utilisant ces paramètres, la Phase convertira la source docbook.xml en un fichier index.html.

Modifiez la deuxième Phase Generate Doc pour générer le fichier PDF: targetfile.name = docbook, targetfile.type=pdf, ce qui engendrera la génération du fichier docbook.pdf.

Maintenant, modifions la Phase Generate Simple War: la plupart des paramètres sont corrects, il faudra uniquement établir le paramètre "appname" à docgen. En utilisant ces paramètres, un fichier docgen.war sera généré, contenant tous les fichiers du répertoire Source css, les fichiers *.html (HTML) et *.pdf (PDF) qui auront été générés par les 2 Phases précédentes.

Nos Phases sont maintenant insérées dans le flux de travail de l’Environnement de Construction avec les paramètres corrects. Regardons si nous obtenons le même résultat de construction.

Naviguez vers votre Bureau et créer une Requête de Niveau de Construction.

Saisissez la description de la Requête de Niveau, par exemple: “Tester les Phases importées”.

Vérifiez la Requête de Niveau de construction en cliquant sur le lien dans le Bureau (comme expliqué avant): vérifiez les détails de la Requête de niveau, le contenu du fichier de construction et le suivi des Phases de construction.

Generate Doc (HTML): cliquez sur le lien Paramètres de phase pour afficher les paramètres utilisés.

Générer le fichier Simple War: