Aller au contenu

PerfShop — Documentation technique

PerfShop est une plateforme pédagogique de chaos engineering qui matérialise, sur une application e-commerce réaliste, tous les types d'anomalies qu'un professionnel du test et de la performance rencontre dans sa carrière. Cette documentation est la bible technique de référence pour comprendre l'architecture, les APIs, les chaos disponibles, les métriques et l'écosystème complet.

Cette documentation n'est pas un manuel de TP. Les travaux pratiques sont vendus séparément avec la licence commerciale et hébergés sur un portail dédié. Cette référence couvre la plateforme elle-même : son code, ses composants, ses interfaces, ses choix de conception.

Elle s'adresse aux professeurs qui animent des formations, aux étudiants qui veulent comprendre ce qui se passe sous le capot, aux développeurs curieux qui explorent un écosystème d'observabilité moderne, et aux équipes QA qui cherchent un terrain d'entraînement partagé. Voir Pour qui pour le détail des publics cibles.

L'écosystème en un diagramme

flowchart TB
  subgraph Users[Utilisateurs]
    Prof[👨‍🏫 Formateur]
    Student[🎓 Étudiants]
    Dev[👨‍💻 Développeurs]
  end

  subgraph Entry[Point d'entrée]
    Welcome[🏠 Welcome page<br/>liste des services]
  end

  subgraph Apps[Applications]
    Shop[🛒 Shop React<br/>frontend e-commerce]
    ChaosAdmin[⚡ chaos-admin<br/>panneau formateur + page étudiant]
    MonitoringHTML[📊 Monitoring HTML<br/>dashboard temps réel]
    ScriptsUI[📜 Scripts UI]
    JMeterUI[⚡ JMeter UI]
    Docs[📚 MkDocs<br/>cette documentation]
  end

  subgraph Backend[Backend]
    SpringBoot[☕ Spring Boot 3.2<br/>+ Java 21]
    MySQL[(🗄️ MySQL 8)]
  end

  subgraph Obs[Observabilité]
    Prometheus[Prometheus]
    Grafana[Grafana]
    Loki[Loki]
    Tempo[Tempo]
    Pyroscope[Pyroscope]
    OpenSearch[OpenSearch]
  end

  subgraph QA[Stack QA]
    SquashTM[Squash TM]
    Selenium[Selenium Grid]
    TestRunner[Test Runner<br/>Robot + pytest]
    Forgejo[Forgejo Git]
  end

  Users --> Welcome
  Welcome --> Shop
  Welcome --> ChaosAdmin
  Welcome --> MonitoringHTML
  Welcome --> Docs

  Shop --> SpringBoot
  ChaosAdmin --> SpringBoot
  MonitoringHTML --> SpringBoot
  ScriptsUI --> SpringBoot
  JMeterUI --> SpringBoot

  SpringBoot --> MySQL
  SpringBoot -.métriques.-> Prometheus
  SpringBoot -.logs.-> Loki
  SpringBoot -.traces.-> Tempo
  SpringBoot -.profils.-> Pyroscope
  SpringBoot -.logs.-> OpenSearch

  Prometheus --> Grafana
  Loki --> Grafana
  Tempo --> Grafana
  Pyroscope --> Grafana

  QA --> SpringBoot

PerfShop est un écosystème complet : backend Spring Boot 3.2 + Java 21, frontend React 18 + Vite, base MySQL 8, observabilité Prometheus/Grafana/Loki/Tempo/Pyroscope/OpenSearch, stack QA Selenium/Squash TM/JMeter/test-runner polyglotte, Git auto-hébergé Forgejo. Un seul docker compose up démarre l'intégralité.

Les treize sections de cette documentation

🏁 Présentation

Le « pourquoi » de PerfShop. Cette section explique la philosophie pédagogique, les publics cibles, les conditions de licence, et fournit un glossaire complet du vocabulaire utilisé dans le reste de la documentation.

🏗️ Architecture

Le « comment » technique. Vue d'ensemble du système, stack technique, topologie de déploiement, schéma de données, flux d'authentification, gestion multi-session pédagogique, composition Docker, réseau et domaines.

👁️ Observabilité

La colonne vertébrale de diagnostic de PerfShop. Métriques Prometheus, dashboards Grafana, logs Loki et Promtail, traces Tempo, profils Pyroscope, logs alternatifs OpenSearch, et dashboard HTML simplifié.

🧪 Stack QA

Outils de gestion et d'exécution de tests intégrés à la plateforme : Squash TM pour la gestion de cas de test, Squash Orchestrator pour les exécutions automatisées, Selenium Grid, un test runner polyglotte Robot Framework + pytest, JMeter et son lanceur web, Scripts UI pour l'édition en ligne, Forgejo comme serveur Git auto-hébergé.

⚡ Chaos Engineering

Le cœur pédagogique de PerfShop. Sept familles de chaos activables à la demande : Performance backend, 20 scénarios météo pré-câblés, Chaos Fonctionnel (exceptions Java), Chaos Métier (16 anomalies silencieuses), Chaos Sécurité (12 failles OWASP), Chaos Scripting (tokens rotatifs HMAC), Chaos Frontend (CPU burn, memory leak, DOM flood), et référence exhaustive des métriques Prometheus exposées.

🎓 Parcours pédagogique

Le sous-système escape room de PerfShop. Concept et architecture, cinq niveaux BAC1 à BAC5, système d'énigmes, code agent dynamique, système d'étoiles, indices et progression, page de succès standalone, thèmes finaux.

🔌 Référence API

Documentation exhaustive des endpoints REST exposés par le backend Spring Boot : catalogue, panier, commandes, profil utilisateur, référentiel pays, administration, portail admin vulnérable, chaos-admin, chaos étudiant, pédagogique étudiant, licence.

🖥️ Interfaces

Description détaillée de chaque interface utilisateur : frontend e-commerce React, page chaos étudiant (6 onglets), monitoring étudiant HTML, panneau chaos-admin formateur, portail admin vulnérable (surface S10-S12), page d'accueil welcome.

🔒 Sécurité et licence

Les mécanismes de protection et de contrôle d'accès : système de licence RSA-PSS 2048 avec intégrité par hash, authentification admin (sessions + X-Admin-Token), règles freemium et niveaux Master.

🛠️ Développement local

Comment récupérer le code, lancer la stack, itérer sur le backend ou le frontend, et contribuer via Forgejo.

🌍 Internationalisation

Stratégie globale FR/EN (et cinq langues cibles), dictionnaires backend, frontend, énigmes pédagogiques, outils annexes. Une seule variable d'environnement — PERFSHOP_LANG — propagée à toute la stack.

📖 Guides

Guides pratiques orientés cas d'usage : démarrage rapide, guide étudiant, création de scripts JMeter custom, scénarios hackathon et formation, configuration Squash TM et Squash Orchestrator, guides Robot Framework, Forgejo, Scripts UI, et activation de licence.

📎 Annexes

Références exhaustives utiles à tout moment : variables d'environnement, schéma complet de la base de données, et foire aux questions techniques.

Licence

PerfShop est publié sous double licence :

  • AGPL-3.0-or-later pour l'usage open source — utilisation, modification, redistribution libres sous réserve de publier les modifications si l'instance est exposée en réseau
  • Licence commerciale pour les usages qui ne peuvent pas satisfaire les obligations de l'AGPL — formation vendue à des tiers, intégration dans un produit propriétaire, accès à la bibliothèque de TP clés en main

Voir Licence (résumé) et Système de licence (technique) pour le détail.

Contact