Configuration d’un laboratoire local Apache Hop avec exemples pratiques

Introduction

Mettre en place un laboratoire local pour Apache Hop est le moyen le plus rapide d'apprendre la plateforme, de prototyper des pipelines de données et de déboguer des transformations sans toucher aux environnements partagés. Ce guide décrit une configuration minimale et reproductible sur un seul poste de travail, puis montre des exemples pratiques de construction et de test d'un pipeline. Il s'adresse aux développeurs, ingénieurs DevOps et équipes techniques de startups qui souhaitent disposer d'un bac à sable sûr pour le développement de pipelines.

L'objectif est la sécurité opérationnelle : observer avant de modifier, limiter le rayon d'impact, utiliser des espaces réservés plutôt que des secrets, vérifier le résultat et documenter comment récupérer si l'état attendu n'est pas atteint. Tous les exemples utilisent un environnement local sans dépendances externes, vous pouvez donc suivre sans accès à un cluster ou à un compte cloud.

Inventaire de la version et de l'environnement

Prérequis

• Java 11 ou 17 : Apache Hop 2.x nécessite Java 11 ou une version ultérieure. Utilisez java -version pour vérifier. Exemple de sortie : openjdk version "17.0.8" 2023-07-18.
• Mémoire suffisante : Hop fonctionne confortablement avec 2 Go alloués à la JVM. Une station de travail avec 8 Go ou plus de RAM totale est recommandée.
• Système d'exploitation : Windows, macOS ou Linux. Les commandes ci-dessous sont présentées pour Linux/macOS ; ajustez les chemins pour Windows.
• Télécharger Apache Hop : Obtenez la dernière distribution binaire stable depuis le site officiel (par exemple, apache-hop-client-2.9.0.zip).

Observation en lecture seule

Avant de modifier quoi que ce soit, inspectez l'état actuel.

# Vérifier la version de Java
java -version

# Vérifier si Hop est déjà installé
which hop

# Vérifier si un répertoire home Hop existe
ls -la ~/hop

Résultat attendu : Java rapporte une version prise en charge (11 ou 17), which hop ne renvoie rien si Hop n'est pas installé, et le répertoire ~/hop n'existe pas. Si Hop est déjà présent, notez sa version et son chemin avant de continuer.

Plus petit changement justifié

Extrayez l'archive zip dans un répertoire dédié, par exemple ~/hop.

mkdir -p ~/hop
cd ~/hop
unzip ../apache-hop-client-2.9.0.zip
# Disposition résultante : ~/hop/apache-hop-client-2.9.0/...

Vérification

Exécutez l'outil en ligne de commande de Hop pour confirmer qu'il démarre.

cd ~/hop/apache-hop-client-2.9.0
./hop-conf.sh --version

La sortie attendue inclut la version de Hop, par exemple : Apache Hop 2.9.0.

Récupération

Si hop-conf.sh échoue, vérifiez l'installation de Java et la variable d'environnement JAVA_HOME.

# Définir JAVA_HOME sous Linux/macOS (ajustez le chemin vers votre JDK)
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
# Vérifier
$JAVA_HOME/bin/java -version

Chemin de configuration sûr

Fichiers de configuration

Hop stocke sa configuration principale dans le répertoire hop-config du home de Hop. Le fichier clé est hop-config/metastore.xml, qui contient les définitions de connexion, les schémas de cluster et d'autres métadonnées partagées. Pour un laboratoire local, la configuration par défaut de la distribution est suffisante. Cependant, pour éviter de se connecter accidentellement à un environnement de production, isolez le laboratoire en utilisant un répertoire de projet séparé.

Créez un dossier de projet dédié pour votre travail :

mkdir -p ~/hop-lab/projects/my-first-project

Variables d'environnement

Définissez HOP_HOME pour pointer vers votre installation Hop. Cette variable est utilisée par les scripts et les plugins.

export HOP_HOME=~/hop/apache-hop-client-2.9.0
# Vérifier
echo $HOP_HOME

Ajoutez cette ligne à votre profil shell (.bashrc, .zshrc, etc.) pour la rendre permanente.

Connexion à la base de données (facultatif)

Pour de nombreux exemples, une base de données locale est utile. Hop inclut un pilote de base de données H2 embarqué, donc aucune base de données externe n'est requise. Pour une configuration plus réaliste, vous pouvez utiliser PostgreSQL ou MySQL. Si vous utilisez PostgreSQL, installez-le localement et créez une base de données pour le laboratoire :

# Exemple sur Ubuntu
sudo apt install postgresql
sudo -u postgres createdb hoplab

Ensuite, dans Hop, créez une nouvelle connexion de base de données dans les métadonnées avec ces paramètres :

• Nom de la connexion : LocalPG
• Type de connexion : PostgreSQL
• Nom d'hôte : localhost
• Nom de la base de données : hoplab
• Port : 5432
• Nom d'utilisateur : hopuser (créez cet utilisateur)
• Mot de passe : utilisez un espace réservé, par exemple ChangeMe123!

Testez la connexion en cliquant sur « Tester » dans l'éditeur de métadonnées. Résultat attendu : « Connexion à la base de données [LocalPG] correcte. »

Récupération : Si le test échoue, vérifiez que PostgreSQL est en cours d'exécution (sudo systemctl status postgresql), que la base de données existe et que l'utilisateur dispose des privilèges. Corrigez les paramètres de connexion et réessayez.

Commandes adaptées à la version

Hop fournit plusieurs outils en ligne de commande :

• hop-run exécute des pipelines et des workflows.
• hop-conf gère la configuration.
• hop-server démarre le serveur Hop pour l'exécution à distance.
• hop-encrypt chiffre les mots de passe à utiliser dans les fichiers de configuration.

Par exemple, pour chiffrer un mot de passe à utiliser dans une connexion :

$HOP_HOME/hop-encrypt.sh -k ~/.hop/security.key -p ChangeMe123!

Sortie attendue : une chaîne chiffrée telle que Encrypted 2be98afc86aa7f2e4cb79ce309ed2ef9a. Utilisez cette chaîne chiffrée dans le champ de mot de passe de la connexion au lieu du texte en clair.

Construction d'un premier pipeline : exemple pratique

Créons un pipeline simple qui lit des données d'un fichier CSV, les transforme et les écrit dans un autre fichier CSV. Cet exemple démontre les concepts fondamentaux de Hop : transformations, hops et champs.

Étape 1 : Créer un fichier CSV d'exemple

Créez un fichier input.csv dans votre répertoire de projet :

id,name,salary
1,Alice,70000
2,Bob,80000
3,Charlie,90000

Étape 2 : Créer un nouveau pipeline

Lancez l'interface graphique de Hop :

cd $HOP_HOME
./hop-gui.sh

Dans l'interface, cliquez sur « Nouveau » -> « Pipeline ». Enregistrez-le sous first-pipeline.hpl dans votre répertoire de projet.

Étape 3 : Ajouter une transformation d'entrée CSV

Dans le dossier « Entrée » de la palette de conception, faites glisser une transformation « Entrée fichier CSV » sur le canevas. Configurez-la :

• Nom de fichier : ~/hop-lab/projects/my-first-project/input.csv
• Délimiteur : ,
• Ligne d'en-tête présente : cochez
• Cliquez sur « Obtenir les champs » pour renseigner les noms de champs : id, name, salary.

Étape 4 : Ajouter une transformation Calculatrice

Faites glisser une transformation « Calculatrice » depuis le dossier « Transformation ». Connectez l'entrée CSV à la calculatrice avec un hop.

Dans la calculatrice, ajoutez un nouveau champ :

• Nouveau champ : salary_with_bonus
• Calcul : salary + (salary * 0.1)

Cela ajoute un bonus de 10 % au salaire.

Étape 5 : Ajouter une transformation de sortie CSV

Faites glisser une transformation « Sortie fichier CSV » depuis le dossier « Sortie ». Connectez la calculatrice à celle-ci.

Configurez la sortie :

• Nom de fichier : ~/hop-lab/projects/my-first-project/output.csv
• Délimiteur : ,
• Inclure la ligne d'en-tête : cochez
• Cliquez sur « Obtenir les champs » pour mapper tous les champs.

Étape 6 : Exécuter le pipeline

Enregistrez le pipeline. Cliquez sur le bouton « Exécuter » (icône de lecture verte). Choisissez l'exécution locale. Le pipeline s'exécute et produit output.csv.

Sortie attendue

Ouvrez output.csv et vérifiez :

id,name,salary,salary_with_bonus
1,Alice,70000,77000.0
2,Bob,80000,88000.0
3,Charlie,90000,99000.0

Vérification

Le journal d'exécution du pipeline ne doit montrer aucune erreur. Dans l'interface, l'onglet « Journalisation » affiche l'état de chaque transformation. L'état final doit être « Terminé » avec une coche verte.

Vérification et diagnostic

Vérification des journaux

Hop écrit les journaux dans logs/ à l'intérieur du répertoire home de Hop. Pour l'interface graphique, les journaux sont affichés dans le panneau des résultats d'exécution. Pour l'exécution en ligne de commande, utilisez :

$HOP_HOME/hop-run.sh -f ~/hop-lab/projects/my-first-project/first-pipeline.hpl -r local

L'option -r local spécifie la configuration d'exécution locale. La sortie comprend les horodatages de début et de fin, le nombre de lignes traitées et les erreurs éventuelles.

Exemple de sortie réussie :

2024/01/15 10:12:34 - first-pipeline - Début de l'exécution.
2024/01/15 10:12:35 - Entrée fichier CSV.0 - Traitement terminé (I=3, O=0, R=0, W=3, U=0, E=0)
2024/01/15 10:12:35 - Calculatrice.0 - Traitement terminé (I=3, O=0, R=0, W=3, U=0, E=0)
2024/01/15 10:12:35 - Sortie fichier CSV.0 - Traitement terminé (I=3, O=0, R=3, W=0, U=0, E=0)
2024/01/15 10:12:35 - first-pipeline - Fin de l'exécution.

Si une erreur se produit, le journal affiche une ligne ERREUR avec une trace de pile. Par exemple, si le fichier d'entrée est manquant :

2024/01/15 10:15:00 - Entrée fichier CSV.0 - ERREUR : Impossible d'ouvrir le fichier '~/hop-lab/projects/my-first-project/missing.csv'

Utilisation du serveur Hop pour le débogage

Pour des pipelines plus complexes, vous pouvez les exécuter sur le serveur Hop et surveiller l'exécution à distance. Démarrez le serveur :

$HOP_HOME/hop-server.sh -p 8080

Ensuite, dans l'interface, créez une nouvelle configuration d'exécution avec « Serveur Hop distant » et spécifiez localhost:8080. Cela vous permet de suivre les étapes du pipeline en temps réel.

Inspection des métadonnées

Utilisez l'explorateur de métadonnées pour vérifier les connexions et les objets partagés. Dans l'interface, cliquez sur « Outils » -> « Métadonnées ». Vérifiez que votre connexion à la base de données apparaît et que le mot de passe chiffré est utilisé.

Modes de défaillance et récupération

Défaillance courante : incompatibilité de version Java

Symptôme : hop-gui.sh ne démarre pas avec UnsupportedClassVersionError ou une erreur de version Java.

Diagnostic : java -version affiche Java 8 ou une version inférieure.

Récupération : Installez Java 11 ou 17 et assurez-vous que JAVA_HOME pointe vers celui-ci. Mettez à jour votre PATH si nécessaire.

Défaillance courante : permissions de fichiers

Symptôme : hop-conf.sh: Permission non accordée.

Diagnostic : Les fichiers extraits peuvent ne pas avoir les permissions d'exécution.

Récupération : Exécutez chmod +x $HOP_HOME/*.sh pour rendre tous les scripts exécutables.

Défaillance courante : mémoire insuffisante

Symptôme : Le pipeline échoue avec java.lang.OutOfMemoryError: Java heap space.

Diagnostic : La taille par défaut du tas JVM peut être trop petite pour de grands ensembles de données.

Récupération : Augmentez la taille du tas en définissant la variable d'environnement HOP_OPTS avant de démarrer Hop :

export HOP_OPTS="-Xmx2048m"

Puis redémarrez Hop.

Défaillance courante : chemin incorrect dans l'entrée CSV

Symptôme : Le pipeline s'exécute mais produit zéro ligne, ou des erreurs « Fichier introuvable ».

Diagnostic : Vérifiez le nom de fichier dans la transformation d'entrée CSV. Assurez-vous d'utiliser un chemin absolu ou un chemin relatif correct.

Récupération : Modifiez la transformation, corrigez le chemin et réexécutez.

Liste de contrôle des opérations

Utilisez cette liste de contrôle avant et après avoir apporté des modifications à l'environnement du laboratoire ou aux pipelines.

Avant les modifications

• [ ] Enregistrez la version actuelle de Hop : $HOP_HOME/hop-conf.sh --version.
• [ ] Enregistrez la version actuelle de Java : java -version.
• [ ] Sauvegardez tous les fichiers de configuration que vous êtes sur le point de modifier (par exemple, hop-config/metastore.xml).
• [ ] Pour les connexions à la base de données, notez le nom de la connexion, l'hôte, le port et le nom de la base de données. N'enregistrez pas les mots de passe.

Après les modifications

• [ ] Vérifiez que Hop démarre : exécutez $HOP_HOME/hop-gui.sh ou $HOP_HOME/hop-conf.sh --version.
• [ ] Pour les pipelines modifiés, exécutez-les en mode local et vérifiez les journaux pour les erreurs.
• [ ] Confirmez que les fichiers de sortie attendus sont créés et ont un contenu correct (par exemple, comparez le nombre de lignes).
• [ ] Testez la récupération : si une défaillance s'est produite, documentez l'erreur exacte et les étapes suivies pour la corriger.

Responsabilité et fréquence d'examen

• Responsable : Le propriétaire désigné de l'environnement du laboratoire (par exemple, Priya Shah, responsable de l'ingénierie) est responsable du maintien de la configuration du laboratoire et de s'assurer que la liste de contrôle est respectée.
• Fréquence d'examen : La configuration du laboratoire et les processus de sauvegarde doivent être examinés mensuellement, ou après toute mise à niveau majeure de la version de Hop.

Pièges courants et comment les éviter

Piège 1 : Mélanger les métadonnées du laboratoire et de la production

Pourquoi cela arrive : Les développeurs peuvent importer des métadonnées de production dans le laboratoire pour tester avec de vraies connexions.

Comment éviter : Utilisez toujours des projets séparés ou des homes Hop séparés pour le laboratoire et la production. Si vous devez copier, modifiez tous les paramètres de connexion en espaces réservés locaux et chiffrez les mots de passe avec une clé spécifique au laboratoire.

Récupération : Si vous avez accidentellement utilisé une connexion de production, révoquez immédiatement les informations d'identification et modifiez-les dans le système de production. Supprimez les métadonnées importées du laboratoire.

Piège 2 : Ne pas versionner les pipelines

Pourquoi cela arrive : Les pipelines de laboratoire sont souvent considérés comme jetables, donc ils ne sont pas validés dans le contrôle de version.

Comment éviter : Initialisez un dépôt Git dans votre répertoire de projet et validez régulièrement les fichiers de pipeline (.hpl, .hwf).

cd ~/hop-lab/projects/my-first-project
git init
git add *.hpl
git commit -m "Pipeline initial"

Piège 3 : Coder en dur les secrets dans les transformations

Pourquoi cela arrive : Pour des tests rapides, les développeurs peuvent mettre des mots de passe en clair directement dans les configurations de transformation.

Comment éviter : Utilisez le système de variables intégré de Hop et les valeurs chiffrées. Définissez des variables dans kettle.properties (situé dans $HOP_HOME/config) et référencez-les dans les transformations avec ${VARIABLE_NAME}. Chiffrez les variables sensibles à l'aide de hop-encrypt.

Récupération : Recherchez les secrets en texte clair dans vos fichiers de projet en utilisant grep -r 'password' . et remplacez-les par des variables ou des chaînes chiffrées.

Piège 4 : Ignorer la compatibilité des versions de Hop avec les plugins

Pourquoi cela arrive : Les utilisateurs peuvent installer des plugins de différentes versions de Hop, provoquant des conflits de classes.

Comment éviter : N'installez que des plugins depuis le Hop Marketplace qui correspondent à votre version de Hop. Vérifiez toujours la matrice de compatibilité du plugin.

Récupération : Si un plugin provoque un échec au démarrage, supprimez-le de $HOP_HOME/plugins et redémarrez Hop.

Conclusion

Un laboratoire local Apache Hop vous offre un environnement sûr et contrôlé pour construire et tester des pipelines de données. En suivant les pratiques observables et adaptées à la version décrites dans ce guide, vous pouvez éviter les pièges courants et récupérer rapidement en cas de défaillance. Commencez par le pipeline CSV simple, puis étendez aux connexions de base de données et aux workflows plus complexes. N'oubliez pas de garder votre laboratoire isolé de la production, de versionner votre travail et de documenter chaque étape de récupération. Avec ces habitudes, votre laboratoire Hop deviendra une base fiable pour le développement de pipelines.