Prerequisites¶

This page lists the tools required to deploy and develop PerfShop locally. Two scenarios are covered: Docker Compose deployment (the recommended mode) and native development (to iterate on the Spring Boot backend or the React frontend without a container).

Docker Compose deployment¶

This is the main scenario. All PerfShop components (backend, frontend, database, observability, QA stack) are containerized and orchestrated by Docker Compose. A single binary to install to run the whole thing.

Operating system¶

OS	Support	Notes
Windows 10/11	✅ Via Docker Desktop + WSL2	Requires a WSL2 backend enabled in Docker Desktop
macOS 12+	✅ Via Docker Desktop	Decent performance on Apple Silicon
Ubuntu 22.04+	✅ Native Docker Engine	The best performing option
Debian 12+	✅ Native Docker Engine	Same as Ubuntu
Synology DSM 7+	✅ Container Manager	NAS production use — see deployment topology

Docker¶

Docker Engine 24+ or Docker Desktop 4.30+
Docker Compose v2 (docker compose and not legacy docker-compose)

Check:

docker --version
# Docker version 26.x or higher

docker compose version
# Docker Compose version v2.x or higher

Recommended minimum resources¶

The full PerfShop stack (core + observability + QA) consumes about 6 to 8 GB of RAM and puts moderate load on the CPU. For a comfortable deployment:

Resource	Minimum	Comfortable
CPU	4 cores	8 cores
RAM	8 GB	16 GB
Disk	20 GB free	50 GB free

On Docker Desktop Windows/macOS, these limits are configured in Settings → Resources. The backend is particularly sensitive to the RAM allocated to the JVM for memory chaos and OOM demonstrations.

Native backend development¶

If you want to modify Java code and iterate quickly without rebuilding a Docker image every time.

Java¶

Java 21 LTS (OpenJDK, Temurin, Zulu, Amazon Corretto — your choice).

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

Spring Boot 3.2 requires Java 17 minimum; PerfShop uses modern language features (pattern matching, records, switch expressions) that are stable in Java 21.

Maven¶

Maven 3.9+.

mvn --version
# Apache Maven 3.9.x or higher

The project uses the spring-boot-maven-plugin to package a standalone executable JAR.

MySQL (optional)¶

In native development, two options:

MySQL container — start only perfshop-db via docker compose up -d perfshop-db and run the backend locally pointing to localhost:19306
Native MySQL 8 — install MySQL 8 and create a perfshop database by hand with the credentials from .env

The first option is simpler and avoids having to deal with a MySQL installation.

Native frontend development¶

To iterate on the React interface with Vite hot reload.

Node.js¶

Node 20 LTS or newer.

node --version
# v20.x or higher

npm --version
# 10.x or higher

Vite 5 requires Node 18 minimum; Node 20 is recommended to benefit from the native fetch and improved performance.

Package manager¶

npm (shipped with Node) is enough. package-lock.json files are committed to guarantee reproducible installations.

Git¶

Git 2.30+ to clone the repository and manage branches.

git --version
# git version 2.30.x or higher

Modern browser¶

To access PerfShop interfaces, a recent browser:

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

The chaos-admin and monitoring interfaces use modern JavaScript features (ES2020+, optional chaining, nullish coalescing) that are not polyfilled.

Required host ports¶

The PerfShop stack exposes many services on the host. Here are the ports used in the default configuration:

Port	Service
`3001`	Monitoring HTML
`3002`	Grafana
`3003`	chaos-admin (student page + instructor panel)
`3004`	Admin backoffice
`3005`	JMeter UI
`3007`	Filebrowser
`3008`	Scripts UI
`3009`	Forgejo (self-hosted Git)
`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`	MkDocs documentation
`9090`	Backend management (actuator, heap dump) — Docker internal only
`9091`	Frontend shop
`9092`	Prometheus
`9201`	OpenSearch API
`9270`	JMeter Prometheus exporter

All these ports are configurable through environment variables in .env — see the environment variables reference. Before a first docker compose up, check that none of these ports are already in use by another service on your machine.

Docker Desktop rule

In the default configuration, no port in the 80xx range is used — Docker Desktop reserves these ports for its own use and they can cause conflicts on some platforms. That is why Squash TM is on 9086 and not 8086, and the backend on 9080 and not 8080.

Quick check¶

To validate your environment before cloning the project:

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

# Optional (native development)
java -version                 # ≥ 21
mvn --version                 # ≥ 3.9
node --version                # ≥ 20

If all these commands respond, you are ready for Clone from Forgejo.