Automatiser le déploiement dans cPanel avec le fichier .cpanel.yml

L'interface Git de cPanel ne se contente pas de stocker vos dépôts : elle peut aussi mettre en production les modifications (faire le déploiement) en exécutant les tâches que vous définissez dans le fichier .cpanel.yml.

Si vous cherchez un cas complet, pas à pas, voyez déploiement automatique depuis GitHub vers cPanel avec Laravel. Si vous préférez ne pas le configurer à la main, Deploy+ s'en charge depuis l'espace client.

Le fichier .cpanel.yml

C'est un fichier texte au format YAML qui contient la liste des commandes exécutées à chaque déploiement : copier des fichiers vers le dossier public, installer des dépendances, vider des caches… tout ce que vous pouvez faire avec une commande ou un script.

Créez-le à la racine du dépôt, avec ce nom exact (avec le point devant), et faites-en un commit. Sa structure est la suivante :

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/
    - /bin/cp index.html $DEPLOYPATH
    - /bin/cp style.css $DEPLOYPATH

• Les trois premières lignes sont fixes : ---, deployment: et, en dessous, tasks:.
• Chaque tâche est une ligne qui commence par - (tiret et espace), avec la même indentation.
• export DEPLOYPATH=... enregistre le dossier de destination dans une variable, pour ne pas le répéter à chaque ligne.
• Les /bin/cp copient index.html et style.css du dépôt vers le dossier public. Le site est ainsi mis à jour avec les modifications.

Remplacez usuario par votre utilisateur cPanel. cp écrase les fichiers qui existent déjà sous ce nom à destination.

Copier tout le site avec rsync

Pour ne pas procéder fichier par fichier, copiez tout le contenu du dépôt sauf ce qui ne doit pas être publié :

---
deployment:
  tasks:
    - export DEPLOYPATH=/home/usuario/public_html/
    - /bin/rsync -a --exclude='.git' --exclude='.cpanel.yml' ./ $DEPLOYPATH

rsync ne supprime pas à destination les fichiers qui ne sont plus dans le dépôt. Vous pouvez ajouter --delete pour qu'il le fasse, mais seulement si ce dossier ne contient que ce qui vient du dépôt : il supprimerait aussi les images envoyées, les caches ou le .htaccess s'ils n'y figurent pas.

Tâches d'une application PHP

Vous pouvez exécuter n'importe quel outil avec son chemin complet. Par exemple, installer les dépendances avec Composer et vider le cache d'une application Laravel :

---
deployment:
  tasks:
    - cd /home/usuario/repositories/proyecto && /usr/local/bin/php /opt/cpanel/composer/bin/composer install --no-dev --optimize-autoloader
    - cd /home/usuario/repositories/proyecto && /usr/local/bin/php artisan config:cache

Utilisez toujours des chemins absolus : les tâches ne chargent pas votre configuration de terminal. Si vous ne savez pas où se trouve un programme, exécutez which php (ou celui concerné) en SSH.

Si les tâches sont nombreuses ou dépendent les unes des autres, placez-les dans un script du dépôt et n'appelez que ce script depuis .cpanel.yml :

---
deployment:
  tasks:
    - /bin/bash /home/usuario/repositories/proyecto/deploy.sh

Commencez le script par set -e pour qu'il s'arrête à la première commande qui échoue.

Quand le déploiement s'exécute

Push deployment : vous faites un push vers le dépôt cPanel

Si votre dépôt local a pour distant le dépôt cPanel, lors d'un git push, cPanel exécute automatiquement les tâches de .cpanel.yml. Pour cela, le dépôt cPanel doit avoir une branche active et aucune modification non validée.

Pour ajouter le dépôt cPanel comme distant, copiez la Clone URL affichée dans Git™ Version Control > Manage et exécutez sur votre ordinateur :

git remote add cpanel ssh://usuario@tudominio.com/home/usuario/repositories/proyecto
git push cpanel main

Pull deployment : le code est sur GitHub, GitLab ou un autre distant

Si le dépôt cPanel est un clone d'un dépôt GitHub, faites un push vers GitHub comme d'habitude puis, dans Git™ Version Control > Manage > Pull or Deploy :

1. Update from Remote télécharge les modifications.
2. Deploy HEAD Commit exécute les tâches de .cpanel.yml.

Un push vers GitHub ne prévient pas cPanel à lui seul. Pour déployer automatiquement à chaque push, utilisez un webhook GitHub comme expliqué dans le cas pratique avec GitHub, ou une tâche cron comme celle de la section suivante.

Lancer le déploiement avec l'API ou une tâche cron

En SSH, cette commande fait la même chose que le bouton Deploy HEAD Commit :

/usr/local/cpanel/bin/uapi VersionControlDeployment create repository_root=/home/usuario/repositories/proyecto

Remplacez le chemin par celui de votre dépôt. Si la réponse contient status: 1, cPanel a lancé le déploiement ; le résultat de chaque tâche est consigné dans le fichier indiqué par log_path.

Pour déployer périodiquement ce qui se trouve sur GitHub, créez une tâche cron qui télécharge d'abord les modifications puis déploie :

cd /home/usuario/repositories/proyecto && /usr/bin/flock -n /home/usuario/.deploy.lock sh -c 'git pull -q && /usr/local/cpanel/bin/uapi VersionControlDeployment create repository_root=/home/usuario/repositories/proyecto' >/dev/null

flock -n évite que deux exécutions se lancent en même temps si l'une dure plus longtemps que prévu. Ne choisissez pas une fréquence trop élevée : toutes les 10 ou 15 minutes suffit généralement. Si vous ne voulez déployer que lorsqu'il y a des modifications, le webhook est une meilleure option.

Voir ce qui s'est passé lors d'un déploiement

Chaque déploiement laisse un journal dans ~/.cpanel/logs/ sous le nom vc_NUMERO_git_deploy.log. On y trouve chaque commande, sa sortie et son code de sortie : Task completed with exit code 0 signifie que tout s'est bien passé ; tout autre nombre indique la commande qui a échoué.

ls -t ~/.cpanel/logs/*git_deploy.log | head -1 | xargs cat

Si un déploiement ne s'exécute pas lors d'un push, vérifiez dans Git™ Version Control > Manage que le dépôt a une branche active et que .cpanel.yml se trouve à la racine et a été validé par un commit.