🛠️ EMCST — Erevos Minecraft Server Toolkit

Version 2.0.0 — Orchestrateur modulaire et boîte à outils d'administration système pour serveurs Minecraft (Vanilla, NeoForge, Fabric, Forge).

---

📖 Philosophie et Architecture

EMCST repose sur une approche Sysadmin-First et applique la stricte séparation des responsabilités (Rule of Separation) :

🧠 "L'Intelligence & l'UX sont dans Python. L'Action Système & la Collecte d'État sont dans les Scripts Bash."

• Scripts Bash (scripts/) : Forment une boîte à outils système 100 % autonome. Ils manipulent l'OS (processus, disques, tubes FIFO, binaires) et renvoient des faits bruts sous forme de codes retours ou de structures de données JSON. Un administrateur système peut exécuter et déboguer chaque script unitairement en ligne de commande, sans Python.
• Python (src/) : Joue le rôle d'Hyperviseur / Orchestrateur. Il charge les configurations TOML, valide les règles de cohérence, appelle les scripts Bash via subprocess, consomme leurs retours JSON, applique la logique métier (normalisation de la charge CPU, parsing des regexes) et offre une interface utilisateur soignée (coloration syntaxique en temps réel, autocomplétion Readline [Tab], tableaux de bord de santé).

• Architecture Multi-Serveurs Découplée :
  • config/main.toml (Socle Hôte / Modules Globaux) : Déclare le contexte d'exécution (runner UID/GID 825), les scripts, les dépendances système et les modules d'infrastructure (ramdisk, backup, snapshot).
  • config/servers/<serveur>.toml (Profils d'Instances) : Chaque instance possède son profil autonome (server_id, game_version, loader, loader_version, is_ramdisk, ram_allocation, java_parameters, installed).
• Sécurité & Contrôle Explicite :
  • Le ciblage d'un serveur (<serveur_ou_id>) est strictement obligatoire pour toutes les commandes d'action (create, start, status, stop, cmd, restart, console, remove) afin d'éviter toute manipulation accidentelle en environnement multi-instances.
• Empreinte d'Instance Automatique (Fingerprinting) :
  • server_id est calculé de manière déterministe (SHA-256(slug)[:8]) et gravé automatiquement dans le profil lors de l'initialisation.
• Gestionnaire de Runtimes Java Isolés (Zero Host Java) :
  • Aucun Java n'est requis sur l'hôte.
  • EMCST télécharge et gère des JREs portables officielles (Eclipse Temurin / Adoptium) dans live/java_runtimes/<version>/ (ex: Java 21, Java 17, Java 8).
  • La version requise est déduite automatiquement selon game_version (ex: MC 1.21.1 ➡️ Java 21).
• Zéro Magie & Configuration Stricte :
  • Les versions du jeu et du loader sont explicitement définies dans le profil du serveur.
  • Règles de Cohérence :
    • loader = "vanilla" ➡️ loader_version doit être omis ou vide ("").
    • loader = "neoforge" / "fabric" ➡️ loader_version est obligatoire (ex: "21.1.249").
• Identité Système Dédiée (Runner) : UID/GID fixe (825:825) pour garantir l'intégrité des ACLs et des réplications de sauvegardes multi-machines.

---

🏷️ Convention de Nommage des Scripts (scripts/)

Préfixe	Domaine & Rôle	Correspondance CLI / Usage
core-*	Socle transverse : Utilitaires atomiques mutualisés	Utilisation interne
init-*	Provisionnement Hôte : Privilèges wheel, compte Runner	emcst init
storage-*	Stockage & Fichiers : Détection Btrfs, création de sous-volumes	Assistant stockage
runtime-*	Runtimes Java : Téléchargement et isolation des JREs	emcst runtime
server-*	Cycle de vie du Jeu : Installation, démarrage FIFO, métriques JSON, console, suppression	emcst server
backup-*	Sauvegardes & Snapshots : Sync tmpfs ➡️ Disque, Snapshots CoW	emcst backup

---

🗂️ Structure du Projet

erv-mc-server-toolkit/
├── config/
│   ├── main.toml                # Configuration centrale (Socle Hôte, Runner, Modules Globaux)
│   └── servers/                 # Profils des instances de serveurs
│       └── erevos.toml          # Profil du serveur Erevos (NeoForge 1.21.1)
├── emcst.py                     # Point d'entrée CLI et routeur de commandes
├── src/
│   ├── core/
│   │   ├── config.py            # Chargeur TOML (Hyperviseur & Profils Serveurs)
│   │   └── console.py           # Formatage ANSI, coloration syntaxique logs Minecraft
│   └── modules/
│       ├── init.py              # Moteur dynamique d'initialisation et validation
│       ├── runtime.py           # Gestionnaire de runtimes Java isolés (Adoptium)
│       ├── server.py            # Gestionnaire du cycle de vie des instances (Orchestration & UX)
│       └── mods.py              # Analyseur de mises à jour de mods (API Modrinth)
├── scripts/
│   ├── core-check-dep.sh        # Mission : Validation d'un binaire absolu (+x, stat)
│   ├── core-ensure-dir.sh       # Mission : Validation / Création d'un dossier (+w, mkdir)
│   ├── init-check-wheel.sh      # Mission : Vérification d'appartenance au groupe wheel/sudo
│   ├── init-check-runner.sh     # Mission : Vérification de conformité du compte Runner
│   ├── init-create-runner.sh    # Mission : Création et vérification du compte Runner (825:825)
│   ├── storage-discover.sh      # Mission : Cartographie globale des points de montage Btrfs
│   ├── storage-setup-btrfs.sh   # Mission : Assistant autonome de provisionnement du stockage
│   ├── runtime-fetch-java.sh    # Mission : Téléchargement et déploiement d'une JRE portable
│   ├── server-install.sh        # Mission : Installation unitaire du serveur (NeoForge/Fabric/Vanilla)
│   ├── server-start.sh          # Mission : Lancement en arrière-plan avec tube FIFO anti-EOF
│   ├── server-stop.sh           # Mission : Arrêt propre (save-all + stop) avec timeout
│   ├── server-cmd.sh            # Mission : Injection d'une commande dans le tube FIFO de contrôle
│   ├── server-metrics.sh        # Mission : Collecte des métriques d'exécution OS (Sortie JSON)
│   ├── server-tps.sh            # Mission : Interrogation unitaire du TPS/MSPT via FIFO + logs
│   ├── server-console.sh        # Mission : Console interactive basique
│   ├── server-remove.sh         # Mission : Suppression sécurisée de l'espace de travail et config
│   └── mods_updater/            # Scripts dédiés au module mods_updater
├── live/
│   ├── java_runtimes/           # JREs portables isolées (21/, 17/, 8/)
│   └── servers/                 # Espaces de travail étanches par instance
│       └── 90abcef/             # Instance Erevos (run.sh, libraries/, mods/, docs/)
└── README.md

---

🎮 Gestion d'une Instance (emcst server <cible> ou emcst -s <cible>)

Toutes les opérations ciblant une instance précise passent par emcst server <cible> <action> (ou le raccourci emcst -s <cible> <action>).

# Diagnostic & Performances
emcst server erevos status             # Statut complet, santé, TPS Spark, CPU, RAM RSS
emcst server erevos console            # Console interactive FIFO (logs temps réel + autocomplétion)
emcst server erevos logs [-n 100] [-f] # Consultation / suivi des logs (latest.log)
emcst server erevos cmd "say Bonjour"  # Injection d'une commande one-shot

# Alimentation & Cycle de vie
emcst server erevos start              # Démarrage en arrière-plan (RAMDisk + FIFO)
emcst server erevos stop               # Arrêt propre (save-all flush + stop)
emcst server erevos restart            # Redémarrage gracieux

# Configuration & Mods
emcst server erevos edit               # Édition du profil TOML dans Neovim avec validation
emcst server erevos mods list          # Inventaire exhaustif de TOUS les mods installés
emcst server erevos mods search <mot>  # Recherche de mods compatibles sur Modrinth
emcst server erevos mods install <mod> # Installation propre (+ dépendances + droits 825:825)
emcst server erevos mods update        # Mise à jour des mods installés vers leur dernière version
emcst server erevos mods remove <mod>  # Suppression propre (live + stockage persistant)
emcst server erevos mods check [-V]    # Contrôle filtré des MàJ disponibles (+ changelogs)
emcst server erevos mods report        # Consultation du dernier rapport de changelogs
emcst server erevos mods quickcheck    # Contrôle rapide silencieux pour scripts (0/1)

# Modpack Client & Distribution
emcst server erevos modpack build       # Génération de l'archive .mrpack (+ webhook Discord)
emcst server erevos modpack status      # Statut du modpack et des URLs de distribution
emcst server erevos modpack webhook-test # Test d'envoi de la notification Discord

# Persistance & Sauvegardes
emcst server erevos sync               # Synchronisation différentielle RAMDisk ➡️ Disque
emcst server erevos snapshot create    # Instantané Btrfs local CoW (0 ms)
emcst server erevos snapshot list      # Liste des instantanés disponibles
emcst server erevos snapshot restore <nom> # Restauration d'un instantané
emcst server erevos backup             # Création d'une archive physique autonome (.tar.zst)

# Intégration Système
emcst server erevos systemd install    # Génération et activation des unités Systemd
emcst server erevos systemd status     # État du service et des minuteurs
emcst server erevos fix-perms          # Réalignement strict des droits Runner 825:825

# Provisionnement
emcst server erevos create             # Installation initiale du moteur et JRE
emcst server erevos remove [--force]   # Désinstallation sécurisée de l'instance

---

🌐 Gestion Globale du Parc (emcst servers ou emcst -ss)

Opérations consolidées et batch sur l'ensemble des serveurs du cluster :

# Inventaire & Tableau de bord
emcst servers                          # Liste synthétique de toutes les instances déclarées
emcst servers list                     # Idem
emcst servers status                   # Rapport de santé consolidé de tous les serveurs actifs

# Alimentation en batch
emcst servers start                    # Démarre tous les serveurs configurés
emcst servers stop                     # Arrête proprement tous les serveurs allumés
emcst servers restart                  # Redémarre tout le parc

# Maintenance globale
emcst servers sync                     # Synchronise tous les RAMDisks actifs vers disque
emcst servers backup                   # Déclenche une archive physique (.tar.zst) pour chaque serveur

---

⚙️ Structure d'un Profil Serveur (config/servers/<serveur>.toml)

Chaque serveur est configuré par un fichier TOML autonome :

# ==============================================================================
# PROFIL DU SERVEUR MINECRAFT : EREVOS
# ==============================================================================

[server]

# Exécution en mémoire vive (RAM Disk tmpfs) : true / false
is_ramdisk = false

# Métadonnées du serveur
server_name = "Erevos Minecraft Serveur"
server_id = "90abcef" # Calculé automatiquement par EMCST (SHA-256 du slug)
server_description = "Serveur de survie technique moddé."

# Versions du jeu et du moteur
game_version = "1.21.1"
loader = "neoforge" # "neoforge", "fabric", "forge" ou "vanilla"
loader_version = "21.1.249"

# ==============================================================================
# PARAMÈTRES JVM & ALLOCATION MÉMOIRE
# Règle d'or : Pré-allocation stricte -Xms = -Xmx
# ==============================================================================
ram_allocation = "12G"
java_parameters = "-XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=150 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=35 -XX:G1MaxNewSizePercent=45 -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -XX:+UseNUMA"

# Indicateur d'état d'installation
installed = true

[server.rcon]
host = "127.0.0.1"
port = 25575

---

☕ Gestion des Runtimes Java (emcst runtime)

# Lister les versions Java portables installées localement
python3 emcst.py runtime list

# Télécharger et installer une version spécifique (ex: 21, 17, 8)
python3 emcst.py runtime install 21

---

🏗️ Initialisation & Environnement (emcst init)

python3 emcst.py init

Vérifie les privilèges (wheel), valide le compte du Runner (825:825), prépare l'ensemble des dossiers *.fs et valide les dépendances *.deps.

---

🧩 Gestion des Mods & Provider Hybride (Modrinth + Fallback CurseForge)

EMCST utilise une architecture double provider pour identifier 100% de vos mods :

1. Modrinth (Principal) : Scan par empreinte SHA-1 en batch ultra-rapide (aucune clé requise).
2. CurseForge (Fallback optionnel) : Si une clé curseforge_api_key est renseignée dans config/main.toml, les fichiers non reconnus sur Modrinth sont automatiquement analysés via l'algorithme d'empreinte Murmur2 sur CurseForge.

# Inventaire exhaustif de tous les mods installés
emcst server erevos mods list

# Rechercher des mods compatibles sur Modrinth (filtrés selon MC 1.21.1 / NeoForge)
emcst server erevos mods search "waystones"

# Installer un mod depuis Modrinth (résout les dépendances et garantit les droits 825:825)
emcst server erevos mods install waystones

# Mettre à jour tous les mods installés vers leur dernière version compatible
emcst server erevos mods update

# Supprimer proprement un mod (retiré de l'espace live ET du stockage persistant)
emcst server erevos mods remove waystones

# Contrôle filtré des mises à jour disponibles
emcst server erevos mods check

# Contrôle avec affichage direct du rapport complet glow
emcst server erevos mods check -V

# Afficher le dernier rapport Markdown généré
emcst server erevos mods report

# Contrôle rapide silencieux pour scripts/cron (code retour 0 si MàJ dispo, 1 sinon)
emcst server erevos mods quickcheck

---

📦 Modpack Client, Distribution Web & Webhooks Discord

EMCST génère des modpacks officiels au standard Modrinth (.mrpack), prêts à être importés dans Prism Launcher, Modrinth App ou ATLauncher.

• Nommage versionné & Alias permanent :
  • Archive physique : erevos-modpack-v1.0.016.mrpack
  • Alias permanent Prism : erevos-modpack-latest.mrpack (permettant la mise à jour 1-clic)
• Serveur Web durci : distribution native sans dépendance sur le port configuré (8080).
• Notifications Discord automatiques : envoi d'un Embed riche avec liens directs lors de chaque publication.

# Compiler le modpack client (incrémente automatiquement l'itération et notifie Discord)
emcst server erevos modpack build

# Consulter l'état du modpack publié et les URLs de téléchargement
emcst server erevos modpack status

# Tester la configuration du Webhook Discord
emcst server erevos modpack webhook-test

---

📜 Cache des Manifestes & Métadonnées (emcst manifest)

EMCST maintient un cache local des manifestes officiels (Mojang, Fabric, NeoForge, Forge, Adoptium) avec gestion native du cache HTTP (304 Not Modified / ETag) et planification Systemd (OnCalendar).

# Consulter l'état du cache local des manifestes
python3 emcst.py manifest list

# Synchroniser tous les manifestes configurés (mojang, fabric, neoforge, forge, adoptium)
python3 emcst.py manifest sync

# Forcer la synchronisation d'un provider spécifique
python3 emcst.py manifest sync adoptium --force

⚡ Autocomplétion Shell (Bash, Zsh, Fish)

EMCST inclut des scripts d'autocomplétion avancée avec détection dynamique des instances de serveurs et descriptions enrichies :

• Bash : completions/emcst.bash (/usr/share/bash-completion/completions/emcst ou /etc/bash_completion.d/emcst)
• Zsh : completions/emcst.zsh (/usr/share/zsh/site-functions/_emcst)
• Fish : completions/emcst.fish (/usr/share/fish/vendor_completions.d/emcst.fish ou ~/.config/fish/completions/emcst.fish)

Note

Les scripts d'autocomplétion sont installés et actualisés automatiquement lors de l'exécution de sudo ./install.sh ou sudo ./update.sh.

# Pour charger immédiatement l'autocomplétion dans votre session active :
# Bash
source completions/emcst.bash

# Zsh
fpath=(completions $fpath) && autoload -U compinit && compinit

# Fish
cp completions/emcst.fish ~/.config/fish/completions/

---

🚀 Déploiement, Mise à Jour & Désinstallation

Action	Commande	Description
Installation	sudo ./install.sh	Déploie l'orchestrateur dans /srv/emcst, configure le compte runner 825:825, le pool Btrfs et /usr/local/bin/emcst.
Mise à Jour	sudo ./update.sh	Met à jour le code, scripts et unités Systemd sans toucher aux données et configurations.
Désinstallation	sudo ./uninstall.sh	Arrête les serveurs, supprime les unités Systemd, démonte les points de montage, nettoie /etc/fstab, supprime /usr/local/bin/emcst et retire le runner.

# Désinstallation interactive avec choix de conservation des données
sudo ./uninstall.sh

# Désinstallation avec purge totale et définitive de toutes les données (/srv/emcst)
sudo ./uninstall.sh --purge

# Simulation sans modification (dry-run)
sudo ./uninstall.sh --dry-run

---

📊 État d'Avancement du Projet (Session du 01/09/2026)

✅ Réalisé & Validé

• Déploiement & Installateur de Production (install.sh, update.sh, uninstall.sh) :
  • Détection interactive et cartographie complète du stockage (lsblk et btrfs filesystem show).
  • Création universelle du sous-volume racine @emcst via montage éphémère subvolid=5.
  • Déclaration persistante et encadrée dans /etc/fstab (##### ajouté par emcst le JJ/MM/AAAA #####) avec sauvegarde automatique (fstab.bak).
  • Matrice de sécurité stricte : code/scripts root:emcst (0755/0644), données live/ & storage/ isolées emcst:emcst (0750).
  • Script de désinstallation complète uninstall.sh (purge totale ou rétention des données, démontages, nettoyage /etc/fstab, suppression du compte runner emcst et des unités Systemd).
  • Wrapper global exécutable /usr/local/bin/emcst.
• Architecture de Stockage & Découplage Persistance / Runtime :
  • Point d'exécution universel : live/servers/<id>/ (monté dynamiquement en tmpfs si is_ramdisk = true).
  • Persistance sur disque Btrfs : storage/<id>/base/ (sous-volume Btrfs dédié créé automatiquement à l'installation de l'instance).
  • Conteneurs snapshots/ (pour les sous-volumes CoW) et backups/ (pour les archives .tar.zst).
• Synchronisation Différentielle (scripts/storage-sync.sh) :
  • Script léger exécutable par timer ou CLI : émission de save-all flush dans le tube FIFO + rsync différentiel.
  • Commandes CLI : emcst sync <cible> et emcst server <cible> sync.
• Gestionnaire de JREs Adoptium (Zero Host Java) :
  • Téléchargement et isolation des versions Temurin OpenJDK (21, 17, 8) dans live/java_runtimes/<version>/.
  • Détection automatique de la version Java requise selon game_version.
• Cache des Manifestes & Métadonnées (emcst manifest) :
  • Synchronisation multi-providers (Mojang, Fabric, NeoForge, Forge, Adoptium) avec gestion du cache HTTP 304.
• Orchestration du Cycle de Vie (emcst server) :
  • Commandes d'action avec ciblage explicite : create, start, stop, restart, status, console, cmd, remove.
  • Tube de contrôle interactif FIFO anti-EOF et monitoring des métriques (TPS/MSPT Spark & NeoForge, CPU normalisé, RAM RSS).

---

🎯 Feuille de Route & Prochaines Étapes (Reprise)

1. 📸 Sous-menu snapshot dédié (Priorité 1)

• Restauration instantanée CoW Btrfs : Restauration en 0 ms sans rsync lourd via btrfs subvolume snapshot storage/<id>/snapshots/<nom> storage/<id>/base.
• Sélection interactive : Menu numéroté [1], [2], [3]... pour restore et delete sans avoir à copier-coller les longs noms d'instantanés.
• Tags personnalisés : Possibilité de nommer ou annoter un snapshot (emcst snapshot erevos create "avant-maj").
• Suppression unitaire : Commande emcst snapshot erevos delete <nom_ou_index>.
• Module Python dédié : Création de src/modules/snapshot.py pour un découplage propre.

2. 🔌 Sous-menu systemd (emcst systemd)

• Commandes de gestion : emcst systemd install, emcst systemd update, emcst systemd remove.
• Modèles de services d'instances : minecraft@<instance>.service avec isolation User=emcst et Restart=on-failure.
• Minuteurs périodiques :
  • minecraft-sync@<instance>.timer : Synchronisation différentielle régulière RAMDisk ➡️ storage/base.
  • minecraft-backup@<instance>.timer : Archivage physique ou instantanés Btrfs planifiés.
  • emcst-manifest-sync.timer : Rafraîchissement hebdomadaire des manifestes.

3. 🧪 Tests d'Intégration & Validation

• Test complet de bout en bout sur le serveur cible ProLiant (install Btrfs ➡️ server create ➡️ start ➡️ sync ➡️ snapshot ➡️ restore).