Build backend¶

This page explains how to build and run the Spring Boot backend outside of Docker, in order to iterate quickly during development using your IDE's hot reload.

Target stack¶

Spring Boot 3.2
Java 21 LTS
Maven 3.9+
MySQL 8 (container or native)

See Prerequisites for exact versions.

Building with Maven¶

From the repository root:

cd backend
mvn clean package

The build compiles the Java code, runs the JUnit tests, and produces an executable JAR in backend/target/perfshop-0.1.0-beta.jar (the exact name depends on the version declared in pom.xml).

Skipping the tests¶

For a faster iteration cycle:

mvn clean package -DskipTests

To be used only in local development — CI and release builds must always run the tests.

Building with the provided script¶

A build.sh script is provided at the repository root to build both the backend and the Docker images:

./build.sh

Its Windows equivalent is build.bat. Check the script content for the detail of the steps it runs.

Running locally (without Docker)¶

Start the MySQL database¶

The simplest approach is to start only the MySQL container from the main compose file:

docker compose -f docker-compose.desktop.yml up -d perfshop-db

This starts MySQL 8 on localhost:19306 with the credentials defined in .env. Flyway will automatically run V1 through V10 the first time the backend starts.

Alternatively, you can use a native MySQL installation if you prefer — just create a perfshop database and a user with the necessary privileges.

Run Spring Boot¶

From backend/:

mvn spring-boot:run

Spring Boot starts on port 8080 by default (not 9080 — that is the Docker Compose mapping that redirects 9080:8080 in containerized mode; locally, you use the internal port directly).

Run the JAR directly¶

If you prefer to launch the packaged JAR:

java -jar target/perfshop-0.1.0-beta.jar

Configuration via environment variables¶

The backend is fully configurable through environment variables. The most important ones:

Variable	Default	Role
`SPRING_DATASOURCE_URL`	`jdbc:mysql://localhost:19306/perfshop`	JDBC URL of the database
`SPRING_DATASOURCE_USERNAME`	`perfshop`	MySQL user
`SPRING_DATASOURCE_PASSWORD`	`perfshop123`	MySQL password
`PERFSHOP_LANG`	`fr`	Active language (`fr` or `en`)
`PERFSHOP_ADMIN_EMAIL`	`admin@perfshop.fr`	Superadmin email (bootstrap)
`PERFSHOP_ADMIN_PASSWORD`	`perfshop`	Superadmin password (bootstrap)
`PERFSHOP_LICENSE_KEY`	(empty)	License key to preload at startup
`CORS_ALLOWED_ORIGINS`	`http://localhost:9091,...`	Allowed origins for CORS

The full list is in the environment variables reference.

Windows PowerShell¶

$env:SPRING_DATASOURCE_URL = "jdbc:mysql://localhost:19306/perfshop"
$env:PERFSHOP_LANG = "fr"
mvn spring-boot:run

Unix / macOS¶

export SPRING_DATASOURCE_URL=jdbc:mysql://localhost:19306/perfshop
export PERFSHOP_LANG=fr
mvn spring-boot:run

Using a `.env` file¶

Or more simply, use your existing .env file together with an IDE plugin that injects it (IntelliJ, VS Code). Spring Boot's application.yml references standard environment variables via ${VAR:default}.

Checking that the backend is up¶

Once started, three endpoints are useful to verify the state:

# Basic health
curl http://localhost:8080/actuator/health
# → {"status":"UP"}

# Build info
curl http://localhost:8080/actuator/info

# Prometheus metrics
curl http://localhost:8080/actuator/prometheus | head -20

The management port 9090 used by certain sensitive endpoints (heap dump, thread dump) is only exposed in containerized mode.

Hot reload and dev loop¶

Spring Boot DevTools is included in the development dependencies. When it detects a change in target/classes/, it automatically restarts the application context — much faster than a full JVM restart.

To benefit from hot reload in IntelliJ:

File → Settings → Build → Compiler: check Build project automatically
File → Settings → Advanced Settings: check Allow auto-make to start even if developed application is currently running

In VS Code with the Spring Boot Dashboard extension, automatic restart is enabled by default as soon as DevTools is present.

Unit tests¶

mvn test

The tests use JUnit 5 and Spring Boot Test. They run against an in-memory H2 database when possible, or against a MySQL Testcontainers instance for more advanced integration tests.

Debugging¶

To attach an IDE debugger to the backend:

mvn spring-boot:run -Dspring-boot.run.jvmArguments="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005"

Then in your IDE, create a Remote JVM Debug configuration pointing at localhost:5005.

Building the Docker image without Docker Compose¶

If you want to build just the backend Docker image without the rest of the stack:

cd backend
docker build -t perfshop-app:local .

The Dockerfile is a multi-stage one that compiles with Maven and then copies the JAR into a minimal eclipse-temurin:21-jre image.