03 – Guide de Démarrage Rapide
Version : 4.0.0 Date : 2025-01-25 Temps estimé : 5 minutes
1. Prérequis
- JDK 21+ installé
- Maven 3.9+ installé
- Git (optionnel)
Vérification :
java -version # java version "21.x.x"
mvn -version # Maven 3.9.x
2. Installation
Option A : Cloner le projet
git clone <repo>/socle-v004.git
cd socle-v004
Option B : Créer un nouveau projet
mvn archetype:generate \
-DgroupId=com.mycompany \
-DartifactId=my-socle-app \
-DarchetypeArtifactId=maven-archetype-quickstart \
-DinteractiveMode=false
cd my-socle-app
# Ajouter la dépendance socle-v004 dans pom.xml
3. Configuration minimale
3.1 pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>eu.lmvi</groupId>
<artifactId>socle-v004</artifactId>
<version>4.0.0</version>
<packaging>jar</packaging>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.2.1</version>
</parent>
<properties>
<java.version>21</java.version>
</properties>
<dependencies>
<!-- Spring Boot Web (sans Logback) -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
<exclusions>
<exclusion>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- Log4j2 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-log4j2</artifactId>
</dependency>
<!-- LMAX Disruptor (AsyncLoggers) -->
<dependency>
<groupId>com.lmax</groupId>
<artifactId>disruptor</artifactId>
<version>4.0.0</version>
</dependency>
<!-- H2 Database -->
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.2.224</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>
3.2 application.yml
spring:
application:
name: my-socle-app
socle:
app_name: ${APP_NAME:my-socle-app}
version: 4.0.0
env_name: ${ENV_NAME:DEV}
region: ${REGION:local}
# HTTP
http_port: ${HTTP_PORT:8080}
# KV Bus
kv_impl: in_memory
# Supervisor
supervisor_enabled: true
# H2 TechDB
techdb:
enabled: true
url: jdbc:h2:file:./data/techdb;MODE=PostgreSQL
console:
enabled: true
path: /h2-console
logging:
config: classpath:log4j2.xml
3.3 log4j2.xml
<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN">
<Appenders>
<Console name="Console" target="SYSTEM_OUT">
<PatternLayout pattern="%d{ISO8601} %-5level [%thread] %logger{36} - %msg%n"/>
</Console>
</Appenders>
<Loggers>
<Root level="INFO">
<AppenderRef ref="Console"/>
</Root>
</Loggers>
</Configuration>
4. Créer un Worker simple
package com.mycompany.worker;
import eu.lmvi.socle.worker.Worker;
import eu.lmvi.socle.supervisor.Supervisor;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;
import java.util.Map;
@Component
public class HelloWorker implements Worker {
private static final Logger log = LoggerFactory.getLogger(HelloWorker.class);
@Autowired
private Supervisor supervisor; // Injection du Supervisor
private int counter = 0;
private volatile boolean running = false;
@Override
public String getName() {
return "hello-worker";
}
@Override
public void initialize() {
log.info("HelloWorker initializing...");
}
@Override
public void start() {
running = true;
log.info("HelloWorker started!");
}
@Override
public void doWork() {
if (!running) return; // Vérifier le flag d'arrêt
try {
counter++;
log.info("Hello from worker! Count: {}", counter);
// IMPORTANT: Envoyer un heartbeat avec métriques
supervisor.heartbeat(getName(), getStats());
} catch (Exception e) {
log.error("Erreur dans doWork", e);
// NE PAS propager l'exception
}
}
@Override
public void stop() {
running = false;
log.info("HelloWorker stopped. Final count: {}", counter);
}
@Override
public boolean isHealthy() {
return running;
}
@Override
public Map<String, Object> getStats() {
return Map.of(
"counter", counter,
"running", running
);
}
@Override
public long getCycleIntervalMs() {
return 5000; // doWork() toutes les 5 secondes
}
}
5. Build et Run
# Build
mvn clean package -DskipTests
# Run
java -jar target/socle-v004-4.0.0.jar
# Ou avec variables d'environnement
APP_NAME=my-app ENV_NAME=PROD java -jar target/socle-v004-4.0.0.jar
6. Vérification
Health check
curl http://localhost:8080/health
Réponse attendue :
{
"status": "UP",
"app": "my-socle-app",
"version": "4.0.0"
}
H2 Console (dev)
Ouvrir : http://localhost:8080/h2-console
- JDBC URL :
jdbc:h2:file:./data/techdb - User :
socle - Password :
socle
Logs
Vous devriez voir :
INFO [main] MainOrchestratorProcess - MOP démarré
INFO [main] HelloWorker - HelloWorker started!
INFO [scheduler-1] HelloWorker - Hello from worker! Count: 1
INFO [scheduler-1] HelloWorker - Hello from worker! Count: 2
StatusDashboard (supervision)
Ouvrir : http://localhost:9374/
Ce dashboard affiche en temps réel :
- L’état de chaque worker (RUNNING, DEGRADED, UNHEALTHY)
- Les métriques transmises par les heartbeats
- L’historique des changements d’état
7. Prochaines étapes
| Document | Description |
|---|---|
| 04-CONFIGURATION | Configuration complète |
| 05-WORKERS | Guide des Workers |
| 08-SUPERVISOR | Supervision et heartbeats |
| 21-H2-TECHDB | Base H2 TechDB |
| 22-LOG4J2-LOGFORWARDER | Logging centralisé |
| 27-STATUS-DASHBOARD | Dashboard de supervision |
| GUIDE-METHODOLOGIQUE | Bonnes pratiques |
8. Troubleshooting
Port déjà utilisé
# Changer le port
HTTP_PORT=9090 java -jar target/socle-v004-4.0.0.jar
H2 Console inaccessible
Vérifier que socle.techdb.console.enabled: true dans application.yml.
Logs non visibles
Vérifier que log4j2.xml existe dans src/main/resources/.
