Aller au contenu

Intégration Backstage (pour le DevOps)

Comment ajouter le projet Bank Transaction (sa documentation et son API) dans le portail Backstage déployé sur un autre serveur.

Tout est déjà préparé côté dépôt : le fichier catalog-info.yaml (à la racine) décrit le composant, sa doc (TechDocs) et son API (OpenAPI). Le DevOps n'a qu'à enregistrer le dépôt et s'assurer que TechDocs est activé.

1. Pré-requis côté Backstage (à vérifier une fois)

  1. Intégration GitHub configurée dans app-config.yaml (le dépôt est privé, dans l'organisation Boaz-study-organization) : 
    1
2
3
4
    integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}   # jeton avec acces en lecture au repo
  2. TechDocs activé avec un générateur capable de construire des docs MkDocs. Recommandé : 
    1
2
3
4
5
6
    techdocs:
  builder: 'local'            # Backstage construit la doc lui-meme
  generator:
    runIn: 'docker'           # utilise l'image de generation (mkdocs + techdocs-core)
  publisher:
    type: 'local'             # ou 'awsS3' / 'googleGcs' selon votre infra

    La doc utilise le plugin techdocs-core (déjà déclaré dans mkdocs.yml), donc elle est directement compatible avec le générateur TechDocs.

  3. Plugins API Docs présents (inclus par défaut dans Backstage) pour afficher l'OpenAPI.
  4. Addon Mermaid pour TechDocs (IMPORTANT si la doc contient des diagrammes) — sans lui, les diagrammes Mermaid s'affichent en texte/code au lieu d'être dessinés (le build ne plante pas, c'est juste le rendu). À installer une fois dans le lecteur TechDocs : 
    1
2
    # dans le package de l'app frontend Backstage
yarn --cwd packages/app add backstage-plugin-techdocs-addon-mermaid

    1
2
3
4
5
6
7
8
9
    // packages/app/src/App.tsx — brancher l'addon dans le lecteur TechDocs
import { TechDocsAddons } from '@backstage/plugin-techdocs-react';
import { Mermaid } from 'backstage-plugin-techdocs-addon-mermaid';

<EntityTechdocsContent>
  <TechDocsAddons>
    <Mermaid config={{ theme: 'neutral' }} />
  </TechDocsAddons>
</EntityTechdocsContent>

    La doc utilise déjà le fence mermaid standard (```mermaid), donc aucune modification du dépôt n'est nécessaire : il suffit d'activer cet addon côté Backstage.

2. Enregistrer le projet (opération principale)

Dans Backstage :

  1. Menu Create… (ou Catalog) → Register Existing Component.
  2. Coller l'URL du fichier catalog-info.yaml du dépôt : 
    1
    https://github.com/Boaz-study-organization/Boaz-study-fullstack-bank-transaction/blob/main/catalog-info.yaml
  3. Analyze → Import.

Backstage crée alors 2 entités : - Component bank-transaction - API bank-transaction-api

3. Résultat attendu (vérifications)

Sur la page du composant bank-transaction :

  • ✅ Onglet Docs : la documentation MkDocs s'affiche (générée depuis mkdocs.yml).
  • ✅ Onglet API : l'API bank-transaction-api est listée. En l'ouvrant, la spécification OpenAPI du backend FastAPI s'affiche (Swagger interactif). Elle est récupérée automatiquement depuis : https://api-transaction.boaz-study.tech/openapi.json

4. Ce qui est déjà en place dans le dépôt (pour info)

Élément Rôle
catalog-info.yaml décrit le composant + l'API + le lien vers la doc
backstage.io/techdocs-ref: dir:. indique à Backstage où générer la doc
mkdocs.yml (plugin techdocs-core) rend la doc compatible TechDocs
entité kind: API (type openapi) pointe vers l'OpenAPI du backend

5. Problèmes courants

Problème Cause Solution
L'onglet Docs affiche une erreur de build générateur TechDocs absent/mal configuré vérifier techdocs.generator.runIn: docker et l'accès à l'image de génération
« Not found » sur le dépôt jeton GitHub sans accès au repo privé fournir un jeton ayant accès à Boaz-study-organization
L'API ne se charge pas Backstage ne peut pas joindre l'OpenAPI vérifier que https://api-transaction.boaz-study.tech/openapi.json répond (200)
La doc ne se met pas à jour cache TechDocs relancer la génération / vider le cache TechDocs
Les diagrammes apparaissent en code (pas dessinés) addon Mermaid absent installer l'addon Mermaid (voir §1, point 4)

Mise à jour automatique : à chaque déploiement (push sur main), la doc et l'API évoluent avec le projet. Backstage régénère la doc selon sa configuration (à la demande ou périodiquement).