Prérequis

Avant de pouvoir héberger des applications Laravel, vous devez installer l’extension gratuite Laravel Toolkit sur le serveur Plesk :

• Si vous êtes l’administrateur de Plesk, installez l’extension depuis le Catalogue des extensions.
• Si vous n’êtes pas administrateur, contactez votre hébergeur et demandez-lui d’installer l’extension pour vous.

Once the extension is installed, you are ready to begin. You will see the Laravel button in the Navigation Pane, and also in the « Create Website » drawer on the domain cards of all your domains.

Téléverser votre application

Avant de configurer et d’exécuter votre application, vous devez la téléverser sur le serveur Plesk et l’enregistrer dans Laravel Toolkit. Pour cela, utilisez l’une des trois méthodes suivantes :

• Créer un squelette Laravel. Si votre application est stockée dans un dossier ou un fichier compressé sur votre ordinateur ou si vous voulez créer votre application de A à Z, Laravel Toolkit doit créer la structure du répertoire nécessaire ainsi qu’un dépôt Git.
• Installer depuis un dépôt Git distant. Si votre application est stockée dans un dépôt distant, vous pouvez la déployer sur le serveur Plesk.
• Rechercher une application existante. Si vous avez déjà téléversé votre application sur Plesk, vous pouvez l’enregistrer dans Laravel Toolkit en utilisant l’analyse.

Créer un squelette Laravel:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui hébergera votre application et cliquez sur Créer un site web > Laravel.
3. Sélectionnez « Installer le squelette » et cliquez sur Installer l’application.
4. Lorsque le squelette est installé, vous devez téléverser les fichiers de votre application sur Plesk (par exemple via FTP ou via le Gestionnaire de fichiers) et remplacer les fichiers par défaut si nécessaire.

Installer depuis un dépôt Git distant:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui hébergera votre application et cliquez sur Créer un site web > Laravel.
3. Sélectionnez « Installer depuis un dépôt distant ».
4. Saisissez ou copiez l’URL du dépôt distant contenant les fichiers de votre application.
5. Si le dépôt distant requiert une authentification, ajoutez-y la clé publique que vous voyez sur cette page.
6. Cliquez sur Installer l’application.

Analyser pour trouver une application existante:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web & Domaines. Cherchez le domaine sur lequel vous hébergerez votre application, puis ouvrez l’onglet « Hébergement et DNS ».
3. Click Hosting.
4. Modifiez la valeur dans « Racine du document » pour que celle-ci corresponde au répertoire public de votre application (par défaut /httpdocs/public) et cliquez sur Enregistrer.
5. Go back to the « Dashboard » tab, click Create Website > Laravel, click Cancel, and then click Scan.

Une fois que vous avez téléversé ou déployé les fichiers de votre application et que celle-ci est enregistrée dans Laravel Toolkit, le bouton Laravel s’affiche sur la carte du domaine qui héberge votre application.

Vous pouvez désormais passer à l’étape suivante.

Exécuter les commandes Artisan, Composer et Node.js

Pour gérer votre application Laravel, vous devrez sans doute exécuter les commandes Artisan, Composer et/ou Node.js. Laravel Toolkit permet de les exécuter facilement depuis l’interface Plesk sans accès shell.

Si vous ne savez pas si votre application a besoin d’exécuter les commandes Artisan, Composer et/ou Node.js pour fonctionner correctement, consultez la personne ou l’entreprise qui vous a fourni l’application.

Exécuter une commande Artisan, Composer ou Node.js:

1. Connectez-vous à Plesk.

2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.

3. Allez sur l’onglet correspondant, saisissez la commande que vous voulez exécuter ou choisissez-en une dans la liste et appuyez sur la touche Entrée ou cliquez sur le bouton .

   Note: Lorsque vous exécutez des commandes Node.js, vous devrez peut-être spécifier la version de Node.js et/ou le gestionnaire de pack pour que la commande ait l’effet voulu. Si vous ne savez pas si vous devez spécifier la version, consultez la personne ou l’entreprise qui vous a fourni l’application.

Voir les fichiers journaux de votre application

Pendant que Laravel fonctionne, les entrées sont consignées dans un fichier journal distinct. Vous pouvez voir le contenu de ce fichier depuis l’interface Laravel Toolkit afin de surveiller votre application et de résoudre plus facilement les problèmes lorsqu’il y en a.

Voir le journal de votre application:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Cliquez sur Journaux.

Cela ouvrira l”Explorateur de journaux du domaine. Seules les entrées du journal Laravel sont affichées.

Voir les tâches planifiées de votre application

Avec Laravel, vous pouvez planifier des tâches dans le code de l’application au lieu d’utiliser un planificateur externe comme cron. Laravel Toolkit vous permet de voir toutes les tâches configurées actuellement directement depuis l’interface de Laravel. Vous pouvez également activer et désactiver les tâches planifiées de Laravel.

Voir les tâches planifiées de votre application:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Allez dans l’onglet « Tâches planifiées » (cet onglet est visible uniquement lorsqu’une ou plusieurs tâches planifiées sont configurées).

Activer la gestion des tâches planifiées:

1. Connectez-vous à Plesk.
2. Activez le droit « Gestion du planificateur » (dans l’onglet « Permissions ») pour l’abonnement auquel l’hébergement du domaine de votre application appartient.
3. (Plesk pour Linux) Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application. Ensuite, allez dans l’onglet « Hébergement et DNS » et cliquez sur Hébergement.
4. (Plesk pour Linux) Dans « Accès SSH », sélectionnez n’importe quelle option sauf « Interdit » et cliquez sur Enregistrer.

Vous pouvez désormais activer ou désactiver les tâches planifiées de votre application.

Activer les tâches planifiées de votre application:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Faites glissez le bouton Tâches planifiées pour qu’il indique « Activé ».

Les tâches planifiées sont désormais activées pour votre application Laravel.

Modifier les variables d’environnement

Votre application peut avoir besoin d’une ou plusieurs variables d’environnement pour fonctionner correctement ou encore fonctionner différemment selon les variables définies. Si vous ne savez pas quelles sont les variables d’environnement requises pour que votre application fonctionne correctement, consultez la personne ou l’entreprise qui vous a fourni l’application.

Modifier les variables d’environnement:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Cliquez sur le bouton Modifier à côté de « Variables d’environnement (.env) ».
4. Modifiez les variables d’environnement si nécessaire et cliquez sur Mettre à jour.

Les variables d’environnement mises à jour sont désormais en vigueur.

Mettre votre application en mode Maintenance

Pour éviter aux visiteurs de votre site web de voir des erreurs lorsque vous travaillez sur votre application ou lorsque vous la mettez à jour, vous pouvez utiliser le mode Maintenance. Quand votre application est en mode Maintenance, les visiteurs de votre site web voient une page avec l’erreur « 503 SERVICE NON DISPONIBLE ».

Mettre votre application en mode maintenance:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Cliquez sur le bouton Mode Maintenance pour le passer sur « Activé ».

Votre application Laravel est désormais en mode Maintenance.

Mettre à jour votre application

Vous devez vous assurer de propager les modifications du code de l’application sur le serveur Plesk, que les fichiers de votre application Laravel soient stockés dans un dépôt Git local ou distant. Vous pouvez déployer les modifications manuellement ou automatiquement.

Si vous avez besoin de contrôler précisément le moment de la mise à jour de votre application, nous vous recommandons d’opter pour la mise à jour manuelle. Ainsi, les modifications effectuées dans le code de l’application dans le dépôt sont propagées sur le serveur Plesk lorsque vous le décidez. L’inconvénient de cette approche est que vous devez effectuer des opérations manuelles à chaque fois que l’application nécessite une mise à jour.

Mettre à jour manuellement votre application:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Allez dans l’onglet « Déploiement ». Dans « Mode de déploiement », sélectionnez le bouton radio « Manuel ».
4. Dans « Scénario de déploiement », décochez les cases qui correspondent aux étapes que vous ne voulez pas exécuter pendant le déploiement et cliquez sur Déployer.

Une fois que Laravel Toolkit a exécuté toutes les étapes du déploiement, votre application et ses dépendances seront à jour.

Si vous voulez propager automatiquement sur le serveur Plesk les modifications apportées au code de l’application, la méthode diffère selon si le code de l’application est stocké dans un répertoire Git local ou distant.

Mettre à jour automatiquement votre application (dépôt local):

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Allez dans l’onglet « Déploiement ». Sous « Mode de déploiement », sélectionnez le bouton radio « Automatique ».
4. Sous « Scénario de déploiement », décochez les cases qui correspondent aux étapes que vous ne voulez pas exécuter pendant le déploiement.

À présent, à chaque fois qu’un commit est poussé vers la branche master du dépôt local qui stocke le code de votre application, celle-ci et ses dépendances seront mises à jour.

Mettre à jour automatiquement votre application (dépôt distant):

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Copiez l’URL webhook que vous voyez ici et ajoutez-la au dépôt distant. Pour en savoir plus, consultez la documentation du fournisseur de votre dépôt.
4. Allez dans l’onglet « Déploiement ». Sous « Mode de déploiement », sélectionnez le bouton radio « Automatique ».
5. Sous « Scénario de déploiement », décochez les cases qui correspondent aux étapes que vous ne voulez pas exécuter pendant le déploiement.

À présent, à chaque fois que l’événement qui déclenche votre webhook se produit dans le dépôt distant qui stocke le code de l’application, celle-ci et ses dépendances seront mises à jour.

Configurer un script de déploiement

Pour que votre application fonctionne correctement, vous devez exécuter certaines commandes sur le serveur pendant le déploiement. Vous pouvez développer un script pour éviter d’exécuter manuellement ces commandes. Ce script sera exécuté à chaque mise à jour de l’application.

Si vous ne savez pas si votre application a besoin d’exécuter des commandes lors du déploiement pour fonctionner correctement, consultez la personne ou l’entreprise qui vous a fourni l’application.

(Plesk for Linux) Enabling the ability to edit the deployment script:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web & Domaines et trouvez le domaine qui héberge votre application. Ensuite, allez sur l’onglet « Hébergement et DNS » et cliquez sur Hébergement.
3. Dans « Accès SSH », sélectionnez n’importe quelle option sauf « Interdit » et cliquez sur Enregistrer.

Vous pouvez désormais modifier le script de déploiement depuis l’interface Laravel Toolkit.

Modifier le script de déploiement:

1. Connectez-vous à Plesk.
2. Allez dans Sites Web et Domaines. Cherchez le domaine qui héberge votre application et cliquez sur Laravel.
3. Allez dans l’onglet « Déploiement » et cliquez sur Modifier le script.
4. Saisissez ou collez votre script de déploiement et cliquez sur Mettre à jour.

Le script de déploiement est désormais effectif et sera exécuté à chaque mise à jour de votre application.

Gérer les files d’attente (« queues »)

Les files d’attente dans Laravel permettent de traiter des tâches chronophages, comme l’analyse d’un fichier téléversé, de manière asynchrone en arrière-plan. Si votre application prend en charge les files d’attente, vous pouvez les activer dans Plesk pour configurer le processus queue worker.

Pour utiliser les files d’attente, vous devez les activer pour votre abonnement et créer une base de données pour queue worker (une seule fois).

Les files d’attente Laravel peuvent utiliser divers backend de files d’attente. Toutefois, dans ce guide nous aborderons uniquement la base de données MySQL/MariaDB comme backend. Il s’agit du moyen le plus simple pour activer les files d’attente dans Plesk. Cette solution répond généralement aux besoins de la plupart des utilisateurs. D’autres backends offrent des avantages supplémentaires comme l’amélioration des temps d’accès, mais ils requièrent de l’expertise pour être mis en place et maintenus, ce qui peut également impliquer des coûts supplémentaires.

Activer les files d’attente (« queues »):

1. Connectez-vous à Plesk, puis cherchez le domaine qui héberge votre application.

2. Activez les tâches planifiées pour votre application afin que les files d’attente fonctionnent.

3. Dans le dépôt Git du projet de votre application, ajoutez la ligne suivante à la section « require » du fichier composer.json :

   "plesk/ext-laravel-integration": "^7.0"
   

   Note: Dans chaque section du fichier composer.json, toutes les lignes doivent terminer par une virgule, sauf la dernière.

   Si vous utilisez un dépôt Git local, ne procédez pas à cette modification via le gestionnaire de fichiers. À la place, effectuez les commit vers le répertoire. Cela permet d’éviter que vos modifications soient écrasées lors du prochain déploiement de votre application.

4. Cliquez sur Laravel. Allez dans l’onglet « Déploiement » et cliquez sur Déployer. Cela entraîne la modification du contenu du fichier composer.lock. Effectuez le commit de ces modifications dans le dépôt afin d’éviter d’écraser ces modifications lors du prochain déploiement de votre application.

5. Une fois que vous avez fait le commit des modifications, cliquez à nouveau sur Déployer.

6. (Facultatif) Revenez à la carte du domaine. Puis, allez dans Bases de données et cliquez sur Ajouter une base de données*.

   Note: Si votre application Laravel utilise déjà une base de données MySQL/MariaDB, vous pouvez utiliser cette base de données pour activer les files d’attente. Dans ce cas, ignorez cette étape ainsi que la suivante.

7. (Facultatif) Créez une base de données MySQL ou MariaDB et un utilisateur de base de données.

8. Revenez sur la carte du domaine. Cliquez sur Laravel, puis sur le bouton Éditer à côté de « Variables d’environnement (.env) ».

9. Ajoutez les lignes suivantes au fichier .env en remplaçant les variables avec les informations relatives à la base de données que vous voulez utiliser (soit celle que vous venez de créer, soit celle déjà en cours d’utilisation par votre application Laravel) :

   DB_CONNECTION=mysql
   DB_HOST=<database server IP address or hostname>
   QUEUE_CONNECTION=database
   DB_DATABASE=<database name>
   DB_USERNAME=<database user name>
   DB_PASSWORD=<database user password>
   

   et cliquez sur « Mettre à jour ».

10. Placez votre application Laravel en Mode Maintenance.

11. Allez dans l’onglet « Artisan ». Puis, exécutez les commandes suivantes, dans cet ordre :

    queue:table

    migrate

12. Allez dans l’onglet « Tableau de bord ». Quittez le mode Maintenance et cliquez sur le bouton à bascule File d’attente pour le positionner sur « Activé ».

Les files d’attente sont désormais activées pour votre application Laravel.

Pour que le processus queue worker utilise plus efficacement les ressources du serveur, vous devez configurer un certain nombre de paramètres dans Plesk. Ces paramètres concernent essentiellement la manière dont le processus queue worker peut se terminer et libérer la mémoire qu’il utilisait.

Configurer le processus queue worker:

1. Connectez-vous à Plesk, puis cherchez le domaine qui héberge votre application.

2. Cliquez sur Laravel et allez dans l’onglet « File d’attente ».

3. (Facultatif) Cochez la case « Arrêter le worker quand vide » pour indiquer au processus worker de s’arrêter lorsqu’il n’y a aucune tâche dans la file d’attente. Dans ce cas, le processus démarre toutes les 60 secondes, traite les tâches actuellement en attente, puis quitte.

   Si vous ne cochez pas la case « Arrêter le worker quand vide », alors le processus continue de s’exécuter même lorsqu’il n’y a aucune tâche dans la file d’attente.

4. (Facultatif) Définissez une valeur « Timeout » personnalisée pour indiquer au processus worker quand il doit quitter avec une erreur lorsque la tâche s’exécute depuis une durée supérieure à la valeur que vous avez indiquée. Assurez-vous de saisir une valeur assez élevée pour que la tâche typique créée par votre application dispose d’assez de temps pour terminer.

   Si vous ne définissez pas de valeur « Timeout » personnalisée, alors le processus worker ne quitte pas même lorsqu’une tâche individuelle de la file d’attente est traitée depuis un long moment (par exemple, lorsque la tâche est bloquée).

   Prudence: Si la valeur n’est pas assez élevée, les tâches risquent d’échouer parce qu’elles n’ont pas assez de temps pour être traitées (par exemple, pour l’envoi d’un fichier volumineux). Si des tâches commencent à échouer lorsque vous avez défini une valeur « Timeout » personnalisée, essayez d’augmenter cette valeur ou de remettre la valeur par défaut (« 0 » indique qu’il n’y a aucune limite de durée de traitement d’une tâche).

5. (Facultatif) Définissez une valeur « Nbr max tâches » personnalisée pour que le processus worker quitte lorsqu’il a terminé un certain nombre de tâches.

   Si vous ne définissez pas de valeur « Nbr max tâches », alors le processus worker ne s’arrête pas, même s’il a traité un grand nombre de tâches.

6. (Facultatif) Définissez une valeur « Durée max » pour que le processus worker quitte une fois qu’il a été exécuté pendant le nombre de secondes spécifié (le processus ne quittera pas pendant qu’il traite une tâche).

   Si vous ne définissez pas de valeur « Durée max », alors le processus worker continue de s’exécuter, même s’il s’exécute depuis un long moment.

Le processus queue worker a été configuré et devrait désormais utiliser plus efficacement les ressources.

Jobs may fail due to many reasons. Plesk keeps track of failed jobs, which you can restart or dismiss.

Afficher, redémarrer et annuler des tâches ayant échoué:

1. Connectez-vous à Plesk, puis cherchez le domaine qui héberge votre application.
2. Cliquez sur Laravel. Allez dans l’onglet « File d’attente » et ensuite cliquez sur Afficher les tâches échouées pour la voir la liste des tâches.
3. (Facultatif) Sélectionnez une ou plusieurs tâches ayant échoué et cliquez sur Réessayer pour la ou les redémarrer.
4. (Facultatif) Sélectionnez une ou plusieurs tâches ayant échoué et cliquez sur Supprimer pour la ou les supprimer de la liste.
5. (Facultatif) Cliquez sur Flush pour supprimer de la liste toutes les tâches ayant échoué.

Les tâches ayant échoué sont désormais soit redémarrées, soit supprimées.