Installer Backstage en local avec Node 22 et Yarn 4 : tutoriel pas à pas

Article principal : Plateforme de développeur interne avec Backstage : architecture pour startup
Ce tutoriel s’inscrit dans la série Platform Engineering et Backstage. Pour la vue d’ensemble du sujet, lire d’abord le guide principal.

À quoi sert ce tutoriel

Avant d’envisager la moindre intégration en production, il faut faire tourner Backstage en local. Cette étape paraît anodine — on lance une commande, c’est censé marcher — mais elle réserve plusieurs pièges : version de Node.js incompatible, Yarn défaillant, dépendance native qui refuse de compiler, port occupé, base SQLite verrouillée. Ce guide pas-à-pas couvre l’installation propre de Backstage v1.50.x (dernière publication v1.50.4 au 29 avril 2026) sur un poste Linux ou WSL, depuis la vérification des prérequis jusqu’au premier ajout d’un service dans le catalogue. À la fin, vous aurez un portail Backstage fonctionnel sur http://localhost:3000, capable de référencer des services et de servir de bac à sable pour la suite des tutoriels.

Le tutoriel suppose un poste Linux Ubuntu 22.04 ou 24.04, ou un environnement WSL2 sous Windows avec Ubuntu installé. Sur macOS, les commandes restent valables modulo l’utilisation de Homebrew au lieu d’apt. Le temps total est de quarante minutes à une heure suivant la vitesse de la connexion.

Prérequis matériels et logiciels

Backstage est gourmand. La documentation officielle indique au minimum six gigaoctets de RAM et vingt gigaoctets d’espace disque pour un environnement de développement. Sur un poste avec quatre gigaoctets de RAM, l’installation peut aboutir mais le démarrage de yarn dev consomme jusqu’à deux gigaoctets et concurrence brutalement les autres outils. Il faut un processeur 64 bits, une connexion réseau stable parce que la première installation télécharge plusieurs centaines de mégaoctets de paquets npm.

Côté logiciels, on a besoin de Node.js 22 ou 24 (versions Active LTS au moment de la rédaction), Yarn 4.4.1, Docker, Git, ainsi que la chaîne de build C — make, build-essential — parce qu’une dépendance native nommée isolated-vm est compilée à l’installation. Vouloir s’en passer mène à un échec. Sur Ubuntu, l’installation de cette chaîne de build se fait avec sudo apt install build-essential.

Étape 1 — Vérifier ou installer Node.js 22

Backstage refuse de tourner sur des versions non supportées. La règle officielle est two adjacent even-numbered LTS releases, ce qui signifie aujourd’hui Node 22 et Node 24. Pour vérifier la version actuelle, on tape la commande dans un terminal et on lit la sortie. Si vous voyez une version 18 ou 20, il faut mettre à jour avant de continuer, sinon vous heurterez des erreurs de compilation à l’installation des paquets.

node --version
# v22.12.0
yarn --version 2>/dev/null || echo "yarn pas encore installe"

Une sortie de la forme v22.x.y ou v24.x.y est ce qu’on cherche. Si Node n’est pas installé ou si la version est ancienne, on utilise nvm (Node Version Manager) qui est l’outil recommandé par la doc Backstage parce qu’il permet de basculer entre versions sans casser les autres projets de la machine.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install 22
nvm use 22

L’installation de nvm écrit dans le fichier ~/.bashrc ou ~/.zshrc et il faut soit relancer le shell, soit recharger le fichier avec source ~/.bashrc. Après nvm use 22, la commande node --version doit retourner une version 22.x. Si ce n’est pas le cas, vérifier que nvm est bien dans le PATH avec which nvm.

Étape 2 — Activer Yarn 4.4.1 via Corepack

Yarn 4 ne s’installe plus via npm comme l’ancienne version 1. Le bon réflexe est d’utiliser Corepack, un utilitaire livré avec Node.js qui pilote les versions des gestionnaires de paquets alternatifs. Corepack est en standby par défaut depuis Node 22, il faut donc l’activer une fois pour toutes.

corepack enable
corepack prepare yarn@4.4.1 --activate
yarn --version
# 4.4.1

La commande corepack prepare yarn@4.4.1 --activate télécharge Yarn 4.4.1 et le marque comme version par défaut globale. Le yarn --version doit retourner exactement 4.4.1 pour que Backstage fonctionne sans accroc. Une version antérieure (par exemple 1.22.x installée par npm install -g yarn) provoque des erreurs subtiles dans le monorepo et il faut la désinstaller en supprimant le binaire global.

Étape 3 — Installer la chaîne de build et Docker

Une dépendance critique de Backstage est isolated-vm, qui isole l’exécution du code généré par le scaffolder dans une machine virtuelle V8 séparée. Ce paquet est en C++ et se compile à l’installation. Sans la chaîne de build, l’installation de Backstage échoue avec une erreur incompréhensible mentionnant node-gyp. On installe donc les outils nécessaires en une seule commande.

sudo apt update
sudo apt install -y build-essential libpython3-dev python3 python3-pip git curl wget

La commande installe le compilateur GCC, les en-têtes Python utilisées par node-gyp, et Git si ce n’est pas déjà fait. Sur macOS, l’équivalent est xcode-select --install qui pose la chaîne de build Apple. Pour Docker, qui sert à TechDocs et à certains scaffolder advanced, on suit la procédure officielle Docker — sudo apt install docker.io sur Ubuntu suffit pour le développement local.

Vérifier ensuite que Docker démarre avec sudo systemctl status docker et qu’on peut le lancer sans sudo en s’ajoutant au groupe docker : sudo usermod -aG docker $USER puis se déconnecter et se reconnecter pour que le groupe prenne effet.

Étape 4 — Créer l’application Backstage

Avec les prérequis en place, la création de l’app est l’étape la plus longue parce qu’elle télécharge l’écosystème npm complet du monorepo. Backstage fournit un générateur officiel via npx qui clone un squelette préconfiguré avec frontend, backend, dépendances et fichier de configuration de base. La commande prompt deux questions : le nom de l’application et le nom du dossier.

npx @backstage/create-app@latest
# ? Enter a name for the app: my-idp
# Creating the app...
# 🥇 Successfully created my-idp

Le générateur télécharge le squelette, exécute yarn install, déclenche la compilation de isolated-vm et de better-sqlite3. Sur une connexion correcte la commande prend dix à quinze minutes et utilise environ trois gigaoctets de RAM en pointe. Si l’installation échoue avec un message node-gyp, c’est que la chaîne de build de l’étape 3 est manquante ou incomplète. Si elle échoue sur better-sqlite3, c’est généralement un problème de version Node — vérifier qu’on est bien en 22 ou 24.

À la fin, on entre dans le dossier généré et on regarde la structure. Le monorepo contient trois éléments principaux : packages/app/ qui héberge le frontend React, packages/backend/ qui héberge le backend Node.js, et app-config.yaml à la racine qui pilote la configuration. Une commande tree -L 2 -d donne un aperçu rapide de l’architecture.

Étape 5 — Lancer Backstage en mode développement

Le moment de vérité arrive. Le mode développement lance frontend et backend en parallèle, chacun en mode hot-reload qui recompile à chaque modification de fichier. Le port frontend est 3000 par défaut, le port backend 7007. La commande à exécuter dans le dossier de l’app, en une seule ligne, est yarn dev.

cd my-idp
yarn dev

Le démarrage prend environ une minute, et les logs montrent successivement le démarrage du backend, puis du frontend. Quand on voit webpack compiled successfully et [backend]: Listening on :7007, le portail est prêt. On ouvre http://localhost:3000 dans un navigateur, on est accueilli par la page d’authentification développement (guest sign-in) sur laquelle on clique pour entrer.

La première vue est le portail Backstage avec son menu latéral : Home, Catalog, APIs, Docs, Create. Le catalogue contient quelques entités de démonstration. Si vous voyez cette interface, l’installation est réussie. Si le navigateur affiche une page blanche ou une erreur 502, vérifier que le backend tourne bien — il arrive que des conflits de port avec une autre application coupent le démarrage. Le lsof -i :7007 liste les processus qui occupent le port.

Étape 6 — Ajouter sa première entité dans le catalogue

Pour valider que tout fonctionne au-delà de la page d’accueil, on ajoute une entité minimale au catalogue. Le moyen le plus simple est de créer un fichier catalog-info.yaml dans un dépôt GitHub public que Backstage va lire à la volée. Pour les besoins du tutoriel, on utilise un fichier local référencé en file: URL.

# exemple-service.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: hello-service
  description: Service de demonstration
spec:
  type: service
  lifecycle: experimental
  owner: guest

On enregistre ce fichier à la racine de l’app, puis on l’enregistre dans Backstage via l’interface : Catalog → Self-service → Register existing component → URL file:///chemin/vers/exemple-service.yaml. Backstage parse le fichier, valide la structure et ajoute l’entité. La page Catalog liste désormais hello-service avec Owner: guest et Type: service. Si l’enregistrement échoue avec une erreur de validation, c’est que le YAML est mal indenté ou qu’un champ obligatoire manque — relire la spec officielle au mot près.

Étape 7 — Configurer l’authentification GitHub

Le mode guest est pratique pour tester mais inadapté à toute utilisation réelle. La première configuration sérieuse est l’authentification GitHub OAuth, qui sert à la fois à l’identification des utilisateurs et à l’accès aux dépôts pour le scaffolder et le discovery. On crée une OAuth App dans GitHub via Settings → Developer settings → OAuth Apps → New OAuth App.

Les paramètres à fournir sont : Application name (libre, par exemple « Backstage local »), Homepage URL (http://localhost:3000), Authorization callback URL (http://localhost:7007/api/auth/github/handler/frame). Une fois créée, GitHub fournit un Client ID et permet de générer un Client Secret. On copie ces deux valeurs.

export AUTH_GITHUB_CLIENT_ID="Iv1.xxxxxxxxxxxx"
export AUTH_GITHUB_CLIENT_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

On édite ensuite app-config.yaml à la racine pour activer le provider GitHub. La section auth existe déjà avec un placeholder, il suffit de décommenter le provider github et de pointer sur les variables d’environnement.

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}

Après redémarrage avec yarn dev, la page de connexion propose désormais le bouton Sign in with GitHub à côté du guest sign-in. Un clic redirige vers GitHub pour autoriser l’application, puis revient sur Backstage authentifié sous l’identité GitHub. Si la redirection retourne un erreur 404 ou callback mismatch, c’est que l’URL de callback dans la OAuth App ne correspond pas exactement à celle attendue par Backstage — l’erreur la plus courante est d’avoir oublié /handler/frame à la fin.

Étape 8 — Activer la base PostgreSQL pour persister

SQLite suffit pour démarrer mais on perd les données à chaque redémarrage en mode développement. Pour expérimenter sérieusement, on bascule sur PostgreSQL qui est aussi la base recommandée pour la production. La méthode la plus rapide est un container Docker dédié, qu’on lance en arrière-plan et qu’on garde tournant pour la session de développement.

docker run -d --name backstage-pg \
  -e POSTGRES_PASSWORD=backstage \
  -e POSTGRES_USER=backstage \
  -e POSTGRES_DB=backstage \
  -p 5432:5432 \
  postgres:16

Le container expose PostgreSQL 16 sur le port 5432 avec les identifiants backstage / backstage / backstage. La commande docker ps confirme qu’il est UP. Pour la production évidemment on n’utilise jamais ces identifiants triviaux, mais en local ça simplifie la mise en route.

backend:
  database:
    client: pg
    connection:
      host: 127.0.0.1
      port: 5432
      user: backstage
      password: backstage
      database: backstage

On édite app-config.local.yaml (et pas app-config.yaml, qui doit rester versionnable sans secret) pour pointer le backend sur PostgreSQL. Au redémarrage de yarn dev, Backstage détecte la nouvelle config, lance les migrations sur la base et garde désormais l’état entre redémarrages. Pour vérifier, on peut se connecter à la base avec docker exec -it backstage-pg psql -U backstage et lister les tables avec \dt — on doit voir une bonne quinzaine de tables avec des préfixes comme backstage_plugin_catalog_.

Étape 9 — Vérifier l’installation de bout en bout

L’étape finale consiste à exécuter une checklist rapide pour s’assurer que rien n’a été cassé en cours de route. Cette vérification prend cinq minutes et évite les surprises au moment de partager le portail avec un collègue.

curl -s http://localhost:7007/api/catalog/entities | head -c 200
curl -s http://localhost:7007/healthcheck
docker ps | grep backstage-pg
yarn --version
node --version

La première commande doit retourner un tableau JSON contenant au moins l’entité hello-service ajoutée à l’étape 6. La seconde retourne {"status":"ok"} ou similaire. La troisième confirme que la base PostgreSQL est UP. Les deux dernières confirment qu’on est bien sur Yarn 4.4.1 et Node 22.x. Si une de ces sorties est anormale, c’est qu’une étape précédente a partiellement échoué et il faut remonter le tutoriel pour identifier l’erreur.

Erreurs fréquentes

Tutoriels associés

• Software Catalog Backstage : référencer ses services avec catalog-info.yaml
• Scaffolder Backstage : créer un template de microservice Node.js
• TechDocs Backstage : documenter ses services avec MkDocs

Pour aller plus loin

Retour au guide principal : Plateforme de développeur interne avec Backstage : architecture pour startup.

• Backstage — Getting Started (documentation officielle d’installation)
• Backstage — Configuration (référence app-config.yaml)
• Backstage — GitHub authentication (provider OAuth)
• nvm-sh/nvm (gestionnaire de versions Node)
• Yarn — Installation via Corepack

FAQ

Puis-je utiliser Node.js 20 au lieu de 22 ?
Non, pas avec Backstage v1.50.0. Le projet suit une politique two adjacent even-numbered LTS et la version 1.46 a déjà supprimé Node 20. Tenter de lancer Backstage sur Node 20 produit des erreurs de syntaxe sur des features ES2023 utilisées par le code généré.

Le démarrage avec yarn dev est lent, est-ce normal ?
Oui, le premier démarrage compile le frontend et peut prendre une à deux minutes. Les démarrages suivants utilisent le cache de webpack et tombent à vingt ou trente secondes. Si le démarrage dépasse cinq minutes, vérifier la RAM disponible — Backstage swappe massivement quand il est à l’étroit.

Faut-il vraiment installer Docker pour le développement local ?
Pour les tutoriels d’installation et de catalogue, non. Docker devient nécessaire dès qu’on touche à TechDocs (qui lance MkDocs dans un container par défaut) ou aux scaffolder actions qui dépendent d’images Docker. Autant l’installer dès le départ pour éviter une coupure plus tard.

Comment supprimer proprement le container PostgreSQL en fin de session ?
docker stop backstage-pg && docker rm backstage-pg arrête et supprime le container. Les données sont perdues si on n’a pas monté de volume — pour les conserver, démarrer le container avec -v backstage-pg-data:/var/lib/postgresql/data.

Mon poste a quatre gigaoctets de RAM, ça suffit ?
Techniquement oui, mais l’expérience est dégradée. Le démarrage de yarn dev consomme à lui seul un peu plus de deux gigaoctets, et il reste peu de marge pour le navigateur, l’IDE et le système. Si vous comptez utiliser Backstage sérieusement, viser huit gigaoctets minimum.

Quel IDE est recommandé pour modifier Backstage ?
VS Code avec les extensions ESLint, Prettier et TypeScript est le combo le plus utilisé. Backstage est en TypeScript strict et l’autocomplétion sur les types des plugins est précieuse pour comprendre les API exposées.

Comment mettre à jour Backstage vers une version plus récente ?
Backstage fournit l’utilitaire yarn backstage-cli versions:bump qui met à jour toutes les dépendances Backstage en une seule commande. À lancer en moyenne une fois par mois si on suit le rythme officiel des releases — sinon prévoir des montées de version trimestrielles, plus risquées mais moins fréquentes.