Déployer Laravel sur cPanel (hébergement mutualisé)

Introduction

Ce guide décrit une méthode fiable pour mettre en production une application Laravel sur un hébergement mutualisé équipé de cPanel. Il couvre la préparation locale, le téléversement (File Manager ou Git/SSH), la gestion du Document Root pour servir uniquement le dossier public/, la création de la base de données, l’exécution des commandes Artisan/Composer et la mise en place du scheduler. Si votre offre ne donne pas accès au Terminal/SSH, des alternatives sont indiquées.

Avant de commencer — prérequis

Accès au panneau cPanel du compte.
Version PHP requise par la version de Laravel que vous utilisez — vérifiez la documentation officielle Laravel. (Ex. : Laravel 10 requiert PHP ≥ 8.1.)
Extensions PHP courantes demandées par Laravel : OpenSSL, PDO, Mbstring, Tokenizer, Ctype, JSON, BCMath, Fileinfo, XML, ZIP — vérifiez et activez‑les si nécessaire.
Composer disponible sur le serveur OU la possibilité d’exécuter Composer en local puis téléverser le dossier vendor/.
Accès à l’outil MySQL Databases dans cPanel pour créer la base et l’utilisateur.
Possibilité de modifier le Document Root (racine du domaine/sous‑domaine) pour le pointer sur /.../projet/public, ou capacité à copier/adapter le contenu de public/ dans public_html.
Accès au Terminal/SSH (recommandé) ou possibilité d’utiliser l’outil Git Version Control de cPanel.
Préparer un fichier .env de production : APP_ENV=production, APP_DEBUG=false, APP_KEY, et paramètres DB.
Quota disque et limites PHP (memory_limit, max_execution_time) suffisants pour installer les dépendances et exécuter les tâches.

Résumé de la méthode

Préparer la version de production localement (dépendances, clé APP_KEY, build des assets).
Téléverser le projet sur le serveur (File Manager ou Git/SSH).
Pointer le domaine/sous‑domaine vers /chemin/vers/projet/public ou adapter public/index.php si la racine ne peut pas être changée.
Créer la base de données MySQL et mettre à jour .env.
Exécuter les migrations, régler les permissions et configurer le scheduler (cron).

Étapes détaillées

1) Préparer votre projet en local

Sur votre machine de développement :

Installer les dépendances en mode production :

composer install --no-dev --optimize-autoloader

Générer la clé d’application et copiez‑la dans .env :
```
php artisan key:generate --show
```
Construire les assets (Vite / Mix) selon le projet :
```
npm ci
npm run build
```
Supprimez les fichiers inutiles (par ex. node_modules/) avant d’archiver si vous utilisez l’upload ZIP.

Conseil : si votre hébergement ne propose pas Composer, exécutez composer install localement puis téléversez le dossier vendor/. C’est moins pratique pour les mises à jour mais fonctionnel.

2) Choisir la structure côté serveur (Document Root)

Deux stratégies :

A — Méthode propre (recommandée quand possible)

Créez un dossier pour votre projet (par ex. /home/username/monprojet) et pointez la racine du domaine ou du sous‑domaine directement vers /home/username/monprojet/public. Cela évite d’exposer des fichiers applicatifs.

Créer un domaine supplémentaire avec un dossier racine distinct dans cPanel

Exemple : dans cPanel, choisissez une racine de document distincte pour un addon domain ou un sous‑domaine puis placez vos fichiers dans ce dossier.

Si vous avez besoin d’aide pour créer un sous‑domaine ou modifier la racine, voyez : Comment ajouter un sous‑domaine dans cPanel.

B — Si vous ne pouvez pas changer la racine

Copiez le contenu de public/ dans public_html/ et modifiez les chemins de index.php pour pointer vers le dossier application situé hors de public_html. Exemple (placeholders) :

// public_html/index.php (exemple si le projet est dans ../monprojet)
require __DIR__ . '/../monprojet/vendor/autoload.php';
$app = require_once __DIR__ . '/../monprojet/bootstrap/app.php';

Important — protégez le fichier .env : il doit rester en dehors de public_html. Pour empêcher l’accès direct au fichier, ajoutez, si besoin, une règle Apache :

<Files ".env">
    Require all denied
</Files>

(sur serveurs très anciens : utiliser Deny from all selon la configuration Apache.)

3) Téléverser les fichiers

Option A — Gestionnaire de fichiers (File Manager)

Créez un fichier ZIP du projet (sans node_modules/), puis : cPanel → File Manager → placez‑vous dans le dossier destinataire et Upload → Extract.

Accéder à Gestionnaire de fichiers depuis le tableau de bord cPanel

Téléversement et extraction d’une archive ZIP via le Gestionnaire de fichiers.

Option B — SSH / Git (recommandé si disponible)

Si votre plan offre SSH ou le Terminal cPanel, clonez votre dépôt et utilisez Composer sur le serveur :

git clone git@repo.exemple:monprojet.git /home/username/monprojet
cd /home/username/monprojet
composer install --no-dev --optimize-autoloader
npm ci && npm run build

Accéder à Terminal depuis le tableau de bord cPanel

Terminal intégré : disponible uniquement si votre hébergeur l’a activé. Si vous préférez Git via l’interface, voyez Gérer des dépôts Git dans cPanel.

4) Créer la base de données et configurer `.env`

Dans cPanel → MySQL Databases : créez la base, créez l’utilisateur et Add User To Database (privilèges ALL). Notez les noms complets (préfixe cPanel) et le mot de passe.

Accéder à bases de données MySQL depuis le tableau de bord cPanel

Créer une base et un utilisateur MySQL depuis l’interface cPanel.

Editez le fichier .env (à la racine du projet, en dehors de public_html) :

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=nom_de_votre_base
DB_USERNAME=nom_utilisateur
DB_PASSWORD=mot_de_passe
APP_ENV=production
APP_DEBUG=false
APP_KEY=base64:...

5) Exécuter les migrations et optimiser

Si vous avez SSH/Terminal, exécutez depuis la racine du projet :

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan config:cache
php artisan route:cache
php artisan view:cache

Si vous n’avez pas SSH :

Exécutez composer install localement et téléversez le dossier vendor/.
Pour lancer ponctuellement des commandes Artisan sans SSH, on peut créer un petit script PHP qui exécute la commande côté serveur — c’est une solution de dernier recours et temporaire : supprimez immédiatement le script après usage et limitez son accès.

6) Permissions

Les dossiers suivants doivent être inscriptibles par PHP : storage et bootstrap/cache. Via Terminal :

chmod -R 775 storage bootstrap/cache

Sur certains hébergements mutualisés, 755 est requis — adaptez selon la politique du fournisseur. Vous pouvez aussi modifier les permissions depuis le Gestionnaire de fichiers.

Cases de lecture, écriture et exécution pour les permissions d’un fichier dans cPanel

7) Configurer la version PHP et les limites

Dans cPanel → MultiPHP Manager (ou PHP Selector), définissez la version PHP requise par votre Laravel (ex. PHP 8.1+ pour Laravel 10). Ajustez, si besoin, memory_limit et max_execution_time via MultiPHP INI Editor.

Sélection du domaine et de la version PHP dans MultiPHP Manager sur cPanel

Choisissez la version PHP adaptée et, au besoin, modifiez les options dans l’éditeur INI.

Vérifiez aussi que les extensions listées au début de ce guide sont activées. Pour savoir comment changer la version PHP : Comment changer la version et extensions PHP sur mon hébergement cPanel ?

8) Scheduler et tâches planifiées (cron)

Pour exécuter le scheduler Laravel, créez une tâche cron (cPanel → Cron Jobs) qui lance php artisan schedule:run chaque minute :

* * * * * /usr/bin/php /home/username/chemin/vers/projet/artisan schedule:run >> /dev/null 2>&1

Formulaire de planification et commande d’une tâche Cron dans cPanel — Planification de la tâche Cron

Créer une tâche cron pour exécuter le scheduler Laravel.

Astuce queues : en mutualisé le Supervisor (processus persistant) n’est souvent pas disponible. Une alternative consiste à exécuter régulièrement via cron :

* * * * * /usr/bin/php /home/username/chemin/vers/projet/artisan queue:work --once --tries=3 >> /dev/null 2>&1

Cela lance un worker qui traite les jobs puis s’arrête; adapté si le flux n’est pas intense.

Vérifications finales

Visitez votre domaine : la page d’accueil Laravel confirme que le déploiement est fonctionnel.
Erreur 500 : consultez d’abord storage/logs/laravel.log puis les journaux d’erreurs cPanel (Errors / Raw Access). Voir : Comment consulter les journaux d’accès de mon site dans cPanel ?
Affichage du code PHP à la place de la page : le serveur n’exécute pas PHP pour cette racine — vérifiez la version/gestionnaire PHP et le Document Root.
Si la connexion à la base échoue : vérifiez le préfixe du nom de la base et de l’utilisateur (cPanel ajoute souvent un préfixe).

Limitations communes sur un hébergement mutualisé

Pas (ou peu) de processus persistants : Supervisor et workers long‑running généralement indisponibles.
WebSockets et services temps réel rarement pris en charge en mutualisé.
Ressources CPU/RAM limitées : surveillez l’usage et optimisez caches/compilation des assets.
Accès root et configuration serveur restreints — pour des besoins avancés (Redis dédié, files d’attente intensives, WebSockets), un VPS ou une solution managée est préférable.

Dépannage rapide

Erreur 500 Consultez storage/logs/laravel.log. Vérifiez permissions (storage, bootstrap/cache), version PHP et extensions manquantes. Composer absent Exécutez Composer en local puis téléversez vendor/, ou demandez au support d’activer Composer/Terminal pour votre compte. Page 404 / mauvais contenu Vérifiez le Document Root du domaine/sous‑domaine et assurez‑vous qu’il pointe vers /.../public ou que public_html/index.php référence correctement l’autoload et le bootstrap. APP_KEY manquante Générez la clé en local (php artisan key:generate --show) et placez‑la dans .env comme APP_KEY=base64:....

Liens internes utiles

Résumé

Le déploiement d’une application Laravel sur un hébergement mutualisé cPanel est possible en respectant quelques règles : servir uniquement le dossier public/, vérifier la version PHP et les extensions, installer les dépendances (Composer) et protéger .env. L’accès SSH/Terminal et la possibilité de modifier le Document Root simplifient fortement l’opération. Pour des besoins nécessitant des processus persistants (workers, WebSockets), envisagez un VPS ou une offre managée.

Sources : documentation officielle Laravel pour les exigences système (voir « Sources » ci‑dessous) et documentation/KB cPanel pour les outils cités.

Documentation de référence

Documentation consultée le 28 octobre 2026. Les outils peuvent varier selon votre hébergement.

Déployer une application Laravel sur un hébergement cPanel (mutualisé)