Déploiement automatisé avec Ansible
Ansible permet un déploiement entièrement automatisé de ClientXCMS, de l'installation des prérequis jusqu'à la mise en production. Cette méthode est recommandée pour les environnements de production et les déploiements multi-serveurs.
Prérequis
Sur la machine de contrôle (votre ordinateur)
- Ansible 2.9+ installé
- Git pour cloner le playbook
- Accès SSH aux serveurs cibles
Sur les serveurs cibles
- Ubuntu 22.04+, Debian 11+ ou Rocky/AlmaLinux 9+
- Accès root ou utilisateur avec privilèges sudo
- Connexion internet pour télécharger les paquets
Installation du playbook
1. Cloner le dépôt Ansible
git clone https://github.com/ClientXCMS/ansible.git clientxcms-ansible
cd clientxcms-ansible
2. Configuration de l'inventaire
Éditez le fichier d'inventaire selon votre environnement :
Production
# inventory/production.yml
[clientxcms]
serveur1.example.com ansible_host=192.168.1.100 ansible_user=root
serveur2.example.com ansible_host=192.168.1.101 ansible_user=root
[clientxcms:vars]
environment_name=production
Développement
# inventory/development.yml
[clientxcms]
dev.local ansible_host=192.168.1.50 ansible_user=root
[clientxcms:vars]
environment_name=development
Déploiement
Nouveau déploiement production
Pour un premier déploiement sur un serveur de production :
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "webserver=nginx" \
-e "clientxcms_domain=manager.example.com" \
-e "[email protected]" \
-e "clientxcms_oauth_client_id=VOTRE_CLIENT_ID" \
-e "clientxcms_oauth_client_secret=VOTRE_CLIENT_SECRET"
Déploiement développement
Pour un environnement de développement ou de test :
ansible-playbook -i inventory/development.yml playbooks/deploy-clientxcms.yml \
-e "webserver=nginx"
Choix du serveur web
Le playbook prend en charge deux serveurs web :
# Nginx (recommandé pour la production)
-e "webserver=nginx"
# Apache (compatible hébergement partagé)
-e "webserver=apache"
Variables de configuration
Variables obligatoires (production)
| Variable | Description | Exemple |
|---|---|---|
webserver | Serveur web à installer | nginx ou apache |
clientxcms_domain | Nom de domaine | manager.example.com |
clientxcms_admin_email | Email administrateur | [email protected] |
clientxcms_oauth_client_id | ID OAuth ClientXCMS | 9707826860385 |
clientxcms_oauth_client_secret | Secret OAuth | votre_secret |
Variables optionnelles
| Variable | Description | Défaut |
|---|---|---|
clientxcms_force_reinstall | Forcer la réinstallation | false |
clientxcms_ssl_enabled | Activer SSL/Let's Encrypt | true (prod), false (dev) |
clientxcms_repo_branch | Branche Git à déployer | master |
Obtenir les identifiants OAuth
Les identifiants OAuth sont requis en production et s'obtiennent depuis votre compte ClientXCMS :
- Connectez-vous sur clientxcms.com
- Accédez à Mon Compte > Mes services > Gérer le service > Onglet Service
- Section Authentification
- Notez le OAuth Client ID et le OAuth Secret
Composants installés
Le playbook Ansible installe et configure automatiquement :
Infrastructure système
- PHP 8.3 avec toutes les extensions requises
- MariaDB 10.11+ (base de données)
- Nginx ou Apache (serveur web)
- PHP-FPM (gestionnaire de processus)
Sécurité
- Certificats SSL (Let's Encrypt en production)
- Pare-feu configuré (ports 22, 80, 443)
- Permissions et utilisateurs sécurisés
- Configuration PHP durcie
ClientXCMS
- Code source depuis Git
- Dépendances Composer et NPM
- Configuration
.envautomatique - Base de données initialisée
- Tâches cron et queues Laravel
Gestion des mises à jour
Mise à jour d'une instance spécifique
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "clientxcms_update_mode=true" \
-e "clientxcms_domain=manager.example.com"
Mise à jour de toutes les instances
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "clientxcms_update_mode=true"
Processus de mise à jour
- Backup automatique (fichiers + base de données)
- Mode maintenance (
php artisan down) - Récupération du code source Git
- Installation des dépendances
- Migrations de base de données
- Nettoyage des caches
- Compilation des assets
- Sortie de maintenance (
php artisan up)
Backups automatiques
Chaque mise à jour génère un backup complet dans /var/backups/clientxcms/[domain]/[timestamp]/
Gestion des erreurs et rollback
En cas d'échec de mise à jour
Si une mise à jour échoue, le playbook affiche la commande de rollback exacte :
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "clientxcms_rollback_mode=true" \
-e "clientxcms_domain=manager.example.com" \
-e "clientxcms_rollback_timestamp=1709123456"
Processus de rollback
- Vérification de l'existence du backup
- Affichage des détails (date, commit git)
- Confirmation utilisateur
- Restauration des fichiers (préserve
.env) - Restauration de la base de données
- Nettoyage des caches
Options avancées
Mode simulation (dry-run)
Testez le déploiement sans appliquer les modifications :
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
--check \
-e "webserver=nginx"
Mode verbeux (debug)
Affichez plus d'informations lors de l'exécution :
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-vvv \
-e "webserver=nginx"
Utilisation de tags
Exécutez uniquement certaines parties du playbook :
# Installation des prérequis uniquement
--tags prerequisites
# Déploiement ClientXCMS uniquement
--tags clientxcms
# Mode mise à jour uniquement
--tags update
Structure des fichiers de backup
/var/backups/clientxcms/
├── manager.example.com/
│ ├── 1709123456/
│ │ ├── files.tar.gz # Archive complète des fichiers
│ │ ├── database.sql # Dump MySQL/MariaDB
│ │ └── metadata.json # Métadonnées (date, commit, etc.)
│ └── 1709234567/
│ └── ...
└── autre-domaine.com/
└── ...
Exemples complets
Déploiement production multi-domaines
# Premier domaine
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "webserver=nginx" \
-e "clientxcms_domain=client1.example.com" \
-e "[email protected]" \
-e "clientxcms_oauth_client_id=8387752805262" \
-e "clientxcms_oauth_client_secret=SECRET1"
# Deuxième domaine sur le même serveur
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "webserver=nginx" \
-e "clientxcms_domain=client2.example.com" \
-e "[email protected]" \
-e "clientxcms_oauth_client_id=9274638291847" \
-e "clientxcms_oauth_client_secret=SECRET2"
Mise à jour planifiée avec rétention personnalisée
# Garder 10 backups au lieu de 5 par défaut
ansible-playbook -i inventory/production.yml playbooks/deploy-clientxcms.yml \
-e "clientxcms_update_mode=true" \
-e "clientxcms_backup_retention=10"
Déploiement avec branche spécifique
# Déployer la branche develop pour les tests
ansible-playbook -i inventory/staging.yml playbooks/deploy-clientxcms.yml \
-e "webserver=nginx" \
-e "clientxcms_domain=staging.example.com" \
-e "clientxcms_repo_branch=develop"
Détection automatique des instances
Le playbook détecte automatiquement les instances ClientXCMS existantes via :
- Scan de
/var/www/pour les répertoires - Vérification du fichier marqueur
storage/installed - Validation de la présence du fichier
artisan
Si aucun domaine spécifique n'est fourni, toutes les instances détectées seront mises à jour.
Bonnes pratiques
Sécurité
- Ne pas commiter les secrets OAuth dans Git ou bien penser à utiliser Vault pour les secrets et informations sensibles à chiffrer.
- Utiliser un utilisateur dédié pour Ansible
- Tester d'abord sur un environnement de staging
- Vérifier les backups régulièrement
Performance
- Utiliser Nginx + PHP-FPM pour la production
- Activer OPcache PHP (fait automatiquement)
- Configurer MariaDB selon votre charge
- Monitorer les ressources serveur avec Grafana (prévu dans une prochaine mise à jour de la playbook)
Maintenance
- Planifier les mises à jour pendant les créneaux de faible trafic
- Conserver les backups selon votre politique de rétention
- Tester les rollbacks sur un environnement de test
- Documenter vos configurations spécifiques
Recommandation
Pour un déploiement professionnel, utilisez Ansible avec un serveur de contrôle dédié et des clés SSH plutôt que des mots de passe.
Support et dépannage
L’équipe de ClientXCMS ne fournit aucun support externe concernant l’utilisation d’Ansible et des playbooks fournis.
Nous restons toutefois disponibles sur les canaux communautaires, mais cette assistance n’entre pas dans l’offre de support officielle.
Logs disponibles
- Ansible :
/var/log/ansible.log - ClientXCMS :
storage/logs/laravel.log - Nginx :
/var/log/nginx/ - Apache :
/var/log/apache2/ou/var/log/httpd/
Résolution de problèmes courants
Erreur de connexion SSH
# Vérifiez la connectivité
ansible -i inventory/production.yml all -m ping
Erreur d’authentification OAuth
- Vérifiez vos identifiants sur clientxcms.com
- Assurez-vous que l’application OAuth est bien active
Échec du déploiement SSL
- Vérifiez que le domaine pointe correctement vers le serveur
- Attendez la propagation DNS (jusqu’à 48 h)
- N’activez pas le proxy Cloudflare lors de la génération des certificats
Ressources d’aide
Pour obtenir de l’aide supplémentaire, consultez :