Guide d'Installation - Backstage

June 22, 2025 · View on GitHub

Ce guide vous accompagne dans l'installation et la configuration complète de cette implémentation Backstage.

Prérequis Système

Logiciels Requis

  • Node.js : Version 18 ou 20 (recommandé : 20 LTS)
  • Yarn : Gestionnaire de paquets (version 1.22+)
  • PostgreSQL : Version 12 ou supérieure
  • Git : Pour le contrôle de version

Vérification des Prérequis

# Vérifier Node.js
node --version  # Doit afficher v18.x.x ou v20.x.x

# Vérifier Yarn
yarn --version  # Doit afficher 1.22.x ou supérieur

# Vérifier PostgreSQL
psql --version  # Doit afficher 12.x ou supérieur

# Vérifier Git
git --version

Installation de PostgreSQL

Ubuntu/Debian

# Mettre à jour les paquets
sudo apt update

# Installer PostgreSQL
sudo apt install postgresql postgresql-contrib

# Démarrer le service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Se connecter en tant qu'utilisateur postgres
sudo -u postgres psql

# Créer la base de données et l'utilisateur
CREATE DATABASE backstage;
CREATE USER backstage WITH ENCRYPTED PASSWORD 'backstage';
GRANT ALL PRIVILEGES ON DATABASE backstage TO backstage;
\q

macOS (avec Homebrew)

# Installer PostgreSQL
brew install postgresql

# Démarrer le service
brew services start postgresql

# Créer la base de données et l'utilisateur
createdb backstage
createuser -P backstage  # Entrer le mot de passe 'backstage'

Windows

  1. Télécharger PostgreSQL depuis postgresql.org
  2. Installer avec l'option "Stack Builder" décochée
  3. Noter le mot de passe de l'utilisateur postgres
  4. Utiliser pgAdmin ou psql pour créer la base de données

Configuration GitHub

1. Créer un Personal Access Token

  1. Aller sur GitHub Settings > Developer settings > Personal access tokens
  2. Cliquer sur "Generate new token (classic)"
  3. Donner un nom descriptif (ex: "Backstage Integration")
  4. Sélectionner les scopes :
    • repo (accès complet aux dépôts privés)
    • read:org (lecture des organisations)
    • read:user (lecture du profil utilisateur)
  5. Copier le token généré

2. Créer une Application OAuth

  1. Aller sur GitHub Settings > Developer settings > OAuth Apps
  2. Cliquer sur "New OAuth App"
  3. Remplir les informations :
    • Application name : Backstage Dev
    • Homepage URL : http://localhost:3000
    • Authorization callback URL : http://localhost:7007/api/auth/github/handler/frame
  4. Noter le Client ID et Client Secret

Installation du Projet

1. Cloner le Repository

# Cloner le repository
git clone <repository-url>
cd projects-ruler

# Vérifier la structure
ls -la

2. Installer les Dépendances

# Installer les dépendances avec Yarn
yarn install

# Vérifier l'installation
yarn --version

3. Configuration des Variables d'Environnement

# Créer le fichier .env
cp .env.example .env  # Si un fichier example existe
# Ou créer manuellement
touch .env

Éditer le fichier .env avec vos valeurs :

# Configuration PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=backstage
POSTGRES_PASSWORD=backstage

# Configuration GitHub
GITHUB_TOKEN=ghp_your_personal_access_token_here
GITHUB_CLIENT=your_github_oauth_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_client_secret

# Secret Backend (générer une clé aléatoire)
BACKEND_SECRET=your_random_secret_key_here

4. Générer un Secret Backend

# Générer une clé aléatoire pour BACKEND_SECRET
openssl rand -hex 32
# Ou utiliser Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Démarrage de l'Application

1. Vérification Préalable

# Vérifier que PostgreSQL est démarré
sudo systemctl status postgresql  # Linux
brew services list | grep postgresql  # macOS

# Tester la connexion à la base de données
psql -h localhost -U backstage -d backstage -c "SELECT version();"

2. Premier Démarrage

# Démarrage en mode développement
yarn dev

# Ou avec dotenv-cli (recommandé)
npx dotenv -e .env -- yarn dev

3. Vérification du Démarrage

  1. Frontend : Ouvrir http://localhost:3000
  2. Backend : Vérifier http://localhost:7007/api/catalog/entities

4. Authentification

  1. Cliquer sur "Sign In" dans l'interface
  2. Choisir "GitHub" ou "Guest"
  3. Suivre le processus d'authentification

Configuration Avancée

1. Configuration Locale

Créer app-config.local.yaml pour les overrides :

app:
  title: Mon Backstage Local

backend:
  cors:
    origin: http://localhost:3000

catalog:
  providers:
    github:
      providerId:
        organization: 'votre-organisation'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

2. Configuration de Production

Éditer app-config.production.yaml :

app:
  title: Backstage Production
  baseUrl: https://votre-domaine.com

backend:
  baseUrl: https://votre-domaine.com
  cors:
    origin: https://votre-domaine.com
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      ssl: true

techdocs:
  builder: 'external'
  generator:
    runIn: 'docker'
  publisher:
    type: 'googleGcs'
    googleGcs:
      projectId: votre-projet-gcp
      bucketName: votre-bucket-techdocs

Tests et Validation

1. Tests Automatisés

# Tests unitaires
yarn test

# Tests avec couverture
yarn test:all

# Tests end-to-end
yarn test:e2e

2. Validation Manuelle

  1. Catalogue : Vérifier que les entités s'affichent
  2. Documentation : Tester la génération TechDocs
  3. Recherche : Vérifier la fonctionnalité de recherche
  4. Authentification : Tester les différents providers

Dépannage

Problèmes Courants

Erreur de Connexion PostgreSQL

# Vérifier le service
sudo systemctl status postgresql

# Vérifier la configuration
sudo -u postgres psql -c "SHOW listen_addresses;"

# Tester la connexion
psql -h localhost -U backstage -d backstage

Erreur d'Authentification GitHub

  1. Vérifier les variables d'environnement
  2. S'assurer que l'application OAuth est configurée
  3. Vérifier les scopes du Personal Access Token

Problèmes de Build

# Nettoyer le cache
yarn clean

# Réinstaller les dépendances
rm -rf node_modules yarn.lock
yarn install

# Vérifier les versions Node.js
node --version
yarn --version

Logs et Debug

# Logs du backend
yarn start-backend

# Logs du frontend
yarn start

# Mode debug
DEBUG=* yarn dev

Prochaines Étapes

  1. Personnalisation : Adapter l'interface et les fonctionnalités
  2. Plugins : Développer des plugins personnalisés
  3. Intégrations : Ajouter d'autres outils (Jira, Slack, etc.)
  4. Déploiement : Configurer pour la production
  5. Monitoring : Ajouter des métriques et alertes

Support