FAQ technique¶

Cette FAQ regroupe les questions fréquentes que les professeurs et les étudiants nous posent sur PerfShop. Les réponses sont volontairement concises et renvoient vers les pages de référence pour le détail.

Licence¶

Comment activer une licence PerfShop ?¶

Deux voies possibles :

Via .env — ajoutez PERFSHOP_LICENSE_KEY=PFSH-xxx.yyy dans votre fichier .env puis redémarrez la stack avec docker compose restart perfshop-app. La licence est chargée au démarrage par LicenseService.
Via l'interface — ouvrez le panneau chaos-admin (page gestion.html accessible au superadmin), collez la clé dans le champ dédié du panneau licence, et cliquez sur Activer.

Voir Système de licence.

Pourquoi l'activation de licence est-elle publique ?¶

Les endpoints POST /api/license/activate et POST /api/license/revoke sont intentionnellement accessibles sans authentification. Sans cela, nous aurions un deadlock : sans licence active, tous les endpoints admin renvoient 402, donc impossible de se connecter pour activer la licence.

La sécurité est assurée par la vérification cryptographique RSA-PSS 2048 de la clé — un attaquant ne peut pas forger de licence valide sans accès à la clé privée qui reste sur perfshop.io.

Que se passe-t-il quand ma licence expire ?¶

La vérification est instantanée à chaque requête. À partir du lendemain de la date d'expiration (expiresAt), tous les appels aux endpoints protégés renvoient HTTP 402 Payment Required. Le shop, la page étudiant et le monitoring HTML restent accessibles. Les dashboards Grafana historiques restent consultables.

Pour prolonger, activez une nouvelle clé via POST /api/license/activate — aucun redémarrage nécessaire.

Puis-je utiliser PerfShop gratuitement ?¶

Oui, partiellement. Le shop, la page étudiant, le monitoring dashboard et le parcours pédagogique BAC1/BAC2 sont accessibles sans licence. Le Chaos Performance freemium (niveau 1) et le Chaos Scripting niveau 1 (Junior) le sont aussi. Voir Freemium vs Pro pour la frontière précise.

Vous pouvez également récupérer le code source et l'exécuter localement sous AGPL-3.0-or-later — mais cette licence open source impose de publier vos propres modifications si vous exposez une instance modifiée en production. Voir Licence.

Parcours pédagogique¶

Comment réinitialiser un parcours pédagogique en cours ?¶

Depuis le panneau formateur (chaos-admin/public/admin/), onglet Pédagogique, cliquez sur le bouton Reset global. Cela appelle POST /api/chaos/pedagogique/reset qui vide toutes les sessions actives et remet current_step = 0 pour tous les étudiants.

Pour ne réinitialiser qu'un seul étudiant, demandez-lui de vider son localStorage.ped_student_token — au prochain poll, le backend créera une nouvelle session via /join.

Comment activer ou désactiver les indices pendant un parcours ?¶

Le formateur peut à tout moment basculer les indices via POST /pedagogique/hints { enabled: true|false } depuis le panneau Pédagogique. L'état est propagé aux étudiants au prochain poll (/status toutes les 15 secondes), et le bouton « Indice » de l'overlay pédagogique apparaît ou disparaît en conséquence.

Le flag est stocké dans un volatile boolean pedagogiqueHintsEnabled côté backend — voir Indices et progression.

Que faire si un étudiant reste bloqué sur une énigme ?¶

Trois leviers :

Activer les indices — si ce n'est pas déjà fait (voir ci-dessus)
Consulter la note culturelle — affichée après validation, mais le prof peut la lire depuis les fichiers i18n/enigmes/bacN/enigmes_fr.json
Reset ciblé — demander à l'étudiant de rafraîchir son token pour repartir au début

Voir Internationalisation des énigmes pour le format des fichiers.

Que se passe-t-il si je dépasse 500 sessions pédagogiques simultanées ?¶

Le backend n'impose pas de limite dure. La table pedagogique_sessions n'a pas de contrainte de volume et le cache mémoire optionnel est dimensionné pour absorber plusieurs milliers de sessions. Les polls /status (15 secondes d'intervalle) génèrent une charge raisonnable même à grande échelle.

À titre indicatif, une instance Docker Desktop moyenne supporte sans broncher ~200 sessions simultanées. Au-delà, surveillez l'heap JVM du backend via Grafana ou le dashboard monitoring HTML, et ajustez -Xmx si nécessaire.

Administration¶

Comment ajouter un compte admin ?¶

Connectez-vous en superadmin sur chaos-admin, naviguez vers Gestion → Créer un compte, saisissez l'email, le mot de passe (min 6 caractères) et cochez les droits souhaités (chaos-admin, monitoring, backoffice, jmeter, scripts), puis cliquez sur Créer.

Seul le superadmin voit ce formulaire. Voir Authentification admin.

Comment réinitialiser le mot de passe admin ?¶

Deux options :

Via .env — modifiez ADMIN_PASSWORD=nouveau-mdp puis redémarrez perfshop-app. Le bootstrap détecte que le hash stocké ne correspond plus et met à jour la base automatiquement.
Via la page Mon compte — connectez-vous avec l'ancien mot de passe, ouvrez la page mon-compte.html, saisissez deux fois le nouveau mot de passe, validez.

Comment changer la langue de la stack ?¶

Modifiez PERFSHOP_LANG=fr|en dans votre .env puis redémarrez l'ensemble :

docker compose down
docker compose up -d

La variable est propagée à tous les services (backend, frontend, chaos-admin, monitoring, welcome, scripts-ui, jmeter-ui). Voir Vue d'ensemble i18n.

Chaos engineering¶

Comment voir les logs d'un chaos en cours ?¶

Plusieurs voies complémentaires :

Grafana → Explore → Loki — filtrez par container="perfshop-app" et cherchez le préfixe de la famille chaos ([chaos.business], [chaos.security]…)
Dashboard Grafana « Chaos Dashboard » — tableaux temps réel par famille, provisionnés par défaut
Monitoring HTML — compteurs simplifiés en temps réel (voir Monitoring étudiant)
Panneau chaos-admin — compteurs par famille (biz-counters-label, sec-hits-label, fn-counters-label) affichés en haut de chaque section

Voir Observabilité.

Comment savoir quel chaos est actuellement actif ?¶

Appelez GET /api/chaos/student/status (pas d'authentification requise) — la réponse contient un objet par famille avec le niveau actif :

{
  "performance": { "active": "N2-03", "level": 2 },
  "scripting":   { "level": 1, "maxLevel": 4 },
  "business":    { "level": 0, "maxLevel": 4 },
  "functional":  { "level": 0, "maxLevel": 4 },
  "security":    { "level": 0, "maxLevel": 4 },
  "pedagogique": { "level": "bac1", "active": true }
}

Le panneau chaos-admin consomme ce endpoint toutes les 5 secondes et affiche l'état à l'écran.

Pourquoi le code 402 apparaît-il sur certains chaos ?¶

Le code HTTP 402 Payment Required est retourné par LicenseInterceptor quand vous essayez d'accéder à un chaos ou à une interface qui nécessite une licence active que votre instance n'a pas. Le header X-License-Required: true confirme qu'il s'agit bien d'un blocage licence et non d'une autre erreur.

Voir Freemium vs Pro pour la liste des chaos et interfaces concernés.

Puis-je activer plusieurs chaos performance en même temps ?¶

Non. La règle d'or du Chaos Performance côté étudiant est « un seul scénario actif à la fois ». Activer un nouveau scénario désactive automatiquement le précédent — c'est géré par PerformanceScenario.resetAll() côté backend.

Les 20 scénarios météo N1-01 à N4-05 combinent déjà plusieurs chaos backend dans un seul preset (par exemple CPU + thread pool + slow queries), donc vous pouvez obtenir des configurations complexes sans cumuler manuellement. Voir Scénarios météo.

Côté panneau formateur, un bouton Reset tout remet toutes les familles à zéro en une seule opération.

Déploiement¶

Comment relancer la stack après un redémarrage du NAS ?¶

Si votre Docker a le redémarrage automatique activé (restart: unless-stopped dans le compose — c'est le cas par défaut), la stack redémarre toute seule avec le NAS. Sinon :

cd /chemin/vers/perfshop
docker compose up -d

Les volumes persistants (base MySQL, Grafana, Loki, Tempo, Pyroscope, OpenSearch, Squash, Forgejo) sont conservés entre redémarrages. Voir Lancer Docker Compose.

Mon port 9080 est déjà utilisé, comment changer le port du backend ?¶

Modifiez BACKEND_HTTP_PORT=9090 dans .env (ou tout autre port libre) et redémarrez perfshop-app. Pensez à mettre à jour aussi PUBLIC_API_URL=http://localhost:9090 pour que le frontend pointe sur le nouveau port.

Voir la référence des variables d'environnement pour la liste complète des ports configurables.

Comment exposer PerfShop sur un domaine avec HTTPS ?¶

Utilisez le mode dns de la welcome page et un reverse-proxy HTTPS (Nginx, Caddy, Traefik) devant la stack :

Passez WELCOME_MODE=dns dans .env
Renseignez toutes les PUBLIC_*_URL avec vos vrais sous-domaines HTTPS
Configurez votre reverse-proxy pour router chaque sous-domaine vers le port interne correspondant
Passez SESSION_COOKIE_SECURE=true pour sécuriser les cookies
Changez les mots de passe par défaut (ADMIN_PASSWORD, DB_PASSWORD, GF_SECURITY_ADMIN_PASSWORD, OPENSEARCH_ADMIN_PASSWORD…)

Voir Topologie de déploiement.

PerfShop collecte-t-il des données d'usage ?¶

Non. PerfShop ne fait aucun appel sortant vers perfshop.io ni vers aucun serveur tiers au démarrage ou en fonctionnement. L'instance que vous déployez est totalement autonome : aucune version, aucun hostname, aucune IP, aucun UUID d'instance n'est envoyé à l'extérieur. La seule communication réseau sortante provient de vos propres actions (ouvrir la documentation officielle dans votre navigateur, activer une licence via copier-coller).

Voir la licence pour le détail de l'engagement vie privée.

Développement¶

Puis-je contribuer à PerfShop ?¶

Oui, sous licence AGPL-3.0-or-later. Forkez le dépôt Forgejo, créez une branche feature/..., committez vos changements, poussez et ouvrez une Pull Request. Voir Workflow Git Forgejo.

Les contributions doivent respecter le niveau de qualité « production commerciale » : pas de pseudo-code, pas de TODO, tests à jour, symétrie FR/EN maintenue, documentation synchronisée.

Mon build Maven échoue — que vérifier ?¶

Les causes fréquentes :

Java 21 non disponible — java -version doit afficher 21.x
Maven trop ancien — Maven 3.9+ est requis
Connexion Internet — Maven doit télécharger les dépendances au premier build
Tests qui échouent — utilisez mvn package -DskipTests en dev pour isoler le problème

Voir Prérequis et Build backend.

Mon build Vite affiche des warnings CORS — que faire ?¶

En mode npm run dev, le dev server Vite tourne sur le port 5173 et le backend sur 8080 (ou 9080 en conteneur). Ces deux origines sont différentes pour le navigateur, donc CORS s'applique.

Deux options :

Ajouter http://localhost:5173 à CORS_ALLOWED_ORIGINS côté backend, puis redémarrer le backend
Configurer un proxy Vite dans vite.config.js qui route /api/* vers http://localhost:8080

Voir Build frontend.

Données et base¶

Comment importer des données de test supplémentaires ?¶

Ajoutez un fichier V11__mes_donnees_test.sql dans backend/src/main/resources/db/migration-fr/ et redémarrez le backend. Flyway détectera la nouvelle migration et l'exécutera automatiquement.

Attention — ne modifiez jamais les migrations V1 à V10 existantes. Flyway rejette les migrations altérées après application et refuse de démarrer. Voir Schéma de la base de données.

Comment repartir d'une base vide ?¶

docker compose down -v
docker compose up -d

L'option -v supprime les volumes Docker, y compris mysql-data. Au prochain démarrage, Flyway rejoue toutes les migrations V1-V10 sur la base vide et AdminUserService recrée le superadmin. Toutes les commandes, sessions pédagogiques et activations de licence passées sont perdues.

Comment consulter directement la base MySQL ?¶

docker exec -it perfshop-db mysql -u perfshop -p perfshop

Saisissez le DB_PASSWORD de votre .env. Vous arrivez dans un shell MySQL où vous pouvez exécuter des requêtes SELECT sur toutes les tables.

Pour les requêtes de lecture courantes (stats, debug), vous pouvez aussi passer par Grafana → Explore en pointant sur le datasource MySQL préconfiguré.

Observabilité¶

Grafana affiche « No data » sur certains panneaux — que vérifier ?¶

Dans l'ordre :

Prometheus est-il up ? — ouvrez http://localhost:9092/targets et vérifiez que toutes les cibles sont UP
Le backend expose-t-il /actuator/prometheus ? — testez avec curl http://localhost:9080/actuator/prometheus | head
La plage de temps Grafana inclut-elle le présent ? — le sélecteur en haut à droite doit être sur « Last 15 minutes » ou équivalent
Le datasource Grafana est-il bien configuré ? — dans Grafana, Connections → Data sources, testez la connexion au datasource Prometheus

Voir Prometheus et Grafana.

Comment récupérer un heap dump du backend ?¶

Trois voies :

Dashboard monitoring — ouvrez http://localhost:3001, section widget heap dump, cliquez sur Télécharger. Le dump peut prendre jusqu'à 60 secondes.
API directe — curl http://localhost:3001/api/heapdump -o heapdump.hprof
Depuis le conteneur — docker exec perfshop-app sh -c 'curl http://localhost:9090/actuator/heapdump' > heapdump.hprof

Le port management 9090 n'est pas exposé publiquement ; seul le monitoring proxy y accède via le réseau Docker interne.

Analysez le fichier .hprof avec Eclipse Memory Analyzer (MAT) ou VisualVM.

Cette FAQ sera enrichie au fil des questions récurrentes. Si votre question n'y figure pas, contactez contact@perfshop.io ou ouvrez une issue sur Forgejo.