# 🎮 Ansible Minecraft Spigot Server

[![Ansible](https://img.shields.io/badge/Ansible-4.0%2B-red?style=flat-square&logo=ansible)](https://www.ansible.com/)
[![Minecraft](https://img.shields.io/badge/Minecraft-1.21.6-green?style=flat-square&logo=minecraft)](https://www.minecraft.net/)
[![Java](https://img.shields.io/badge/Java-17-orange?style=flat-square&logo=java)](https://openjdk.java.net/)
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)

Déploiement automatisé et professionnel d'un serveur Minecraft Spigot avec sécurité avancée, sauvegardes automatiques et mise à jour continue via Ansible.

## 📋 Table des matières

- [🎯 Vue d'ensemble](#-vue-densemble)
- [✨ Fonctionnalités](#-fonctionnalités)
- [🏗️ Architecture](#-architecture)
- [🚀 Installation rapide](#-installation-rapide)
- [⚙️ Configuration](#-configuration)
- [🎛️ Utilisation](#-utilisation)
- [🔒 Sécurité](#-sécurité)
- [💾 Sauvegardes](#-sauvegardes)
- [🔄 Mises à jour](#-mises-à-jour)
- [🎮 Administration](#-administration)
- [📊 Monitoring](#-monitoring)
- [🧪 Tests](#-tests)
- [🔧 Dépannage](#-dépannage)
- [🤝 Contribution](#-contribution)

## 🎯 Vue d'ensemble

Ce projet Ansible automatise complètement l'installation, la configuration et la maintenance d'un serveur Minecraft Spigot version 1.21.6 sur des serveurs Linux (Debian/Ubuntu).

### Pourquoi ce projet ?

- ✅ **Déploiement zero-touch** en moins de 30 minutes
- ✅ **Sécurité niveau production** avec durcissement complet
- ✅ **Haute disponibilité** avec sauvegardes automatiques
- ✅ **Mises à jour sans interruption** de Spigot
- ✅ **CI/CD intégré** avec tests automatiques
- ✅ **Architecture évolutive** et modulaire

## ✨ Fonctionnalités

### 🛡️ Sécurité
- **Durcissement SSH** : Authentification par clés, port personnalisé, configuration sécurisée
- **Pare-feu UFW** : Règles minimales, ports spécifiques
- **Fail2ban** : Protection anti-bruteforce
- **Utilisateur dédié** : Isolation des processus Minecraft
- **Mises à jour automatiques** : Patches de sécurité système

### 🎮 Minecraft
- **Spigot 1.21.6** : Compilation automatique avec BuildTools
- **Java 17** : Installation et configuration optimisée
- **MCRCON** : Administration à distance du serveur
- **Service systemd** : Démarrage/arrêt propre, redémarrage automatique
- **Gestion des opérateurs** : Configuration automatisée des admins
- **Support plugins** : Répertoire et gestion dédiés

### 💾 Sauvegardes
- **Sauvegardes multiples** : Quotidiennes (7j), hebdomadaires (4s), mensuelles (6m)
- **Rsync optimisé** : Sauvegardes incrémentielles rapides
- **Scripts de restauration** : Remise en état automatisée
- **Arrêt sécurisé** : Notification joueurs avant sauvegarde

### 🔄 Maintenance
- **Mises à jour Spigot** : Téléchargement, compilation et basculement automatique
- **Rotation des logs** : Gestion intelligente de l'espace disque
- **Monitoring** : Vérification de santé du serveur
- **Rollback** : Retour version précédente en cas d'échec

## 🏗️ Architecture

```
📁 Structure du projet
├── 📁 .gitea/workflows/          # CI/CD Pipeline
├── 📁 inventories/               # Inventaires serveurs
│   ├── 📁 production/           # Environnement de production
│   └── 📁 staging/              # Environnement de test
├── 📁 roles/                    # Rôles Ansible modulaires
│   ├── 📁 01-server_hardening/   # Sécurisation serveur Linux
│   ├── 📁 02-installation-java/  # Installation Java OpenJDK
│   ├── 📁 03-installation-minecraft/ # Installation Spigot complet
│   ├── 📁 04-backups/           # Système de sauvegarde
│   └── 📁 05-update/            # Mises à jour automatiques
├── 📁 playbooks/                # Playbooks d'orchestration
├── 📄 requirements.yml          # Collections Ansible
├── 📄 secrets.example           # Template variables sensibles
└── 📄 README.md                 # Cette documentation
```

### 🎯 Rôles détaillés

| Rôle | Description | Fonctionnalités |
|------|-------------|-----------------|
| **01-server_hardening** | Sécurisation serveur | SSH, UFW, Fail2ban, Updates, Clés admin |
| **02-installation-java** | Installation Java | Détection, Installation OpenJDK 17, Validation |
| **03-installation-minecraft** | Installation Minecraft | Spigot, MCRCON, Service, Configuration, Logs |
| **04-backups** | Système sauvegarde | Scripts automatiques, Restauration, Rétention |
| **05-update** | Mises à jour | SSH, Système, Spigot, Basculement sécurisé |

## 🚀 Installation rapide

### Prérequis

- **Système local** : Ansible 4.0+, Python 3.8+, Git
- **Serveur cible** : Ubuntu 20.04+/Debian 10+, 4GB RAM minimum, 20GB disque
- **Réseau** : SSH accès root/sudo, ports 22 et 25565 accessibles
- **Utilisateur** : Compte `ansible` avec droits sudo configuré

### 1. Clonage et préparation

```bash
# Cloner le repository
git clone https://gitea.tips-of-mine.com/Tips-Of-Mine/Ansible-Minecraft-Serveur.git
cd Ansible-Minecraft-Serveur

# Installer les collections Ansible requises
ansible-galaxy collection install -r requirements.yml

# Vérifier l'installation
ansible --version
```

### 2. Configuration rapide

```bash
# Copier et éditer les secrets
cp secrets.example secrets
vim secrets

# Configurer l'inventaire de production
vim inventories/production/hosts.yml
vim inventories/production/group_vars/all.yml
```

### 3. Premier déploiement

```bash
# Test de connectivité
ansible all -i inventories/production/hosts.yml -m ping

# Déploiement complet (environ 20-30 minutes)
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml

# Vérification du statut final
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "systemctl status minecraft"
```

## ⚙️ Configuration

### 🔧 Variables principales

**inventories/production/group_vars/all.yml**

```yaml
# Configuration Minecraft
minecraft_version: "1.21.6"          # Version Spigot à installer
minecraft_memory_min: "2G"           # RAM minimum allouée
minecraft_memory_max: "4G"           # RAM maximum allouée
max_players: 20                      # Nombre max de joueurs
server_motd: "Mon serveur Ansible"   # Message d'accueil

# Configuration sécurité
ssh_port: 22                         # Port SSH (changer pour sécurité)
fail2ban_enabled: true               # Protection anti-bruteforce
firewall_enabled: true              # Activation pare-feu UFW

# Configuration sauvegardes
backup_retention_days: 7             # Rétention sauvegardes quotidiennes
backup_retention_weeks: 4            # Rétention sauvegardes hebdomadaires
backup_retention_months: 6           # Rétention sauvegardes mensuelles
```

### 🗝️ Gestion des secrets

**secrets (à créer)**

```bash
# Variables sensibles - NE PAS COMMITER !
export RCON_PASSWORD="motdepasse_ultra_securise"
export MINECRAFT_VERSION="1.21.6"

# Utilisateurs administrateurs
export ADMIN_USERS='[
  {
    "name": "admin1", 
    "key": "ssh-rsa AAAAB3NzaC1yc2E...", 
    "comment": "Administrateur 1"
  }
]'

# Opérateurs Minecraft  
export MINECRAFT_OPS='[
  {
    "name": "JoueurAdmin",
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "level": 4
  }
]'
```

### 🏠 Configuration inventaire

**inventories/production/hosts.yml**

```yaml
all:
  children:
    minecraft_servers:
      hosts:
        minecraft-prod-01:
          ansible_host: 192.168.1.100
          ansible_user: ansible
          ansible_ssh_private_key_file: ~/.ssh/minecraft_rsa
        minecraft-prod-02:
          ansible_host: 192.168.1.101
          ansible_user: ansible
          ansible_ssh_private_key_file: ~/.ssh/minecraft_rsa
```

## 🎛️ Utilisation

### Déploiements modulaires

```bash
# Déploiement complet
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml

# Sécurisation seulement
ansible-playbook playbooks/hardening.yml -i inventories/production/hosts.yml

# Installation Java seulement  
ansible-playbook playbooks/install-java.yml -i inventories/production/hosts.yml

# Installation Minecraft seulement
ansible-playbook playbooks/install-minecraft.yml -i inventories/production/hosts.yml

# Configuration sauvegardes seulement
ansible-playbook playbooks/setup-backups.yml -i inventories/production/hosts.yml

# Mises à jour seulement
ansible-playbook playbooks/update-system.yml -i inventories/production/hosts.yml
```

### Déploiement avec tags

```bash
# Seulement la partie sécurité
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --tags security,hardening

# Seulement Minecraft sans les sauvegardes  
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --tags minecraft,installation

# Seulement les mises à jour
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --tags update,maintenance
```

### Mode vérification

```bash
# Vérifier ce qui sera modifié (dry-run)
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --check --diff

# Test de syntaxe
ansible-playbook --syntax-check playbooks/site.yml -i inventories/production/hosts.yml
```

## 🔒 Sécurité

### Configuration SSH sécurisée

Le rôle `01-server_hardening` applique automatiquement :

- ✅ **Authentification par clés** uniquement (mots de passe désactivés)
- ✅ **Connexion root** désactivée  
- ✅ **Port SSH** configurable (défaut 22, recommandé : changer)
- ✅ **Tentatives limitées** : 3 essais maximum
- ✅ **Timeout automatique** : 5 minutes d'inactivité

### Pare-feu intelligent

```bash
# Règles UFW appliquées automatiquement
Port 22/tcp    → SSH (port configuré)
Port 25565/tcp → Minecraft
Tout le reste  → BLOQUÉ par défaut
```

### Protection Fail2ban

Configuration automatique pour :
- **SSH** : Ban après 3 tentatives échouées (10 minutes)
- **Logs** : Surveillance active des tentatives d'intrusion
- **Whitelist** : IPs administrateurs protégées

### Utilisateur dédié

```bash
# Isolation complète des processus
Utilisateur : minecraft
Groupe     : minecraft  
Home       : /opt/minecraft
Shell      : /bin/bash (limité)
Sudo       : NON (sécurité)
```

## 💾 Sauvegardes

### Types de sauvegardes automatiques

| Type | Fréquence | Rétention | Horaire | Script |
|------|-----------|-----------|---------|--------|
| **Quotidienne** | Tous les jours | 7 jours | 02:00 | `backup-daily.sh` |
| **Hebdomadaire** | Dimanche | 4 semaines | 03:00 | `backup-weekly.sh` |  
| **Mensuelle** | 1er du mois | 6 mois | 04:00 | `backup-monthly.sh` |

### Contenu sauvegardé

- 📁 **Monde Minecraft** : `/opt/minecraft/server/world*`
- 📁 **Configuration** : `server.properties`, `ops.json`, etc.
- 📁 **Plugins** : `/opt/minecraft/server/plugins/`
- 📁 **Logs** : `/opt/minecraft/logs/`

### Processus de sauvegarde

1. **Notification** : Message aux joueurs (30s avant)
2. **Arrêt propre** : Commande `/stop` via MCRCON  
3. **Sauvegarde** : Rsync optimisé vers `/opt/minecraft/backups/`
4. **Compression** : Archive tar.gz datée
5. **Redémarrage** : Serveur Minecraft
6. **Nettoyage** : Suppression sauvegardes expirées
7. **Log** : Enregistrement résultat

### Restauration manuelle

```bash
# Se connecter au serveur
ssh ansible@votre-serveur

# Lister les sauvegardes disponibles
ls -la /opt/minecraft/backups/daily/
ls -la /opt/minecraft/backups/weekly/
ls -la /opt/minecraft/backups/monthly/

# Restaurer une sauvegarde (exemple quotidienne)
sudo -u minecraft /opt/minecraft/tools/restore-backup.sh daily daily_backup_20241225_120000.tar.gz

# Le script demande confirmation et effectue :
# 1. Arrêt du serveur Minecraft
# 2. Sauvegarde des données actuelles  
# 3. Extraction et restauration
# 4. Redémarrage du serveur
```

### Sauvegarde manuelle d'urgence

```bash
# Depuis Ansible
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "/opt/minecraft/tools/backup-daily.sh"

# Depuis le serveur directement
sudo -u minecraft /opt/minecraft/tools/backup-daily.sh
```

## 🔄 Mises à jour

### Mise à jour automatique Spigot

Le système vérifie automatiquement les nouvelles versions et effectue la mise à jour sans interruption :

1. **Détection** : Comparaison version actuelle vs configurée
2. **Téléchargement** : BuildTools dans répertoire séparé
3. **Compilation** : Nouvelle version en parallèle  
4. **Tests** : Validation de la compilation
5. **Sauvegarde** : Version actuelle préservée
6. **Basculement** : Remplacement atomique
7. **Vérification** : Contrôle de fonctionnement

### Mise à jour manuelle

```bash
# Mettre à jour vers version spécifique
ansible-playbook playbooks/update-system.yml \
  -i inventories/production/hosts.yml \
  -e "minecraft_version=1.21.7"

# Forcer mise à jour complète
ansible-playbook playbooks/update-system.yml \
  -i inventories/production/hosts.yml \
  -e "force_update=true"

# Mise à jour système seulement
ansible-playbook playbooks/update-system.yml \
  -i inventories/production/hosts.yml \
  --tags system
```

### Rollback en cas de problème

```bash
# Automatique si la nouvelle version ne démarre pas
# Sinon, rollback manuel :

ssh ansible@votre-serveur
sudo systemctl stop minecraft

# Restaurer version précédente  
sudo -u minecraft mv /opt/minecraft/server /opt/minecraft/server.failed
sudo -u minecraft mv /opt/minecraft/server.old /opt/minecraft/server

sudo systemctl start minecraft
```

## 🎮 Administration

### MCRCON - Administration à distance

```bash
# Installation automatique dans /usr/local/bin/mcrcon
# Configuration automatique du RCON sur port 25575

# Connexion depuis le serveur
mcrcon -H localhost -P 25575 -p "votre_mot_de_passe_rcon"

# Commandes courantes une fois connecté
/list                          # Joueurs en ligne
/whitelist add NomJoueur       # Ajouter à la liste blanche  
/whitelist remove NomJoueur    # Retirer de la liste blanche
/op NomJoueur                  # Donner droits administrateur
/deop NomJoueur               # Retirer droits administrateur
/kick NomJoueur Raison        # Expulser un joueur
/ban NomJoueur Raison         # Bannir un joueur
/pardon NomJoueur             # Débannir un joueur
/say Message à tous           # Message serveur
/tell NomJoueur Message       # Message privé
/save-all                     # Forcer sauvegarde
/reload                       # Recharger configuration
/stop                         # Arrêter serveur
```

### Gestion des opérateurs

Configuration dans `inventories/production/group_vars/all.yml` :

```yaml
minecraft_ops:
  - name: "JoueurAdmin1"
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  # UUID Minecraft
    level: 4                                      # Niveau admin (1-4)
    bypass_player_limit: false                   # Ignore limite joueurs
  - name: "JoueurAdmin2" 
    uuid: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy"
    level: 4
    bypass_player_limit: true
```

> **Note** : Obtenez l'UUID d'un joueur sur https://mcuuid.net/

### Gestion des plugins

```bash
# Répertoire plugins : /opt/minecraft/server/plugins/

# Installer un plugin
wget -O /tmp/plugin.jar "https://url-du-plugin.jar"
sudo -u minecraft cp /tmp/plugin.jar /opt/minecraft/server/plugins/
sudo systemctl restart minecraft

# Script de gestion (auto-créé)
sudo -u minecraft /opt/minecraft/tools/manage-plugins.sh

# Lister plugins actifs via MCRCON
mcrcon -H localhost -P 25575 -p "mot_de_passe" "plugins"
```

### Configuration serveur

Fichier `/opt/minecraft/server/server.properties` généré automatiquement :

```properties
# Configuration générée par Ansible
server-port=25565
max-players=20
motd=Serveur Minecraft Ansible  
gamemode=survival
difficulty=normal
pvp=true
white-list=false
enable-rcon=true
rcon.port=25575
```

## 📊 Monitoring

### Vérifications automatiques

```bash
# Statut général du serveur
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "systemctl status minecraft"

# Utilisation mémoire
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "free -h"

# Espace disque
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "df -h /opt/minecraft"

# Joueurs connectés
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "mcrcon -H localhost -P 25575 -p 'password' 'list'"

# Logs récents
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "tail -20 /opt/minecraft/server/logs/latest.log"
```

### Logs importants

| Log | Localisation | Description |
|-----|--------------|-------------|
| **Minecraft** | `/opt/minecraft/server/logs/` | Logs du serveur de jeu |
| **Système** | `/var/log/syslog` | Logs système général |
| **SSH** | `/var/log/auth.log` | Tentatives connexion SSH |
| **Fail2ban** | `/var/log/fail2ban.log` | Bannissements automatiques |
| **Sauvegardes** | `/opt/minecraft/logs/backup-*.log` | Résultats sauvegardes |
| **UFW** | `/var/log/ufw.log` | Trafic réseau bloqué |

### Commandes de diagnostic

```bash
# Connexion au serveur
ssh ansible@votre-serveur

# Vérifier processus Minecraft
ps aux | grep minecraft
systemctl status minecraft

# Tester connectivité Minecraft  
telnet localhost 25565

# Vérifier RCON
mcrcon -H localhost -P 25575 -p "password" "version"

# Analyser performances
top -u minecraft
htop -u minecraft

# Vérifier espace disque mondes
du -sh /opt/minecraft/server/world*

# Taille des sauvegardes
du -sh /opt/minecraft/backups/*
```

## 🧪 Tests

### Tests automatiques (CI/CD)

Le pipeline Gitea effectue automatiquement :

- ✅ **Lint YAML** : Validation syntaxe fichiers
- ✅ **Ansible-lint** : Validation playbooks
- ✅ **Structure** : Vérification organisation fichiers  
- ✅ **Sécurité** : Scan secrets potentiels
- ✅ **Connectivité** : Test ping serveurs
- ✅ **Déploiement** : Test staging automatique

### Tests manuels

```bash
# Test connectivité inventaire
ansible all -i inventories/production/hosts.yml -m ping

# Validation syntaxe playbook
ansible-playbook --syntax-check playbooks/site.yml -i inventories/production/hosts.yml

# Test déploiement sans modification (dry-run)
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --check

# Test déploiement avec différences affichées
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --check --diff

# Test rôle spécifique
ansible-playbook playbooks/site.yml -i inventories/staging/hosts.yml --tags minecraft --check
```

### Tests de performance

```bash
# Test charge serveur
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "stress --cpu 4 --timeout 30s"

# Test mémoire disponible  
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "free -m | grep Available"

# Test vitesse disque
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "dd if=/dev/zero of=/tmp/testfile bs=1M count=100 conv=fdatasync"

# Test réseau Minecraft
ansible minecraft_servers -i inventories/production/hosts.yml -m shell -a "nc -zv localhost 25565"
```

## 🔧 Dépannage

### Problèmes courants

#### 🚫 Serveur Minecraft ne démarre pas

```bash
# 1. Vérifier les logs
journalctl -u minecraft -f
tail -100 /opt/minecraft/server/logs/latest.log

# 2. Vérifier Java
sudo -u minecraft java -version

# 3. Vérifier mémoire disponible
free -h

# 4. Tester démarrage manuel
sudo -u minecraft -s
cd /opt/minecraft/server
java -Xms2G -Xmx4G -jar spigot.jar nogui

# 5. Vérifier permissions
ls -la /opt/minecraft/server/
chown -R minecraft:minecraft /opt/minecraft/
```

#### 🔌 Problème de connectivité

```bash
# 1. Vérifier service actif
systemctl status minecraft

# 2. Vérifier port ouvert
netstat -tlnp | grep :25565
ss -tlnp | grep :25565  

# 3. Tester depuis serveur
telnet localhost 25565

# 4. Vérifier pare-feu
ufw status verbose
iptables -L -n

# 5. Tester RCON
mcrcon -H localhost -P 25575 -p "password" "version"
```

#### 💾 Problème de sauvegarde

```bash
# 1. Vérifier espace disque
df -h /opt/minecraft

# 2. Vérifier permissions sauvegardes
ls -la /opt/minecraft/backups/
chown -R minecraft:minecraft /opt/minecraft/backups/

# 3. Tester script sauvegarde
sudo -u minecraft /opt/minecraft/tools/backup-daily.sh

# 4. Vérifier cron jobs
crontab -u minecraft -l
systemctl status cron

# 5. Analyser logs sauvegardes
tail -50 /opt/minecraft/logs/backup-daily.log
```

#### 🔐 Problème SSH/Ansible

```bash
# 1. Test connexion SSH directe
ssh -v ansible@votre-serveur

# 2. Vérifier clé SSH
ssh-add -l
ls -la ~/.ssh/

# 3. Tester Ansible basique
ansible all -i inventories/production/hosts.yml -m ping -vvv

# 4. Vérifier configuration SSH serveur
sudo sshd -T | grep -E "(Port|PermitRoot|PasswordAuth)"

# 5. Analyser logs SSH
tail -50 /var/log/auth.log
```

#### 🔄 Problème de mise à jour

```bash
# 1. Vérifier compilation en cours
ps aux | grep BuildTools
ps aux | grep java

# 2. Vérifier espace disque pour compilation
df -h /opt/minecraft/sources

# 3. Analyser logs compilation Spigot
tail -100 /opt/minecraft/sources/BuildTools.log.txt

# 4. Vérifier version actuelle
cat /opt/minecraft/server/.version
/usr/local/bin/mcrcon -H localhost -P 25575 -p "password" "version"

# 5. Rollback manuel si nécessaire
sudo systemctl stop minecraft
sudo -u minecraft mv /opt/minecraft/server.old /opt/minecraft/server
sudo systemctl start minecraft
```

### Messages d'erreur fréquents

| Erreur | Cause probable | Solution |
|--------|----------------|----------|
| `Connection refused` | Service arrêté ou port fermé | Vérifier `systemctl status minecraft` |
| `Out of memory` | RAM insuffisante | Réduire `-Xmx` ou ajouter RAM serveur |
| `Permission denied` | Problème permissions fichiers | `chown -R minecraft:minecraft /opt/minecraft` |
| `EULA not accepted` | EULA non accepté | Vérifier `/opt/minecraft/server/eula.txt` |
| `Port already in use` | Port 25565 occupé | `netstat -tlnp \| grep 25565` |
| `Failed to bind to port` | Permissions réseau | Vérifier pare-feu et ports |

### Commandes de récupération d'urgence

```bash
# Redémarrage complet services
sudo systemctl restart minecraft
sudo systemctl restart ssh
sudo systemctl restart fail2ban
sudo systemctl restart ufw

# Nettoyage et récupération espace
sudo -u minecraft find /opt/minecraft/backups -name "*.tar.gz" -mtime +30 -delete
sudo -u minecraft find /opt/minecraft/server/logs -name "*.gz" -mtime +7 -delete

# Reset permissions complètes
sudo chown -R minecraft:minecraft /opt/minecraft/
sudo chmod -R 755 /opt/minecraft/
sudo chmod 644 /opt/minecraft/server/*.properties
sudo chmod 755 /opt/minecraft/tools/*.sh

# Vérification intégrité complète
ansible-playbook playbooks/site.yml -i inventories/production/hosts.yml --tags hardening --check
```

## 🤝 Contribution

### Comment contribuer

1. **Fork** du projet sur Gitea
2. **Clone** votre fork localement
3. **Branche** pour votre fonctionnalité : `git checkout -b feature/ma-fonctionnalite`
4. **Développement** avec tests sur staging
5. **Commit** avec messages clairs
6. **Push** vers votre fork
7. **Pull Request** vers la branche `develop`

### Standards de développement

- ✅ **Ansible-lint** : Pas de violations
- ✅ **YAML-lint** : Syntaxe respectée
- ✅ **Tests** : Fonctionnement sur staging vérifié
- ✅ **Documentation** : README et commentaires à jour
- ✅ **Sécurité** : Pas de secrets en dur
- ✅ **Idempotence** : Playbooks réexécutables sans effet de bord

### Règles de commit

```bash
# Format des messages
type(scope): description

# Types acceptés
feat: nouvelle fonctionnalité
fix: correction bug  
docs: documentation
style: formatage code
refactor: refactoring
test: ajout tests
chore: maintenance

# Exemples
feat(minecraft): add plugin auto-update
fix(backup): correct retention policy
docs(readme): update installation steps
```

### Tests requis avant PR

```bash
# Validation locale complète
yamllint .
ansible-lint playbooks/
ansible-playbook --syntax-check playbooks/site.yml -i inventories/staging/hosts.yml

# Test déploiement staging
ansible-playbook playbooks/site.yml -i inventories/staging/hosts.yml --check --diff
ansible-playbook playbooks/site.yml -i inventories/staging/hosts.yml

# Validation fonctionnelle
ansible minecraft_servers -i inventories/staging/hosts.yml -m shell -a "systemctl status minecraft"
mcrcon -H staging-server -P 25575 -p "password" "version"
```

---

## 📖 Documentation avancée

### Variables complètes par rôle

#### 🛡️ Rôle 01-server_hardening

```yaml
# SSH Configuration
ssh_port: 22                          # Port SSH (recommandé: changer)
ssh_permit_root_login: false          # Connexion root autorisée
ssh_password_authentication: false    # Authentification par mot de passe  
ssh_max_auth_tries: 3                # Tentatives de connexion max
ssh_client_alive_interval: 300        # Timeout inactivité (secondes)

# Firewall UFW
firewall_enabled: true                # Activation pare-feu
firewall_allowed_ports:               # Ports autorisés
  - "{{ ssh_port }}/tcp"
  - "25565/tcp"

# Fail2ban
fail2ban_enabled: true                # Protection anti-bruteforce
fail2ban_jail_ssh_maxretry: 3        # Tentatives avant ban
fail2ban_jail_ssh_bantime: 600       # Durée ban (secondes)

# Utilisateurs administrateurs
admin_users:
  - name: "admin1"
    key: "ssh-rsa AAAAB3NzaC1yc2E..."
    comment: "Administrateur principal"
```

#### ☕ Rôle 02-installation-java

```yaml
# Configuration Java
java_version: "17"                    # Version OpenJDK à installer
java_package: "openjdk-17-jdk"       # Package système
java_home: "/usr/lib/jvm/java-17-openjdk-amd64"  # Répertoire d'installation
required_java_version: "17"          # Version minimum requise pour Spigot
```

#### 🎮 Rôle 03-installation-minecraft

```yaml
# Utilisateurs et répertoires
minecraft_user: minecraft             # Utilisateur système dédié
minecraft_group: minecraft            # Groupe système dédié
minecraft_base_dir: /opt/minecraft    # Répertoire racine
minecraft_server_dir: /opt/minecraft/server     # Serveur Spigot
minecraft_tools_dir: /opt/minecraft/tools       # Outils (MCRCON, scripts)
minecraft_plugins_dir: /opt/minecraft/server/plugins  # Plugins

# Configuration serveur
minecraft_version: "1.21.6"          # Version Spigot
minecraft_memory_min: "2G"           # RAM minimum JVM
minecraft_memory_max: "4G"           # RAM maximum JVM
minecraft_port: 25565                 # Port serveur
minecraft_eula: true                  # Acceptation EULA automatique

# Propriétés serveur
server_name: "Minecraft Server"       # Nom serveur
server_motd: "Un serveur Minecraft"   # Message d'accueil
max_players: 20                       # Joueurs maximum simultanés
difficulty: "normal"                  # Difficulté (peaceful/easy/normal/hard)
gamemode: "survival"                  # Mode de jeu par défaut
pvp_enabled: true                     # PvP activé

# MCRCON (administration à distance)
mcrcon_version: "0.7.2"              # Version MCRCON
rcon_enabled: true                    # RCON activé
rcon_port: 25575                      # Port RCON
rcon_password: "changeme"             # Mot de passe RCON (À CHANGER!)

# Opérateurs Minecraft
minecraft_ops:
  - name: "JoueurAdmin"
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    level: 4                          # Niveau admin (1-4)
    bypass_player_limit: false       # Ignore limite joueurs
```

#### 💾 Rôle 04-backups

```yaml
# Configuration sauvegardes
backup_base_dir: /opt/minecraft/backups          # Répertoire sauvegardes
backup_daily_dir: /opt/minecraft/backups/daily   # Sauvegardes quotidiennes
backup_weekly_dir: /opt/minecraft/backups/weekly # Sauvegardes hebdomadaires
backup_monthly_dir: /opt/minecraft/backups/monthly # Sauvegardes mensuelles

# Rétention (en jours)
backup_retention_days: 7              # Quotidiennes: 7 jours
backup_retention_weeks: 4             # Hebdomadaires: 4 semaines (28 jours)
backup_retention_months: 6            # Mensuelles: 6 mois (180 jours)

# Planification cron
backup_daily_time: "02:00"            # Heure sauvegarde quotidienne
backup_weekly_time: "03:00"           # Heure sauvegarde hebdomadaire  
backup_weekly_day: "0"                # Jour semaine (0=dimanche)
backup_monthly_time: "04:00"          # Heure sauvegarde mensuelle
backup_monthly_day: "1"               # Jour mois (1=premier du mois)

# Options rsync
rsync_options: "-avz --delete"        # Options synchronisation

# Répertoires à sauvegarder
backup_sources:
  - "/opt/minecraft/server"           # Serveur complet
  - "/opt/minecraft/logs"             # Logs
```

#### 🔄 Rôle 05-update

```yaml
# Configuration mises à jour
update_check_ssh_keys: true          # Vérifier nouvelles clés SSH
update_check_system: true            # Vérifier mises à jour système  
update_check_spigot: true            # Vérifier nouvelles versions Spigot

# Fichiers et répertoires mise à jour Spigot
spigot_current_version_file: /opt/minecraft/server/.version    # Fichier version actuelle
spigot_new_version_dir: /opt/minecraft/new_version             # Répertoire nouvelle version
spigot_backup_dir: /opt/minecraft/version_backups              # Sauvegardes versions

# Système
system_update_auto: false            # Mise à jour système automatique
system_reboot_required_check: true   # Vérifier si reboot nécessaire
```

### Exemples d'inventaires avancés

#### Production multi-serveurs

```yaml
# inventories/production/hosts.yml
all:
  children:
    minecraft_servers:
      children:
        minecraft_primary:
          hosts:
            mc-prod-01:
              ansible_host: 10.0.1.10
              minecraft_memory_max: "8G"
              max_players: 50
              server_motd: "Serveur Principal"
        minecraft_secondary:
          hosts:
            mc-prod-02:
              ansible_host: 10.0.1.11
              minecraft_memory_max: "4G" 
              max_players: 25
              server_motd: "Serveur Secondaire"
            mc-prod-03:
              ansible_host: 10.0.1.12
              minecraft_memory_max: "4G"
              max_players: 25
              server_motd: "Serveur Test"
      vars:
        ansible_user: ansible
        ansible_ssh_private_key_file: ~/.ssh/minecraft_prod_rsa
        environment: production
```

#### Variables par groupe d'inventaire

```yaml
# inventories/production/group_vars/minecraft_primary.yml
minecraft_memory_min: "4G"
minecraft_memory_max: "8G"
max_players: 50
backup_retention_days: 30
backup_retention_weeks: 12
backup_retention_months: 12

# inventories/production/group_vars/minecraft_secondary.yml  
minecraft_memory_min: "2G"
minecraft_memory_max: "4G"
max_players: 25
backup_retention_days: 14
backup_retention_weeks: 8
backup_retention_months: 6
```

### Personnalisation avancée

#### Configuration server.properties complète

Le template `roles/03-installation-minecraft/templates/server.properties.j2` peut être étendu :

```properties
# Génération et ressources  
generate-structures={{ generate_structures | default(true) | ternary('true', 'false') }}
generator-settings={{ generator_settings | default('') }}
level-seed={{ level_seed | default('') }}
level-type={{ level_type | default('minecraft:normal') }}

# Performance
view-distance={{ view_distance | default(10) }}
simulation-distance={{ simulation_distance | default(10) }}
max-tick-time={{ max_tick_time | default(60000) }}
network-compression-threshold={{ network_compression_threshold | default(256) }}

# Fonctionnalités
allow-flight={{ allow_flight | default(false) | ternary('true', 'false') }}
allow-nether={{ allow_nether | default(true) | ternary('true', 'false') }}
enable-command-block={{ enable_command_block | default(false) | ternary('true', 'false') }}
spawn-protection={{ spawn_protection | default(16) }}

# Entités et mobs
spawn-animals={{ spawn_animals | default(true) | ternary('true', 'false') }}
spawn-monsters={{ spawn_monsters | default(true) | ternary('true', 'false') }}
spawn-npcs={{ spawn_npcs | default(true) | ternary('true', 'false') }}
max-entity-cramming={{ max_entity_cramming | default(24) }}
entity-broadcast-range-percentage={{ entity_broadcast_range_percentage | default(100) }}
```

#### Service systemd personnalisé

Template `roles/03-installation-minecraft/templates/minecraft.service.j2` étendu :

```ini
[Unit]
Description=Minecraft Spigot Server {{ minecraft_version }}
Documentation=https://www.spigotmc.org/
After=network.target
Wants=network.target

[Service]
Type=notify
User={{ minecraft_user }}
Group={{ minecraft_group }}
WorkingDirectory={{ minecraft_server_dir }}

# Configuration JVM optimisée
Environment="JAVA_OPTS=-Xms{{ minecraft_memory_min }} -Xmx{{ minecraft_memory_max }}"
Environment="SPIGOT_OPTS=--noconsole"

# Commandes
ExecStartPre=/bin/bash -c 'if [ ! -f {{ minecraft_server_dir }}/spigot.jar ]; then echo "Spigot JAR not found"; exit 1; fi'
ExecStart=/usr/bin/java $JAVA_OPTS -jar spigot.jar $SPIGOT_OPTS
ExecStop=/usr/local/bin/mcrcon -H 127.0.0.1 -P {{ rcon_port }} -p {{ rcon_password }} stop
ExecReload=/usr/local/bin/mcrcon -H 127.0.0.1 -P {{ rcon_port }} -p {{ rcon_password }} reload

# Gestion processus
TimeoutStartSec=600
TimeoutStopSec=600  
TimeoutReloadSec=60
Restart=on-failure
RestartSec=30
KillMode=mixed
KillSignal=SIGTERM

# Sécurité
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths={{ minecraft_base_dir }}
NoNewPrivileges=true

# Limites ressources  
LimitNOFILE=65536
LimitAS={{ (minecraft_memory_max | regex_replace('G', '') | int * 1.5 * 1024 * 1024 * 1024) | int }}

[Install]
WantedBy=multi-user.target
```

## 🔧 Outils et scripts utiles

### Script de monitoring personnalisé

```bash
#!/bin/bash
# Créer dans /opt/minecraft/tools/monitor.sh

echo "=== MONITORING SERVEUR MINECRAFT ==="
echo "Date: $(date)"
echo ""

# Statut service
echo "📊 SERVICE STATUS:"
systemctl is-active minecraft && echo "✅ Service: ACTIVE" || echo "❌ Service: INACTIVE"
systemctl is-enabled minecraft && echo "✅ Autostart: ENABLED" || echo "❌ Autostart: DISABLED"

# Processus
echo ""
echo "🔄 PROCESSES:"
ps aux | grep -E "(java.*spigot|PID)" | grep -v grep

# Mémoire
echo ""
echo "💾 MEMORY USAGE:"
free -h
echo ""
echo "Java Heap Usage:"
jstat -gc $(pgrep -f spigot) | tail -1

# Réseau
echo ""
echo "🌐 NETWORK:"
netstat -tlnp | grep -E "(25565|25575)"

# Joueurs connectés
echo ""
echo "👥 PLAYERS:"
/usr/local/bin/mcrcon -H localhost -P 25575 -p "${RCON_PASSWORD}" "list" 2>/dev/null || echo "❌ Cannot connect to RCON"

# Espace disque
echo ""
echo "💿 DISK USAGE:"
df -h /opt/minecraft | tail -1
echo ""
echo "World sizes:"
du -sh /opt/minecraft/server/world* 2>/dev/null

# Sauvegardes récentes
echo ""
echo "💾 RECENT BACKUPS:"
ls -lth /opt/minecraft/backups/daily/ | head -6

# Logs récents
echo ""
echo "📋 RECENT ERRORS:"
tail -100 /opt/minecraft/server/logs/latest.log | grep -i error | tail -5
```

### Script d'optimisation automatique

```bash
#!/bin/bash  
# Créer dans /opt/minecraft/tools/optimize.sh

echo "🚀 OPTIMISATION SERVEUR MINECRAFT"

# Nettoyage logs anciens
echo "🧹 Nettoyage logs..."
find /opt/minecraft/server/logs -name "*.gz" -mtime +7 -delete
find /opt/minecraft/logs -name "*.log" -mtime +30 -delete

# Optimisation base données monde
echo "🗃️ Optimisation monde..."
if systemctl is-active --quiet minecraft; then
    /usr/local/bin/mcrcon -H localhost -P 25575 -p "${RCON_PASSWORD}" "save-all"
    sleep 5
    /usr/local/bin/mcrcon -H localhost -P 25575 -p "${RCON_PASSWORD}" "save-off"
    
    # Compaction fichiers région (si NBT-tools installé)
    if command -v nbt &> /dev/null; then
        find /opt/minecraft/server/world*/region -name "*.mca" -exec nbt optimize {} \;
    fi
    
    /usr/local/bin/mcrcon -H localhost -P 25575 -p "${RCON_PASSWORD}" "save-on"
fi

# Nettoyage cache système
echo "🧽 Cache système..."
sync && echo 3 > /proc/sys/vm/drop_caches

# Défragmentation si nécessaire (ext4)
FRAGMENTATION=$(e4defrag -c /opt/minecraft/server/world 2>/dev/null | grep -o '[0-9.]*%' | head -1)
if [[ ${FRAGMENTATION%\%} -gt 30 ]]; then
    echo "📦 Défragmentation nécessaire (${FRAGMENTATION})"
    # e4defrag /opt/minecraft/server/world
fi

echo "✅ Optimisation terminée"
```

### Script de diagnostic complet

```bash
#!/bin/bash
# Créer dans /opt/minecraft/tools/diagnostic.sh

OUTPUT_FILE="/tmp/minecraft_diagnostic_$(date +%Y%m%d_%H%M%S).txt"

{
echo "🔍 DIAGNOSTIC COMPLET SERVEUR MINECRAFT"
echo "======================================"
echo "Date: $(date)"
echo "Hostname: $(hostname)"
echo "Uptime: $(uptime)"
echo ""

echo "🖥️ SYSTÈME"
echo "----------"
echo "OS: $(lsb_release -d | cut -f2)"
echo "Kernel: $(uname -r)"
echo "Architecture: $(uname -m)"
echo "CPU: $(nproc) cores - $(grep 'model name' /proc/cpuinfo | head -1 | cut -d: -f2 | xargs)"
echo "RAM Total: $(free -h | awk 'NR==2{print $2}')"
echo "RAM Used: $(free -h | awk 'NR==2{print $3}')"
echo "Load Average: $(cat /proc/loadavg)"
echo ""

echo "☕ JAVA"
echo "------"
/usr/bin/java -version 2>&1
echo "JAVA_HOME: $JAVA_HOME"
echo ""

echo "🎮 MINECRAFT"
echo "-----------"
echo "Status: $(systemctl is-active minecraft)"
echo "Enabled: $(systemctl is-enabled minecraft)"
echo "Version file: $(cat /opt/minecraft/server/.version 2>/dev/null || echo 'Not found')"
echo "Process:"
ps aux | grep -E "java.*spigot" | grep -v grep
echo ""
echo "Configuration:"
grep -E "(server-port|max-players|difficulty|gamemode)" /opt/minecraft/server/server.properties 2>/dev/null
echo ""

echo "🌐 RÉSEAU"
echo "--------"
echo "Ports ouverts:"
netstat -tlnp | grep -E "(25565|25575)"
echo ""
echo "Firewall status:"
ufw status 2>/dev/null || echo "UFW not available"
echo ""

echo "💾 STOCKAGE"
echo "----------"
df -h /opt/minecraft
echo ""
echo "Tailles répertoires:"
du -sh /opt/minecraft/server/world* 2>/dev/null
du -sh /opt/minecraft/backups/* 2>/dev/null
echo ""

echo "📋 LOGS RÉCENTS"
echo "--------------"
echo "Erreurs récentes (dernières 24h):"
find /opt/minecraft/server/logs -name "*.log" -mtime -1 -exec grep -i "error\|exception\|fatal" {} \; | tail -10
echo ""
echo "Messages système Minecraft:"
journalctl -u minecraft --since "1 hour ago" --no-pager | tail -10
echo ""

echo "👥 JOUEURS"
echo "---------"
if systemctl is-active --quiet minecraft; then
    /usr/local/bin/mcrcon -H localhost -P 25575 -p "${RCON_PASSWORD}" "list" 2>/dev/null || echo "RCON non accessible"
else
    echo "Serveur arrêté"
fi
echo ""

echo "🔒 SÉCURITÉ"
echo "----------"
echo "Fail2ban status:"
systemctl is-active fail2ban 2>/dev/null || echo "Fail2ban not running"
echo ""
echo "SSH tentatives récentes:"
grep "Failed password" /var/log/auth.log 2>/dev/null | tail -5 || echo "No failed attempts"
echo ""

echo "💾 SAUVEGARDES"
echo "-------------"
echo "Dernières sauvegardes:"
ls -lt /opt/minecraft/backups/daily/*.tar.gz 2>/dev/null | head -3 || echo "Aucune sauvegarde quotidienne"
echo ""
echo "Espace utilisé sauvegardes:"
du -sh /opt/minecraft/backups/* 2>/dev/null
echo ""

echo "🔧 MAINTENANCE"
echo "-------------"
echo "Dernière mise à jour système:"
stat -c %y /var/log/dpkg.log 2>/dev/null | head -1 || echo "Information non disponible"
echo ""
echo "Packages à mettre à jour:"
apt list --upgradable 2>/dev/null | wc -l || echo "APT non disponible"

} > "$OUTPUT_FILE"

echo "📊 Diagnostic complet généré: $OUTPUT_FILE"
echo "📤 Pour envoyer le diagnostic:"
echo "   cat $OUTPUT_FILE | pastebinit  # ou autre service"
echo "   scp $OUTPUT_FILE admin@monitoring-server:/tmp/"
```

## 📚 Resources et références

### Documentation officielle

- **[Spigot Wiki](https://www.spigotmc.org/wiki/)** - Documentation complète Spigot
- **[Ansible Documentation](https://docs.ansible.com/)** - Documentation officielle Ansible  
- **[Java Performance Guide](https://docs.oracle.com/en/java/javase/17/gctuning/)** - Optimisation JVM
- **[Ubuntu Server Guide](https://ubuntu.com/server/docs)** - Guide serveur Ubuntu
- **[Debian Administrator's Handbook](https://debian-handbook.info/)** - Guide administrateur Debian

### Outils utiles

- **[MCRCON](https://github.com/Tiiffi/mcrcon)** - Client RCON pour Minecraft
- **[NBT Explorer](https://github.com/jaquadro/NBTExplorer)** - Éditeur de fichiers NBT Minecraft
- **[Minecraft Server Status](https://mcstatus.io/)** - Vérification statut serveur
- **[UUID Lookup](https://mcuuid.net/)** - Recherche UUID joueurs Minecraft
- **[Ansible Lint](https://ansible.readthedocs.io/projects/lint/)** - Linting playbooks Ansible

### Communauté et support

- **[SpigotMC Forums](https://www.spigotmc.org/)** - Communauté Spigot
- **[r/admincraft](https://reddit.com/r/admincraft)** - Reddit administration serveurs Minecraft  
- **[Ansible Community](https://forum.ansible.com/)** - Forum communauté Ansible
- **[Stack Overflow](https://stackoverflow.com/questions/tagged/ansible+minecraft)** - Questions techniques

### Monitoring et métriques

- **[Prometheus](https://prometheus.io/)** - Système de monitoring
- **[Grafana](https://grafana.com/)** - Visualisation de métriques
- **[minecraft-prometheus-exporter](https://github.com/sladkoff/minecraft-prometheus-exporter)** - Métriques Minecraft
- **[Node Exporter](https://github.com/prometheus/node_exporter)** - Métriques système

## 📄 Changelog et versions

### Version 1.0.0 (2024-12-25)

#### ✨ Nouvelles fonctionnalités
- Installation automatisée complète de Spigot 1.21.6
- Système de durcissement sécuritaire multicouche
- Sauvegardes automatiques multiples (quotidien/hebdomadaire/mensuel)
- Système de mise à jour continue sans interruption
- CI/CD pipeline intégré avec Gitea
- Support multi-environnement (staging/production)

#### 🛡️ Sécurité
- Configuration SSH durcie (clés uniquement, fail2ban)
- Pare-feu UFW avec règles minimales
- Utilisateur système dédié avec isolation
- Gestion automatisée des clés SSH administrateurs
- Mises à jour sécuritaires automatiques

#### 🎮 Minecraft
- Compilation automatique Spigot avec BuildTools
- MCRCON intégré pour administration à distance
- Service systemd optimisé avec restart automatique
- Gestion des opérateurs et configuration serveur
- Support plugins avec répertoire dédié
- Rotation automatique des logs

#### 💾 Sauvegarde et restauration
- Scripts rsync optimisés avec compression
- Rétention configurable par type de sauvegarde
- Scripts de restauration automatisés
- Sauvegarde des configurations et mondes

#### 🔄 Maintenance
- Détection automatique nouvelles versions Spigot
- Compilation et tests en environnement séparé
- Basculement atomique avec rollback automatique
- Mise à jour clés SSH et système

#### 📖 Documentation
- README complet avec exemples pratiques
- Guide de dépannage détaillé
- Scripts d'administration et monitoring
- Templates de configuration avancés

### Roadmap futures versions

#### Version 1.1.0 (Planifiée)
- [ ] Support BungeeCord multi-serveurs
- [ ] Monitoring Prometheus/Grafana intégré
- [ ] Gestion automatique plugins populaires
- [ ] Support Docker/containerisation
- [ ] Alerting Discord/Slack

#### Version 1.2.0 (Planifiée)  
- [ ] Support MySQL/PostgreSQL externe
- [ ] Load balancer intégré
- [ ] Clustering multi-serveurs
- [ ] API REST pour administration
- [ ] Interface web d'administration

---

## 🏁 Conclusion

Ce projet Ansible fournit une solution **complète, sécurisée et production-ready** pour déployer et maintenir des serveurs Minecraft Spigot à grande échelle.

### 🎯 Ce que vous obtenez
- ⚡ **Déploiement en 30 minutes** au lieu de plusieurs heures manuelles
- 🛡️ **Sécurité niveau entreprise** avec durcissement complet
- 🔄 **Maintenance automatisée** avec mises à jour sans interruption
- 💾 **Sauvegardes fiables** avec restauration rapide
- 📊 **Monitoring intégré** pour supervision proactive
- 📖 **Documentation exhaustive** pour équipe technique

### 🚀 Prêt pour la production
Ce playbook a été conçu selon les **meilleures pratiques DevOps** et est immédiatement utilisable en production pour des serveurs supportant **des centaines de joueurs simultanés**.

**🎮 Votre infrastructure Minecraft sera opérationnelle, sécurisée et maintenable dès aujourd'hui !**

---

*Développé avec ❤️ pour la communauté Minecraft*