Déployer WordPress et Laravel sur cPanel avec Deployer

Deployer automatise les déploiements en SSH grâce à une recette PHP que vous conservez avec le projet. Chaque publication peut préparer un nouveau dossier et activer cette version à la fin. C'est une alternative pour qui veut garder son propre processus de déploiement ; si vous préférez le configurer depuis l'espace client, consultez Deploy+.

Ce guide utilise Deployer 8 et propose de commencer avec un sous-domaine de test. Séparer les versions réduit la durée du changement de code, mais la continuité du service dépend aussi des migrations, des fichiers partagés, des caches et des processus de l'application.

Préparer l'environnement

Vous avez besoin d'un accès SSH à l'hébergement, d'un dépôt Git accessible depuis le serveur et d'espace pour le code, les dépendances, les fichiers partagés et plusieurs versions. Configurez une clé en lecture seule pour le dépôt privé le cas échéant.

Sur votre ordinateur ou votre environnement d'intégration, vérifiez les prérequis de l'installation de Deployer 8. Cette version nécessite PHP 8.3 ou supérieur pour exécuter l'outil. Installez-la comme dépendance de développement du projet et conservez le fichier de verrouillage :

composer require --dev deployer/deployer:^8
vendor/bin/dep --version

Le PHP qui exécute Deployer sur votre ordinateur et le PHP qui exécutera l'application sur l'hébergement sont deux environnements distincts. Vérifiez la version et les extensions des deux, ainsi que Composer, Git et les outils dont votre compilation a besoin.

Choisir l'emplacement et la racine publique

Dans les recettes, {{deploy_path}}/current représente le lien vers la version publiée dans le chemin de déploiement. Deployer remplace {{deploy_path}} par la valeur que vous configurez ; ce n'est pas un chemin à copier tel quel dans cPanel.

Nous utiliserons /home/usuario_cpanel/apps/miapp comme répertoire privé de déploiement. Remplacez l'utilisateur, le serveur, le port SSH et le dépôt des exemples par vos vraies données.

La structure sera :

miapp/
  releases/   versiones de código
  shared/     archivos que persisten
  current     enlace a la versión publicada

La racine du domaine de test doit servir current/public pour Laravel ou current pour un WordPress classique. Vérifiez que la configuration de votre domaine autorise ce chemin et les liens symboliques avant le premier déploiement. Les restrictions de cPanel peuvent empêcher une racine en dehors de public_html ; le domaine principal ne se configure pas non plus toujours comme un domaine supplémentaire.

Ne déplacez pas et ne supprimez pas public_html pour tester cette structure : il pourrait contenir d'autres sites. Si le domaine n'accepte pas le chemin prévu, convenez d'une configuration compatible avec l'assistance ou utilisez Deploy+. Ne publiez pas le dossier complet de Laravel, qui contient des fichiers privés.

Exemple pour WordPress

Cet exemple suppose que le dépôt contient le code d'un WordPress classique, ses plugins et son thème. Si vous utilisez Bedrock ou une autre structure, adaptez la recette et la racine publique.

Créez deploy.php dans le projet :

<?php
namespace Deployer;

require 'recipe/wordpress.php';

set('repository', 'git@github.com:organizacion/wordpress.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['wp-config.php']);
set('shared_dirs', ['wp-content/uploads']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('writable_dirs', ['wp-content/uploads']);

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

after('deploy:failed', 'deploy:unlock');

Préparez au préalable shared/wp-config.php avec la configuration complète du WordPress de test : base de données, préfixe des tables, clés et autres réglages du site. Conservez ces valeurs lorsque vous transférez une installation existante et vérifiez tout chemin absolu hérité. N'envoyez pas les identifiants dans le dépôt.

Copiez les images existantes dans shared/wp-content/uploads et vérifiez leurs permissions avec l'utilisateur de l'hébergement. Le dossier partagé doit contenir les bonnes données avant la publication ; ne comptez pas sur le déploiement pour importer à lui seul les fichiers d'une autre installation.

Dans cet exemple, les plugins et thèmes sont publiés depuis Git. Une mise à jour faite uniquement depuis l'administration de WordPress peut disparaître avec la version suivante. Choisissez un flux de mise à jour qui garde le dépôt à jour. Partager tout wp-content n'est pas non plus une solution automatique : cela empêcherait de versionner ce code de façon fiable.

Exemple pour Laravel

La recette officielle de Laravel inclut des tâches de migration et de rechargement des services. Avant de l'adopter, vérifiez lesquelles votre application nécessite et autorise. L'exemple suivant définit un flux explicite sans migrations ni redémarrage de processus, pour préparer d'abord la publication en test :

<?php
namespace Deployer;

require 'recipe/laravel.php';

set('repository', 'git@github.com:organizacion/laravel.git');
set('branch', 'main');
set('keep_releases', 3);
set('shared_files', ['.env']);
set('shared_dirs', ['storage']);
set('writable_mode', 'chmod');
set('writable_chmod_mode', '0755');
set('bin/php', '/opt/alt/php83/usr/bin/php');

host('pruebas')
    ->setHostname('servidor.example.com')
    ->setRemoteUser('usuario_cpanel')
    ->setPort(93)
    ->set('deploy_path', '/home/usuario_cpanel/apps/miapp');

task('deploy', [
    'deploy:prepare',
    'deploy:vendors',
    'artisan:storage:link',
    'artisan:config:cache',
    'artisan:route:cache',
    'artisan:view:cache',
    'deploy:publish',
]);

after('deploy:failed', 'deploy:unlock');

Le chemin de PHP 8.3 est un exemple : vérifiez qu'il existe et qu'il satisfait composer.lock. Configurez une autre version disponible si le projet l'exige. Vérifiez aussi comment la recette exécute Composer sur ce serveur.

Avant le premier déploiement, préparez shared/.env en dehors de la racine publique, avec des permissions limitées à l'utilisateur du compte. Utilisez la base de données de test, désactivez le débogage public et conservez l'APP_KEY d'une application existante : le régénérer peut empêcher de déchiffrer des données et fermer les sessions. Ne générez une clé que pour une nouvelle installation qui n'en a pas encore.

Préparez les dossiers que l'application utilise dans shared/storage, y compris les répertoires de sessions, de vues et de cache le cas échéant. bootstrap/cache appartient à chaque release ; ce n'est pas un sous-dossier de storage. Vérifiez que l'utilisateur qui exécute PHP peut écrire là où il en a besoin, sans permissions 777.

Si le projet a besoin d'assets compilés, intégrez le résultat à l'artefact ou ajoutez une tâche de compilation avant la publication. Les tâches présentées n'exécutent pas npm. Si un cache n'est pas compatible avec votre application, corrigez sa configuration ou adaptez la tâche après l'avoir testée.

Vérifier et lancer le déploiement

Depuis l'ordinateur où vous avez installé Deployer :

vendor/bin/dep deploy --plan pruebas

Vérifiez l'ordre des tâches et les hooks de la version installée. Le plan aide à repérer des opérations inattendues, mais ne vérifie pas que le serveur ou l'application fonctionnent.

Quand l'environnement de test est prêt :

vendor/bin/dep deploy pruebas

Vérifiez le résultat dans la sortie et ouvrez le site. Testez la connexion, une page interne, les formulaires, l'envoi d'images et les opérations sur la base de données. Avec Laravel, vérifiez aussi les tâches planifiées et les processus en arrière-plan que vous utilisez réellement.

Si une exécution échoue, examinez la première tâche en erreur. Ne déverrouillez pas le déploiement tant qu'un autre processus travaille encore et ne supprimez pas de versions pour libérer de l'espace sans avoir identifié celle qui est active.

Migrations et passage en production

Une nouvelle version peut nécessiter des changements de schéma. Prévoyez des migrations compatibles avec le code qui continue de répondre aux requêtes pendant le changement. Si ce n'est pas possible, utilisez une fenêtre de maintenance et une procédure de récupération éprouvée.

Il ne suffit pas d'ordonner « d'abord le code, ensuite la base de données » : cela dépend du changement. N'ajoutez pas non plus migrate:fresh, qui supprime les tables, au déploiement d'une installation contenant des données.

Avant de passer en production, conservez une sauvegarde récupérable des fichiers et de la base de données, testez la recette et préparez le changement de racine du domaine. La première publication ne dispose d'aucune release précédente vers laquelle revenir.

Revenir à une version précédente

Si vous conservez une version précédente compatible, vous pouvez lancer le rollback :

vendor/bin/dep rollback pruebas

Vérifiez ensuite le site et ses principales opérations. Le rollback change le code publié ; il ne récupère pas la base de données et ne remet pas les fichiers partagés dans leur état précédent. Une migration ou un script qui les a modifiés nécessite sa propre procédure de récupération.

Les releases conservées occupent de l'espace et ne remplacent pas les sauvegardes. Ajustez leur rétention à la taille du projet et à la marge disponible pour construire la version suivante.

Pour approfondir les tâches disponibles, consultez la recette WordPress et la recette Laravel correspondant à la version installée. Sur un hébergement mutualisé, utilisez des tâches de déploiement avec votre utilisateur ; les recettes de provisionnement de serveurs exigent des privilèges que ce compte n'a pas.