Prérequis¶

Cette page liste les outils nécessaires pour déployer et développer PerfShop localement. Deux scénarios sont couverts : déploiement Docker Compose (le mode recommandé) et développement natif (pour itérer sur le backend Spring Boot ou le frontend React sans conteneur).

Déploiement Docker Compose¶

C'est le scénario principal. Tous les composants de PerfShop (backend, frontend, base de données, observabilité, stack QA) sont conteneurisés et orchestrés par Docker Compose. Un seul binaire à installer pour faire tourner l'ensemble.

Système d'exploitation¶

OS	Support	Notes
Windows 10/11	✅ Via Docker Desktop + WSL2	Nécessite un backend WSL2 activé dans Docker Desktop
macOS 12+	✅ Via Docker Desktop	Performances correctes sur Apple Silicon
Ubuntu 22.04+	✅ Docker Engine natif	Le plus performant
Debian 12+	✅ Docker Engine natif	Idem Ubuntu
Synology DSM 7+	✅ Container Manager	Usage production NAS — voir topologie de déploiement

Docker¶

Docker Engine 24+ ou Docker Desktop 4.30+
Docker Compose v2 (docker compose et non docker-compose legacy)

Vérification :

docker --version
# Docker version 26.x ou plus

docker compose version
# Docker Compose version v2.x ou plus

Ressources minimales recommandées¶

La stack complète PerfShop (core + observabilité + QA) consomme environ 6 à 8 Go de RAM et sollicite modérément le CPU. Pour un déploiement confortable :

Ressource	Minimum	Confortable
CPU	4 cœurs	8 cœurs
RAM	8 Go	16 Go
Disque	20 Go libre	50 Go libre

Sur Docker Desktop Windows/macOS, ces limites se configurent dans Settings → Resources. Le backend est particulièrement sensible à la RAM allouée à la JVM pour les démonstrations de chaos mémoire et OOM.

Développement natif backend¶

Si vous voulez modifier le code Java et itérer rapidement sans reconstruire d'image Docker à chaque fois.

Java¶

Java 21 LTS (OpenJDK, Temurin, Zulu, Amazon Corretto — au choix).

java -version
# openjdk version "21.x.x"

Spring Boot 3.2 exige Java 17 minimum ; PerfShop utilise les fonctionnalités modernes du langage (pattern matching, records, switch expressions) qui sont stables en Java 21.

Maven¶

Maven 3.9+.

mvn --version
# Apache Maven 3.9.x ou plus

Le projet utilise le plugin spring-boot-maven-plugin pour packager un JAR exécutable autonome.

MySQL (optionnel)¶

En développement natif, deux options :

Conteneur MySQL — démarrer uniquement perfshop-db via docker compose up -d perfshop-db et lancer le backend localement en pointant sur localhost:19306
MySQL 8 natif — installer MySQL 8 et créer une base perfshop à la main avec les credentials du .env

La première option est plus simple et évite d'avoir à gérer l'installation MySQL.

Développement natif frontend¶

Pour itérer sur l'interface React avec hot reload Vite.

Node.js¶

Node 20 LTS ou plus récent.

node --version
# v20.x ou plus

npm --version
# 10.x ou plus

Vite 5 requiert Node 18 minimum ; Node 20 est recommandé pour bénéficier du fetch natif et des performances améliorées.

Gestionnaire de paquets¶

npm (fourni avec Node) suffit. Les package-lock.json sont committés pour garantir la reproductibilité des installations.

Git¶

Git 2.30+ pour cloner le dépôt et gérer les branches.

git --version
# git version 2.30.x ou plus

Navigateur moderne¶

Pour accéder aux interfaces PerfShop, un navigateur récent :

Chrome / Edge / Chromium 120+
Firefox 115+
Safari 16+ (macOS)

Les interfaces chaos-admin et monitoring utilisent des fonctionnalités JavaScript modernes (ES2020+, optional chaining, nullish coalescing) qui ne sont pas polyfillées.

Ports requis sur l'hôte¶

La stack PerfShop expose de nombreux services sur l'hôte. Voici les ports utilisés en configuration par défaut :

Port	Service
`3001`	Monitoring HTML
`3002`	Grafana
`3003`	chaos-admin (page étudiant + panneau formateur)
`3004`	Backoffice admin
`3005`	JMeter UI
`3007`	Filebrowser
`3008`	Scripts UI
`3009`	Forgejo (Git auto-hébergé)
`3011`	Welcome page
`19100`	Loki
`19200`	Tempo
`4040`	Pyroscope
`4317`, `4318`	Tempo OTLP (gRPC, HTTP)
`4444`	Selenium Grid Hub
`5601`	OpenSearch Dashboards
`7900`	Selenium VNC viewer
`9080`	Backend HTTP (Spring Boot)
`9086`	Squash TM
`9087`	Documentation MkDocs
`9090`	Backend management (actuator, heap dump) — interne Docker uniquement
`9091`	Frontend shop
`9092`	Prometheus
`9201`	OpenSearch API
`9270`	JMeter Prometheus exporter

Tous ces ports sont configurables via les variables d'environnement dans .env — voir la référence des variables d'environnement. Avant un premier docker compose up, vérifiez qu'aucun de ces ports n'est déjà utilisé par un autre service sur votre machine.

Règle Docker Desktop

Dans la configuration par défaut, aucun port en 80xx n'est utilisé — Docker Desktop réserve ces ports pour son propre usage et ils peuvent générer des conflits sur certaines plateformes. C'est pourquoi Squash TM est sur 9086 et non 8086, et le backend sur 9080 et non 8080.

Check rapide¶

Pour valider votre environnement avant de cloner le projet :

docker --version              # ≥ 24
docker compose version        # ≥ v2
git --version                 # ≥ 2.30

# Optionnels (développement natif)
java -version                 # ≥ 21
mvn --version                 # ≥ 3.9
node --version                # ≥ 20

Si toutes ces commandes répondent, vous êtes prêt pour Cloner depuis Forgejo.