Documentation de l'Implémentation Backstage

June 22, 2025 · View on GitHub

Vue d'ensemble

Cette implémentation de Backstage est une plateforme de portail développeur moderne basée sur le framework open-source de Spotify. Elle fournit un hub centralisé pour la gestion des services, la documentation technique, et l'automatisation des processus de développement.

Architecture

Structure du Projet

Le projet suit une architecture monorepo organisée avec les packages suivants :

projects-ruler/
├── packages/
│   ├── app/          # Application frontend React
│   └── backend/      # Serveur backend Node.js
├── plugins/          # Plugins personnalisés (à développer)
├── docs/            # Documentation du projet
├── examples/        # Exemples d'entités et templates
└── config/          # Fichiers de configuration

Technologies Utilisées

  • Frontend : React 18, TypeScript, Material-UI
  • Backend : Node.js 18/20, Express
  • Base de données : PostgreSQL
  • Authentification : GitHub OAuth + Guest Provider
  • Tests : Playwright (e2e), Jest
  • Build : Backstage CLI, Lerna

Fonctionnalités Principales

1. Catalogue de Services (Software Catalog)

Le catalogue centralise toutes les informations sur les services, APIs et ressources :

  • Composants : Services, applications, bibliothèques
  • APIs : Documentation et métadonnées des APIs
  • Systèmes : Groupement logique de composants
  • Ressources : Infrastructure et dépendances

Exemple d'entité :

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: example-website
spec:
  type: website
  lifecycle: experimental
  owner: guests
  system: examples

2. Documentation Technique (TechDocs)

  • Génération automatique de documentation depuis les dépôts Git
  • Support Markdown avec extensions
  • Navigation et recherche intégrées
  • Publication locale ou cloud (GCS, S3)

3. Templates de Software (Scaffolder)

  • Création automatisée de nouveaux projets
  • Templates personnalisables
  • Intégration avec les outils de développement
  • Workflows d'approbation

4. Recherche Globale

  • Recherche unifiée dans le catalogue, la documentation et les APIs
  • Filtres avancés
  • Historique des recherches

5. Authentification et Autorisations

  • GitHub OAuth : Authentification via GitHub
  • Guest Provider : Accès anonyme pour le développement
  • Permissions : Contrôle d'accès granulaire
  • Résolution d'utilisateurs : Mapping GitHub → Backstage

6. Intégrations

  • GitHub : Synchronisation automatique des dépôts
  • GitHub Actions : Visualisation des workflows CI/CD
  • GitHub Insights : Métriques et analytics

Configuration

Variables d'Environnement

Créer un fichier .env à la racine du projet :

# Base de données PostgreSQL
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USER=backstage
POSTGRES_PASSWORD=backstage

# GitHub Integration
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_CLIENT=your_github_oauth_app_client_id
GITHUB_CLIENT_SECRET=your_github_oauth_app_client_secret

# Backend Secret (pour la production)
BACKEND_SECRET=your_backend_secret_key

Configuration de l'Application

Le fichier app-config.yaml contient la configuration principale :

  • Base URL : http://localhost:3000 (frontend), http://localhost:7007 (backend)
  • CORS : Configuration pour le développement local
  • Database : Configuration PostgreSQL
  • Auth : Providers d'authentification
  • Catalog : Sources d'entités et règles d'accès

Configuration GitHub

L'intégration GitHub est configurée pour :

  • Synchroniser automatiquement les dépôts de l'organisation fpouyez
  • Scanner les fichiers catalog-info.yaml dans la branche main
  • Mise à jour toutes les 30 minutes

Installation et Démarrage

Prérequis

  • Node.js 18 ou 20
  • PostgreSQL
  • Compte GitHub avec Personal Access Token
  • Application OAuth GitHub configurée

Installation

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

# Installer les dépendances
yarn install

# Configurer la base de données PostgreSQL
# Voir docs/Installing database.md

# Configurer les variables d'environnement
cp .env.example .env
# Éditer .env avec vos valeurs

Démarrage

# Démarrage en mode développement
yarn dev

# Avec dotenv-cli (recommandé)
dotenv -e .env -- yarn dev

# Démarrage séparé
yarn start        # Frontend uniquement
yarn start-backend # Backend uniquement

L'application sera accessible sur :

Développement

Structure des Composants

Frontend (packages/app/src/)

  • App.tsx : Configuration principale de l'application
  • components/ : Composants personnalisés
    • catalog/ : Pages du catalogue
    • home/ : Page d'accueil
    • search/ : Interface de recherche
    • Root/ : Layout principal

Backend (packages/backend/src/)

  • index.ts : Point d'entrée et configuration des plugins
  • Plugins activés :
    • App Backend
    • Proxy Backend
    • Scaffolder Backend
    • TechDocs Backend
    • Auth Backend (GitHub + Guest)
    • Catalog Backend (GitHub)
    • Permission Backend
    • Search Backend

Tests

# Tests unitaires
yarn test

# Tests avec couverture
yarn test:all

# Tests end-to-end (Playwright)
yarn test:e2e

# Linting
yarn lint

# Formatage
yarn prettier:check

Build et Déploiement

# Build complet
yarn build:all

# Build du backend
yarn build:backend

# Image Docker
yarn build-image

Plugins Intégrés

Plugins Core

  • @backstage/plugin-catalog : Gestion du catalogue
  • @backstage/plugin-techdocs : Documentation technique
  • @backstage/plugin-scaffolder : Templates de création
  • @backstage/plugin-search : Recherche globale
  • @backstage/plugin-api-docs : Documentation des APIs
  • @backstage/plugin-org : Gestion des organisations
  • @backstage/plugin-user-settings : Paramètres utilisateur

Plugins Communautaires

  • @backstage-community/plugin-github-actions : Intégration GitHub Actions
  • @roadiehq/backstage-plugin-github-insights : Métriques GitHub

Bonnes Pratiques

Développement

  1. TypeScript : Utiliser le typage strict
  2. Tests : Écrire des tests pour les nouvelles fonctionnalités
  3. Documentation : Maintenir la documentation à jour
  4. Linting : Respecter les règles ESLint et Prettier

Configuration

  1. Variables d'environnement : Ne jamais commiter de secrets
  2. Configuration locale : Utiliser app-config.local.yaml pour les overrides
  3. Base de données : Utiliser PostgreSQL en production

Sécurité

  1. Authentification : Configurer les providers appropriés
  2. Permissions : Définir des règles d'accès granulaires
  3. CORS : Configurer correctement pour la production
  4. Secrets : Utiliser un gestionnaire de secrets en production

Troubleshooting

Problèmes Courants

  1. Erreur de connexion à la base de données

    • Vérifier les variables d'environnement PostgreSQL
    • S'assurer que PostgreSQL est démarré

  2. Erreur d'authentification GitHub

    • Vérifier le Personal Access Token
    • Configurer l'application OAuth GitHub

  3. Problèmes de build

    • Nettoyer le cache : yarn clean
    • Vérifier les versions Node.js

Logs

  • Frontend : Console du navigateur
  • Backend : Logs dans le terminal de démarrage
  • Base de données : Logs PostgreSQL

Ressources

Support

Pour toute question ou problème :

  1. Consulter la documentation officielle Backstage
  2. Vérifier les logs d'erreur
  3. Consulter les issues GitHub du projet
  4. Contacter l'équipe de développement