# Minecraft Spigot Server - Ansible Deployment

Ce projet Ansible permet de déployer automatiquement un serveur Minecraft Spigot complet avec hardening de sécurité, sauvegarde automatisée et gestion des mises à jour.

## 🚀 Fonctionnalités

### ✅ Rôles disponibles
- **01-server_hardening** : Durcissement sécuritaire du serveur
- **02-installation-java** : Installation automatique de Java OpenJDK
- **03-installation-minecraft** : Déploiement complet du serveur Spigot
- **04-backups** : Système de sauvegarde automatisé
- **05-update** : Gestion des mises à jour automatisées

### 🔧 Composants installés
- **Spigot 1.21.6** : Serveur Minecraft optimisé
- **mcrcon** : Administration à distance via RCON
- **Java 21** : Version optimale pour Spigot
- **Fail2Ban** : Protection contre les attaques par force brute
- **UFW** : Pare-feu simplifié
- **Logrotate** : Rotation automatique des logs

## 📁 Structure du projet

```
minecraft-spigot-ansible/
├── README.md                    # Documentation principale
├── site.yml                     # Playbook principal
├── ansible.cfg                  # Configuration Ansible
├── inventories/                 # Inventaires des serveurs
│   ├── production/              # Environnement de production
│   └── staging/                 # Environnement de test
├── roles/                       # Rôles Ansible
│   ├── 01-server_hardening/     # Sécurisation du serveur
│   ├── 02-installation-java/    # Installation Java
│   ├── 03-installation-minecraft/ # Déploiement Minecraft
│   ├── 04-backups/              # Système de sauvegarde
│   └── 05-update/               # Gestion des mises à jour
└── .gitea/workflows/            # CI/CD Gitea
    ├── lint.yml                 # Tests et validation
    └── deploy.yml               # Déploiement automatique
```

## ⚙️ Configuration requise

### Serveur cible
- **OS** : Debian 10/11/12/13 ou Ubuntu LTS
- **RAM** : Minimum 2GB (4GB recommandés)
- **Stockage** : 20GB minimum
- **Réseau** : Accès Internet pour téléchargements

### Serveur de contrôle
- **Ansible** : Version 2.9 ou supérieure
- **Python** : 3.8 ou supérieure
- **SSH** : Accès par clé aux serveurs cibles

## 🛠️ Installation et configuration

### 1. Préparation de l'environnement

```bash
# Cloner le repository
git clone https://your-gitea-instance.com/your-repo/minecraft-spigot-ansible.git
cd minecraft-spigot-ansible

# Installer Ansible (si nécessaire)
pip install ansible ansible-lint yamllint

# Configurer les clés SSH
ssh-keygen -t ed25519 -f ~/.ssh/ansible_key
ssh-copy-id -i ~/.ssh/ansible_key.pub ansible@your-server-ip
```

### 2. Configuration des inventaires

#### Production (`inventories/production/hosts.yml`)
```yaml
all:
  children:
    minecraft_servers:
      hosts:
        minecraft-prod-01:
          ansible_host: YOUR_PROD_IP
          ansible_user: ansible
```

#### Variables globales (`inventories/production/group_vars/minecraft_servers.yml`)
```yaml
minecraft_version: "1.21.6"
minecraft_memory_min: "1G"
minecraft_memory_max: "4G"
minecraft_rcon_password: "your-secure-password"
```

### 3. Configuration des secrets

Créer un fichier vault pour les mots de passe :
```bash
ansible-vault create inventories/production/group_vars/vault.yml
```

Contenu du vault :
```yaml
vault_minecraft_rcon_password: "your-secure-rcon-password"
vault_mysql_password: "your-mysql-password"
```

## 🚀 Déploiement

### Déploiement manuel

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

# Déploiement complet
ansible-playbook -i inventories/production/hosts.yml site.yml --ask-vault-pass

# Déploiement par rôle spécifique
ansible-playbook -i inventories/production/hosts.yml site.yml --tags "minecraft" --ask-vault-pass
```

### Déploiement par tags

```bash
# Sécurisation uniquement
ansible-playbook site.yml --tags "hardening"

# Installation Java uniquement
ansible-playbook site.yml --tags "java"

# Configuration Minecraft uniquement
ansible-playbook site.yml --tags "minecraft"

# Configuration des sauvegardes uniquement
ansible-playbook site.yml --tags "backup"

# Mises à jour uniquement
ansible-playbook site.yml --tags "update"
```

## 🔐 Sécurité

### Hardening automatique inclus
- **SSH** : Configuration sécurisée (clés uniquement, port personnalisable)
- **Firewall** : UFW avec règles restrictives
- **Fail2Ban** : Protection anti-bruteforce
- **Permissions** : Utilisateur dédié minecraft
- **Logs** : Rotation automatique et surveillance

### Ports ouverts par défaut
- **22/tcp** : SSH (configurable)
- **25565/tcp** : Minecraft
- **25575/tcp** : RCON (localhost uniquement)

## 💾 Système de sauvegarde

### Types de sauvegardes
- **Quotidienne** : 2h00, rétention 7 jours
- **Hebdomadaire** : Dimanche 3h00, rétention 4 semaines  
- **Mensuelle** : 1er du mois 4h00, rétention 6 mois

### Localisation des sauvegardes
```
/opt/minecraft/backups/
├── daily/      # Sauvegardes quotidiennes
├── weekly/     # Sauvegardes hebdomadaires
├── monthly/    # Sauvegardes mensuelles
└── scripts/    # Scripts de sauvegarde
```

### Restauration
```bash
# Lister les sauvegardes disponibles
sudo -u minecraft /opt/minecraft/backups/scripts/restore.sh

# Restaurer une sauvegarde spécifique
sudo -u minecraft /opt/minecraft/backups/scripts/restore.sh daily 20241201_020000
```

## 🔄 Gestion des mises à jour

### Mises à jour automatiques
Le rôle `05-update` vérifie et applique automatiquement :
- **Clés SSH** : Nouvelles clés autorisées
- **Système** : Paquets Debian/Ubuntu  
- **Spigot** : Nouvelles versions disponibles

### Processus de mise à jour Spigot
1. Détection nouvelle version
2. Téléchargement BuildTools
3. Compilation en parallèle
4. Tests de la nouvelle version
5. Basculement sans interruption
6. Nettoyage des anciennes versions

## 🎮 Administration du serveur

### Commandes utiles

```bash
# Statut du service
systemctl status minecraft

# Logs en temps réel
journalctl -u minecraft -f

# Console RCON
/opt/minecraft/tools/mcrcon -H 127.0.0.1 -P 25575 -p your-password

# Commandes RCON utiles
/opt/minecraft/tools/mcrcon -H 127.0.0.1 -P 25575 -p your-password "say Serveur en maintenance"
/opt/minecraft/tools/mcrcon -H 127.0.0.1 -P 25575 -p your-password "stop"
```

### Structure des fichiers Minecraft

```
/opt/minecraft/
├── server/          # Serveur actif
│   ├── spigot.jar   # Exécutable Spigot
│   ├── plugins/     # Plugins installés
│   ├── worlds/      # Mondes Minecraft
│   ├── logs/        # Logs du serveur
│   └── ops.json     # Administrateurs
├── sources/         # Sources et BuildTools
├── tools/          # Outils (mcrcon, scripts)
└── backups/        # Sauvegardes automatiques
```

### Configuration des administrateurs

Éditer le fichier `inventories/production/group_vars/minecraft_servers.yml` :

```yaml
minecraft_ops:
  - name: "admin_username"
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    level: 4
    bypass_limit: true
  - name: "moderator_username"
    uuid: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
    level: 3
    bypass_limit: false
```

## 🔧 CI/CD avec Gitea

### Configuration des secrets Gitea

Dans les paramètres de votre repository Gitea, configurez ces secrets :

- `ANSIBLE_SSH_KEY` : Clé privée SSH pour l'utilisateur ansible
- `ANSIBLE_VAULT_PASSWORD` : Mot de passe du vault Ansible
- `ANSIBLE_HOST` : IP du serveur pour ssh-keyscan

### Workflows disponibles

#### Lint et validation (`.gitea/workflows/lint.yml`)
- **Déclenchement** : Push sur main/develop, Pull Requests
- **Actions** : 
  - Validation YAML avec yamllint
  - Validation Ansible avec ansible-lint
  - Test des inventaires

#### Déploiement automatique (`.gitea/workflows/deploy.yml`)
- **Déclenchement** : Push sur main, déclenchement manuel
- **Environnements** : staging, production
- **Actions** :
  - Déploiement automatique selon la branche
  - Utilisation des secrets sécurisés

### Stratégie de déploiement

```
develop branch    → staging environment
main branch      → production environment
manual trigger   → choice of environment
```

## 📊 Monitoring et logs

### Logs système
```bash
# Logs du service Minecraft
journalctl -u minecraft -f --since "1 hour ago"

# Logs de sécurité
tail -f /var/log/auth.log

# Logs Fail2Ban
tail -f /var/log/fail2ban.log

# Logs UFW
tail -f /var/log/ufw.log
```

### Logs Minecraft
```bash
# Log actuel du serveur
tail -f /opt/minecraft/server/logs/latest.log

# Logs archivés
ls -la /opt/minecraft/server/logs/

# Recherche dans les logs
grep "ERROR" /opt/minecraft/server/logs/latest.log
```

### Métriques système
```bash
# Utilisation mémoire Java
ps aux | grep java

# Espace disque
df -h /opt/minecraft

# Processus réseau
netstat -tlnp | grep :25565
```

## 🔍 Dépannage

### Problèmes courants

#### Le serveur ne démarre pas
```bash
# Vérifier le statut
systemctl status minecraft

# Vérifier les logs
journalctl -u minecraft -n 50

# Vérifier la configuration
sudo -u minecraft java -jar /opt/minecraft/server/spigot.jar --help
```

#### Problèmes de mémoire
```bash
# Ajuster dans group_vars/minecraft_servers.yml
minecraft_memory_min: "2G"
minecraft_memory_max: "6G"

# Redéployer
ansible-playbook site.yml --tags "minecraft"
```

#### Problèmes de connectivité
```bash
# Vérifier le pare-feu
ufw status verbose

# Tester la connectivité
telnet server-ip 25565

# Vérifier RCON
/opt/minecraft/tools/mcrcon -H 127.0.0.1 -P 25575 -p password "list"
```

#### Erreurs de compilation Spigot
```bash
# Nettoyer le cache de compilation
rm -rf /opt/minecraft/sources/build_*

# Relancer la compilation
ansible-playbook site.yml --tags "compile" -v
```

### Mode debug

Pour activer le mode debug lors du déploiement :

```bash
ansible-playbook site.yml -vvv
```

## 🔄 Maintenance

### Maintenance programmée

```bash
# Script de maintenance (à créer)
#!/bin/bash
# Arrêter le serveur
systemctl stop minecraft

# Effectuer la maintenance
# ...

# Redémarrer le serveur
systemctl start minecraft
```

### Mise à jour manuelle

```bash
# Mise à jour du système uniquement
ansible-playbook site.yml --tags "system-update"

# Mise à jour Spigot uniquement
ansible-playbook site.yml --tags "spigot-update"

# Mise à jour complète
ansible-playbook site.yml --tags "update"
```

### Nettoyage

```bash
# Nettoyer les anciens logs
find /opt/minecraft/server/logs/ -name "*.log.gz" -mtime +30 -delete

# Nettoyer les anciennes sauvegardes (automatique via scripts)
# Les scripts de sauvegarde incluent le nettoyage automatique

# Nettoyer les anciennes versions compilées
rm -rf /opt/minecraft/sources/build_*
```

## 📝 Personnalisation

### Ajout de plugins

Éditer `inventories/production/group_vars/minecraft_servers.yml` :

```yaml
minecraft_plugins:
  - name: "EssentialsX-2.21.0.jar"
    url: "https://github.com/EssentialsX/Essentials/releases/download/2.21.0/EssentialsX-2.21.0.jar"
  - name: "WorldEdit-7.3.0.jar"
    url: "https://dev.bukkit.org/projects/worldedit/files/latest"
```

### Configuration serveur personnalisée

Éditer les templates dans `roles/03-installation-minecraft/templates/` :

- `server.properties.j2` : Propriétés principales
- `spigot.yml.j2` : Configuration Spigot
- `bukkit.yml.j2` : Configuration Bukkit

### Ajout de nouveaux environnements

1. Créer le répertoire d'inventaire :
```bash
mkdir -p inventories/preprod/{group_vars}
```

2. Créer les fichiers de configuration :
```bash
cp inventories/staging/* inventories/preprod/
```

3. Adapter la configuration dans `group_vars/`

## 🤝 Contribution

### Développement local

```bash
# Cloner le projet
git clone https://your-gitea-instance.com/your-repo/minecraft-spigot-ansible.git
cd minecraft-spigot-ansible

# Installer les dépendances de développement
pip install ansible ansible-lint yamllint pre-commit

# Installer les hooks pre-commit
pre-commit install

# Tester les modifications
ansible-lint
yamllint .
```

### Standards de code

- **YAML** : Indentation 2 espaces
- **Ansible** : Utilisation des modules officiels
- **Templates** : Variables Jinja2 documentées
- **Tags** : Cohérence dans le nommage
- **Idempotence** : Tous les tasks doivent être idempotents

### Processus de contribution

1. **Fork** du projet
2. **Branche** de fonctionnalité : `feature/nouvelle-fonctionnalite`
3. **Commits** descriptifs et atomiques
4. **Tests** : Validation avec ansible-lint
5. **Pull Request** avec description détaillée

## 📚 Ressources

### Documentation Ansible
- [Ansible Documentation](https://docs.ansible.com/)
- [Ansible Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)

### Documentation Minecraft
- [Spigot Documentation](https://www.spigotmc.org/wiki/)
- [Paper Documentation](https://docs.papermc.io/)

### Sécurité
- [CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks/)
- [ANSSI Hardening Guide](https://www.ssi.gouv.fr/)

## 📞 Support

### Rapporter un problème

Utilisez le système d'issues de Gitea avec :
- **Titre** descriptif
- **Environnement** (OS, version Ansible, etc.)
- **Logs** d'erreur
- **Steps to reproduce**

### Contact

- **Issues** : Système d'issues Gitea
- **Discussions** : Forum interne de l'équipe
- **Documentation** : Wiki du projet

## 📄 Licence

Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails.

---

**Version du playbook** : 1.0.0
**Compatible avec** : Debian 10/11/12/13, Ubuntu 18.04/20.04/22.04
**Version Minecraft supportée** : 1.21.6
**Dernière mise à jour** : Décembre 2024