Les projets Node-RED transforment vos flows en dépôt git : chaque modification est validée, relisible et réversible. Dans ce tutoriel, vous allez activer le mode projets, créer un projet, valider et pousser vers un dépôt distant, le cloner sur une autre machine et, surtout, garder les identifiants de votre broker MQTT chiffrés et hors du dépôt.
Pourquoi versionner vos flows
Sans les projets, Node-RED conserve tout dans un unique fichier flows.json situé dans le répertoire utilisateur. Lorsque quelqu'un déploie une modification défectueuse, il n'y a aucun historique à consulter et aucun moyen simple de revenir en arrière. Des copies de flows circulent par e-mail ou par messagerie sous forme de JSON exporté, et personne ne sait vraiment quelle version tourne en production.
Les projets règlent ce problème avec des outils que les développeurs connaissent déjà :
- Historique. Chaque commit enregistre qui a modifié quoi et quand.
- Diffs. L'éditeur affiche les différences au niveau des nœuds avant le commit.
- Branches. Testez une modification risquée sur une branche, puis fusionnez-la quand elle fonctionne.
- Dépôts distants. Poussez vers GitHub, GitLab, Gitea ou Azure DevOps pour la sauvegarde et la collaboration.
- Dépendances. Chaque projet possède un
package.jsonqui liste les nœuds nécessaires, pour qu'une nouvelle machine sache quoi installer.
Prérequis
Les projets s'appuient sur la ligne de commande git et, pour les dépôts distants SSH, sur ssh-keygen. Vérifiez que les deux sont installés sur la machine qui exécute Node-RED :
git --version
ssh-keygen -h 2>&1 | head -1
Sous Debian, Ubuntu ou Raspberry Pi OS, installez git avec sudo apt install git. L'image Docker officielle inclut déjà git.
Activer les projets Node-RED
Le mode projets est désactivé par défaut. Ouvrez settings.js dans votre répertoire utilisateur (~/.node-red/settings.js, ou /data/settings.js sous Docker), trouvez la section editorTheme et activez-le :
editorTheme: {
projects: {
enabled: true,
workflow: {
// "manual" : vous validez explicitement
// "auto" : Node-RED crée un commit à chaque déploiement
mode: "manual"
}
}
},
Redémarrez Node-RED. À la première ouverture de l'éditeur, un écran d'accueil propose de créer un projet, de cloner un dépôt ou de passer cette étape. Le mode manuel est le meilleur choix par défaut pour les équipes : vous déployez aussi souvent que vous le souhaitez pendant vos tests et ne validez que lorsqu'une modification est prête, avec un message explicite.
Créer votre premier projet
- Choisissez Create Project sur l'écran d'accueil, ou plus tard via Projects → New dans le menu principal.
- Saisissez votre nom d'utilisateur et votre e-mail git si on vous les demande ; ils apparaissent dans l'historique des commits.
- Nommez le projet, par exemple
plant-telemetry. - Choisissez un nom de fichier de flow. Le
flow.jsonpar défaut convient. - Configurez le chiffrement des identifiants. Choisissez « Enable encryption » et saisissez une clé robuste. Conservez-la dans votre gestionnaire de mots de passe.
- Cliquez sur Create Project.
Node-RED crée un dossier sous projects/ dans le répertoire utilisateur, avec cette structure :
~/.node-red/projects/plant-telemetry/
.git/
.gitignore
README.md
package.json
flow.json
flow_cred.json
Le fichier d'identifiants est chiffré avec la clé de l'étape 5, et cette clé est stockée dans les paramètres locaux de votre runtime Node-RED, pas dans le dépôt. C'est cette conception qui garde les mots de passe du broker hors de git : le dépôt ne contient que du texte chiffré, et seules les machines auxquelles vous confiez la clé peuvent le déchiffrer.
Construire un flow et le valider
Ajoutez un flow MQTT simple pour avoir quelque chose à versionner. Configurez un nœud broker pour le serveur MQTT public gratuit avec le serveur broker.connectmq.com, le port 1883 et un client ID unique comme nr-proj-a19e. Abonnez un nœud mqtt in à connectmq/demo/a19e/# et reliez-le à un nœud debug. Déployez. Ce serveur public est réservé aux tests et aux prototypes, pas aux données de production.
Ouvrez l'onglet Project history dans la barre latérale (l'icône git). Sous Local Changes, le fichier de flow apparaît comme modifié. Cliquez dessus pour voir un diff visuel des nœuds ajoutés. Indexez le fichier, rédigez un message de commit comme « Add telemetry subscriber » et validez.
Faites maintenant une modification, par exemple renommer le nœud debug, et déployez de nouveau. L'onglet d'historique affiche un nouveau diff portant exactement sur cette modification. C'est là que les projets Node-RED prennent tout leur sens : lors d'une relecture, vous voyez qu'une seule propriété a changé plutôt qu'un bloc JSON illisible.
Pousser vers un dépôt distant
Créez un dépôt vide sur votre hébergeur git. Dans Node-RED, ouvrez Projects → Project Settings → Settings → Git remotes et ajoutez l'URL du dépôt distant.
Pour les dépôts distants SSH, générez une clé dans Node-RED via User Settings → Git config → SSH Keys → Add key. Node-RED affiche la clé publique ; ajoutez-la sur votre hébergeur git comme deploy key avec accès en écriture. Les dépôts distants HTTPS avec un jeton d'accès personnel fonctionnent également, et Node-RED demandera les identifiants au premier push.
De retour dans l'onglet d'historique, la section Commit History affiche désormais des flèches push et pull. Poussez vos commits. Depuis le terminal, vous pouvez vérifier le contenu du dépôt :
git clone git@github.com:your-org/plant-telemetry.git
cd plant-telemetry
cat flow_cred.json # affiche du texte chiffré comme {"$":"8f2c..."}
Garder les identifiants du broker hors de git
Les identifiants exigent une stratégie réfléchie. Vous avez trois options raisonnables :
| Stratégie | Ce qui va dans git | Gestion de la clé | Adapté à |
|---|---|---|---|
| Fichier d'identifiants chiffré (par défaut) | flow_cred.json sous forme chiffrée |
Clé saisie une fois par machine | La plupart des équipes |
| Ignorer le fichier d'identifiants | Rien | Identifiants saisis sur chaque instance | Politiques strictes interdisant tout secret dans git |
| Variables d'environnement | Uniquement des références ${VAR} dans des champs non secrets, les secrets dans l'environnement |
Définies par environnement | Conteneurs et pipelines CI |
Pour la deuxième option, ajoutez flow_cred.json au .gitignore et ressaisissez le nom d'utilisateur et le mot de passe MQTT sur chaque instance après le clonage. Pour la troisième, définissez des valeurs comme l'hôte du broker ou le préfixe de client ID en variables d'environnement, et lisez-les dans les propriétés des nœuds avec ${MQTT_HOST} ou dans les nœuds function avec env.get().
Quel que soit votre choix, suivez deux règles. Ne collez jamais un mot de passe dans un nœud function ou un nœud inject, car ils sont stockés en clair dans le fichier de flow. Et utilisez des identifiants de broker distincts par environnement, pour qu'une instance de développement ne puisse jamais publier sur des topics de production ; avec ConnectMQ, cela peut être aussi simple qu'un broker séparé par environnement. Notre check-list pour sécuriser Node-RED couvre les autres étapes de durcissement.
Cloner un projet sur une autre machine
Sur une seconde instance Node-RED avec les projets activés, choisissez Projects → New → Clone Repository, saisissez l'URL du dépôt distant et, si le fichier d'identifiants est chiffré, la clé des identifiants. Node-RED clone le dépôt, lit package.json et vous indique quels nœuds manquent. Installez-les depuis l'invite ou avec npm dans le dossier du projet, puis déployez.
Avec Docker, clonez dans le dossier monté /data/projects pour que le projet survive à la recréation du conteneur ; consultez notre guide Node-RED avec Docker pour la configuration du volume.
Check-list du workflow des projets Node-RED
- Activez les projets en mode manuel et redémarrez Node-RED.
- Créez un projet par application déployable, pas un par onglet.
- Activez le chiffrement des identifiants et conservez la clé dans un gestionnaire de mots de passe.
- Listez chaque nœud contribué dans
package.jsonavec une plage de versions. - Validez des modifications petites et décrites ; relisez les diffs avant de valider.
- Utilisez des branches pour les expérimentations et fusionnez une fois testé.
- Poussez vers un dépôt distant après chaque commit significatif.
- Gardez les valeurs propres à chaque environnement dans des variables d'environnement, pas dans le flow.
- Utilisez des identifiants MQTT distincts pour les brokers de développement et de production.
La logique réutilisable est plus facile à versionner lorsqu'elle se trouve dans des sous-flux Node-RED, car une modification d'un modèle apparaît comme un diff unique et clair. La documentation officielle des projets couvre les réglages avancés et l'interface complète de l'éditeur. Si vous débutez avec MQTT dans Node-RED, commencez par le tutoriel Node-RED MQTT.
Versionnez vos flows, laissez ConnectMQ gérer le broker
Les projets apportent à vos flows un historique et des déploiements reproductibles ; le broker auquel ils se connectent doit être tout aussi fiable. ConnectMQ est un broker MQTT managé avec MQTT 3.1.1 et 5.0, TLS sur le port 8883 et des identifiants propres à chaque broker : il est donc simple de créer des brokers distincts pour le développement et la production et de séparer les identifiants de chaque environnement. Commencez avec l'offre gratuite Serverless sur app.connectmq.com, sans carte bancaire. Pour comparer les approches d'hébergement, consultez notre panorama de l'exploitation d'un broker MQTT dans le cloud.
Questions fréquentes
Comment activer les projets dans Node-RED ?
Définissez editorTheme.projects.enabled à true dans settings.js, vérifiez que git est installé et redémarrez Node-RED. L'éditeur propose alors de créer ou de cloner un projet.
Les mots de passe MQTT sont-ils stockés dans git avec les projets Node-RED ?
Uniquement sous forme chiffrée, si vous activez le chiffrement des identifiants. Le fichier d'identifiants contient du texte chiffré, et la clé reste sur chaque machine. Vous pouvez aussi ajouter le fichier d'identifiants au .gitignore.
Puis-je utiliser GitHub avec les projets Node-RED ?
Oui. Ajoutez le dépôt comme dépôt distant en SSH avec une clé générée dans Node-RED, ou en HTTPS avec un jeton, puis poussez et tirez depuis la barre latérale Project history.
Quelle est la différence entre les modes de workflow manuel et automatique ?
En mode manuel, vous validez explicitement lorsqu'une modification est prête. En mode automatique, Node-RED crée un commit à chaque déploiement, ce qui est plus simple mais produit un historique plus bruyant.
