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/.