JenkinsLa partie web de Geolocgame est réalisée en PHP. Nous avons utilisé Jenkins pour deux tâches, l’intégration continue et le déploiement automatique.

La première consiste à analyser le code, exécuter des tests unitaires (TU) et fournir des statistiques dans le but d’améliorer la qualité du code. Les TU sont très importants, à chaque modification du programme, cela nous permet de savoir si toutes les fonctionnalités existantes fonctionnent toujours correctement.

La seconde tâche réalisée avec Jenkins est le déploiement automatique. Pour installer une nouvelle version de Geolocgame, nous avons un certain nombre d’étapes à réaliser. Cela fait énormément de travail si on réalise ces opérations à la main, sans compter les erreurs de manipulation.

 

Prérequis

  • Jenkins avec les plugins Parameterize Trigger, Checkstyle, Clover Php, JDepend, Plot, DRY, HTML Publisher, PMD, xUnit, Violations et Git (uniquement si vous utiliser un repo Git, Subversion est géré par défaut).
  • Phar avec les outils Phing, PhpUnit, Php_CodeSniffer, PhpLOC, Php_Depend, PhpMD, PhpCPD et PhpDoc.

 

Intégration continue

Le tuto ci-dessous est basé sur le travail de Sebastian Bergmann, depuis que nous avons installé notre plateforme, le projet à quelque peu évolué. Vous pouvez utiliser les fichiers de configuration de notre tuto ou ceux de Sebastien Bergmann.

Préparer le projet/application

Le travail de Jenkins va consister à exécuter une série de tâche “Ant”. Pour cela vous devez avoir installé Phar avec la liste des outils. Jenkins utilise un fichier build.xml dans lequel est répertorié tout ce qu’il doit faire. Ce fichier doit être placé à la racine de votre projet (exemple build de Geolocgame). En complément les outils Checkstyle, PhpMD et PhpUnit ont besoin de fichier de configuration. Ajouter un dossier “build” à la racine de votre projet. Placer les trois fichiers suivant à l’intérieur :

  • Checkstyle : définit la liste des règles à utiliser pour vérifier le style/indentation/nommage…
  • PhpMD : liste des règles pour analyser la qualité du code
  • PhpUnit : indique à PhpUnit de créer un rapport de couverture des tests unitaires au format HTML et XML

Dans le dossier “build” créer un sous-répertoire “logs”, il contiendra les résultats d’exécution des différents programmes.

Importer le template

Jenkins utilise un répertoire de travail où il stock les fichiers de configuration des jobs et le résultat des builds, sous Windows le dossier par défaut est “C:\.jenkins”. Dans ce dossier allez dans “jobs”, puis créez un sous-répertoire “php-template”. A l’intérieur placez ce fichier config.xml. Vous aurez besoin de redémarrer Jenkins pour prendre en compte ce nouveau job.

Ce template servira de modèle pour la création de votre job. Il contient toute la configuration nécessaire pour pouvoir personnaliser l’affichage des résultats des différents outils d’analyse.

Créer un nouveau job

Connectez-vous à Jenkins, puis ajoutez un nouveau Job, donnez-lui un nom, choisissez l’option “Copier un Job existant”, puis entrez “php-template”. Cliquez sur “Ok”. Vous arrivez ensuite sur la page de configuration, la seule modification à faire concerne la “Gestion de code source”. Selon le gestionnaire de source que vous utilisez, cochez la bonne option et entrez l’url ainsi que les identifiants. Une fois terminée, cliquez sur le bouton “Sauver”.

Vous pouvez maintenant lancer votre premier build. Patientez quelques minutes, puis vous rafraîchissez la page et vous pourrez voir les différents graphiques, avoir accès à la documentation, le résultat détaillé de la couverture des tests, l’analyse Checkstyle, PhpMD…

 

Déploiement automatique

Liste des taches Jenkins

Comme pour l’intégration continue, Jenkins utilise un fichier XML pour savoir la liste des tâches à exécuter. Créez à la racine de votre projet un fichier build_Deploy.xml. Ce fichier doit être personnalisé pour votre application. Ci-dessous le détail de chaque section.

Suppression et création des dossiers de travail de PhpUnit

Exécution des tests unitaires

PhpUnit utilise un fichier de configuration, prendre le même que pour l’intégration continue.

Configuration environnement

Si votre application comporte une configuration différente selon l’environnement où elle est déployée, vous pouvez utiliser Jenkins pour spécifier l’environnement cible et supprimer les fichiers inutiles. Pensez à adapter les chemins et noms des fichiers. La variable ${basedir} est fourni par Jenkins, elle correspond au répertoire racine du projet. Dans ce bloc générique, la variable ${env} permet de définir la cible. La valeur est définit dans la configuration du job, voir la sous-section “Propriétés” de la section “Appeler Ant”. Les variables sont définies comme suit :

Génération de la documentation

Vous pouvez utiliser PhpDoc pour générer la documentation. Ici seuls les fichiers contenus dans le dossier “module” seront analysés. La documentation au format HTML sera placée dans le dossier “doc”.

Passage en mode maintenance

Pendant le déploiement de l’application, il est préférable que les utilisateurs accède à un message de maintenance plutôt qu’à une version potentiellement instable. Pour cela, on place par exemple un fichier index.html à la racine du site, ensuite on supprime le fichier index.php. Dans l’exemple ci-dessous, on utilise SCP pour le transfert de fichiers et SSH pour exécuter une commande. Les variables suivantes doivent être spécifiées dans le job, voir la sous-section “Propriétés” de la section “Appeler Ant”.

Envoi des fichiers

On utilise SCP pour transférer les fichiers de l’application. Le bloc “fileset” permet de spécifier les fichiers et dossiers à inclure et ceux à exclure.

Création de dossiers

Selon le cas, il peut être nécessaire de créer des dossiers, par exemple pour la gestion du cache.

Nettoyage du cache

Pour être certain qu’après la mise en ligne les visiteurs récupèrent la nouvelle version des fichiers mis en cache, on supprime le contenu dossier “cache”.

Suppression maintenance

L’application est maintenant prête à être utilisée, on peut donc supprimer la maintenance.

 

Création des jobs

Toutes les tâches peuvent être réalisées par un job ou plusieurs. Si quelque chose ce passe mal, il est utile de pouvoir relancer certaines traitement, c’est pourquoi j’ai découpé le processus en quatre étapes. Seul le premier job sera lancé manuellement. Une fois le premier fini, il déclenchera le second et ainsi de suite. Jenkins gère ce type de fonctionnement par défaut, cependant, il n’est possible de passer des paramètres d’un job au suivant. L’alternative est d’utiliser le plugin “Parameterize Trigger” pour déclencher les builds et faire suivre les paramètres.

Les jobs sont créés avec l’option “Construire un projet free-style”.

Récupération des sources et tests unitaires

Ce premier job consiste à aller chercher les sources de l’application, par exemple via Git. Ensuite, on effectue trois tâches, elles doivent être spécifiées dans la sous-section “Cibles” de la section “Appeler Ant”.

Préparation de l’application

Génération de la documentation

Déploiement

 

Conclusion

Ce tuto est une première étape vers l’automatisation. J’ai détaillé le plus possible, si vous avez des questions n’hésitez pas.

Des articles suivront pour expliquer comment :

  • utiliser Phing pour la gestion de version sur la base de données
  • mettre à jour le schéma de la BD avec DoctrineORM
  • utiliser Composer pour gérer les dépendances et ajouter les étapes dans le build Jenkins
  • conditionner certaines tâches
  • intégrer un numéro de version à chaque build