deployer un projet laravel avec gitlab

deployer un projet laravel avec gitlab

BUSINESS

Déployer un projet Laravel avec GitLab représente une solution robuste pour automatiser et sécuriser le cycle de développement de vos applications PHP. Dans un environnement où la rapidité de livraison et la fiabilité sont cruciales, l’intégration d’un pipeline CI/CD (Continuous Integration/Continuous Deployment) via GitLab permet de réduire les erreurs humaines, d’accélérer les mises en production et d’assurer une cohérence entre les environnements de développement, de test et de production.

GitLab, avec ses fonctionnalités natives de gestion de versions, de pipelines CI/CD et de déploiement, s’impose comme une plateforme idéale pour les développeurs Laravel. Que vous soyez un freelance gérant plusieurs projets ou une équipe en entreprise, maîtriser le déploiement automatisé avec GitLab vous fera gagner un temps précieux tout en améliorant la qualité de vos livrables. Ce guide détaillé vous accompagnera étape par étape pour configurer un workflow efficace, sécurisé et scalable, adapté aux spécificités de Laravel.

Pourquoi déployer un projet Laravel avec GitLab ?

Les avantages d’une intégration CI/CD avec GitLab

L’utilisation de GitLab pour déployer un projet Laravel offre plusieurs bénéfices majeurs. Tout d’abord, l’automatisation des tests et du déploiement réduit considérablement le risque d’erreurs humaines. Chaque commit peut déclencher une série de vérifications (tests unitaires, linting, analyse de code) avant même que le code ne soit fusionné dans la branche principale.

Ensuite, GitLab propose une gestion centralisée des environnements, permettant de configurer des stages distincts pour le développement, les tests et la production. Cette approche garantit que chaque modification est validée dans un contexte proche de l’environnement final avant d’être déployée en production.

Enfin, la sécurité et la traçabilité sont renforcées grâce aux logs détaillés des pipelines, aux revues de code et aux mécanismes de rollback intégrés. Contrairement à des solutions manuelles ou à des outils moins intégrés, GitLab offre une visibilité complète sur l’ensemble du processus de déploiement.

Compatibilité avec Laravel : une synergie naturelle

Laravel, framework PHP moderne et populaire, est parfaitement compatible avec les pipelines GitLab. Que ce soit pour gérer les dépendances via Composer, exécuter des migrations de base de données ou configurer des variables d’environnement, GitLab fournit tous les outils nécessaires pour orchestrer ces étapes de manière fluide. De plus, Laravel Forge ou Envoyer peuvent être intégrés pour des déploiements encore plus poussés, mais GitLab reste une solution autonome et puissante pour la plupart des projets.

Prérequis avant de configurer le déploiement

Configurer un serveur compatible Laravel

Avant de déployer votre projet Laravel avec GitLab, assurez-vous que votre serveur de production (ou de staging) répond aux exigences suivantes :

  • PHP 8.1 ou supérieur (version recommandée pour Laravel 10+)
  • Composer installé pour gérer les dépendances
  • Base de données (MySQL, PostgreSQL ou MariaDB) avec les droits d’accès appropriés
  • Extensions PHP : bcmath, ctype, fileinfo, json, mbstring, tokenizer, xml, pdo, pdo_mysql
  • Serveur web : Nginx ou Apache configuré pour gérer les requêtes Laravel
  • Permissions des fichiers : Le dossier storage et bootstrap/cache doivent être accessibles en écriture par le serveur web

Pour un déploiement sécurisé, utilisez un utilisateur système dédié (par exemple www-data sur Linux) et désactivez l’accès SSH pour l’utilisateur root. Configurez également un pare-feu (comme UFW) pour limiter les accès aux ports nécessaires (80, 443, et éventuellement 22 pour SSH).

Configurer GitLab pour le projet Laravel

Dans votre projet GitLab, commencez par créer un fichier .gitlab-ci.yml à la racine du dépôt. Ce fichier servira de blueprint pour votre pipeline CI/CD. Assurez-vous également que votre dépôt est bien synchronisé avec votre serveur GitLab (soit via un dépôt local, soit via un hébergeur comme GitHub ou Bitbucket).

Pour une intégration optimale, activez les fonctionnalités suivantes dans GitLab :

  • GitLab Pages (optionnel) pour documenter votre projet
  • GitLab Container Registry si vous utilisez Docker
  • Variables d’environnement sécurisées pour stocker les secrets (clés API, mots de passe de base de données, etc.)
  • Webhooks pour déclencher des pipelines depuis d’autres outils (comme Jira ou Slack)

Enfin, configurez les branches protégées pour éviter les fusions non validées en production, et activez les revues de code pour renforcer la qualité du code avant déploiement.

Configurer le fichier .gitlab-ci.yml pour Laravel

Structure de base du pipeline

Le fichier .gitlab-ci.yml définit les étapes de votre pipeline CI/CD. Voici une structure de base adaptée à Laravel :

stages: - test - build - deploy variables: APP_ENV: "testing" COMPOSER_CACHE_DIR: "$CI_PROJECT_DIR/.composer-cache" cache: paths: - vendor/ - node_modules/ - .composer-cache/ test: stage: test image: php:8.2 before_script: - apt-get update -yqq - apt-get install -yqq git unzip libzip-dev - docker-php-ext-install zip - curl -sS https://getcomposer.org/installer | php -- --install-dir=/usr/local/bin --filename=composer - composer install --prefer-dist --no-interaction - cp .env.example .env - php artisan key:generate - php artisan config:clear script: - composer test - vendor/bin/phpunit build: stage: build image: alpine:latest script: - echo "Building the application..." - echo "No build step required for Laravel (handled by Composer)" artifacts: paths: - vendor/ - .env expire_in: 1 hour deploy_production: stage: deploy image: alpine:latest before_script: - apk add --no-cache openssh-client rsync - eval $(ssh-agent -s) - echo "$SSH_PRIVATE_KEY" | tr -d 'r' | ssh-add - - mkdir -p ~/.ssh - chmod 700 ~/.ssh script: - rsync -avz --delete --exclude-from=.deployignore . user@your-server:/path/to/laravel-project/ - ssh user@your-server "cd /path/to/laravel-project && composer install --no-dev --optimize-autoloader && php artisan migrate --force && php artisan config:cache && php artisan view:cache" only: - main

Explications des étapes clés

Le pipeline est divisé en trois stages : test, build et deploy.

Étape « test » :

  • Utilise une image Docker avec PHP 8.2 pour exécuter les tests.
  • Installe les dépendances nécessaires (Composer, extensions PHP).
  • Génère le fichier .env à partir de .env.example et configure l’application en mode testing.
  • Exécute les tests unitaires via PHPUnit.

Étape « build » :

Cette étape est minimaliste pour Laravel, car le framework gère ses propres dépendances via Composer. Elle peut être utilisée pour générer des artefacts (comme un fichier .env préconfiguré) ou pour exécuter des commandes spécifiques avant le déploiement.

Étape « deploy_production » :

  • Utilise une image Alpine légère pour minimiser la taille du conteneur.
  • Installe les outils nécessaires (SSH, rsync) pour le déploiement.
  • Charge la clé SSH privée (stockée dans une variable GitLab sécurisée) pour se connecter au serveur.
  • Utilise rsync pour synchroniser les fichiers du projet avec le serveur distant, en excluant les fichiers inutiles (via un fichier .deployignore).
  • Exécute les commandes nécessaires sur le serveur : installation des dépendances en mode production, migration de la base de données, et mise en cache des configurations.

Gestion des variables d’environnement et des secrets

Pour sécuriser votre déploiement, utilisez les variables d’environnement de GitLab pour stocker les informations sensibles. Accédez à Settings > CI/CD > Variables dans votre projet GitLab et ajoutez les variables suivantes :

  • SSH_PRIVATE_KEY : La clé privée SSH pour se connecter au serveur.
  • DB_PASSWORD : Le mot de passe de la base de données.
  • APP_KEY : La clé d’application Laravel (générée via php artisan key:generate).
  • APP_ENV : L’environnement de l’application (production, staging, etc.).

Ces variables seront automatiquement injectées dans votre pipeline et accessibles via $VARIABLE_NAME dans le fichier .gitlab-ci.yml.

Automatiser les migrations et la configuration Laravel

Exécuter les migrations de base de données

Les migrations sont essentielles pour maintenir la cohérence de votre base de données entre les environnements. Dans votre pipeline, ajoutez une étape dédiée pour exécuter les migrations en mode production :

deploy_production: stage: deploy image: alpine:latest before_script: - apk add --no-cache openssh-client rsync - eval $(ssh-agent -s) - echo "$SSH_PRIVATE_KEY" | tr -d 'r' | ssh-add - - mkdir -p ~/.ssh - chmod 700 ~/.ssh script: - rsync -avz --delete --exclude-from=.deployignore . user@your-server:/path/to/laravel-project/ - ssh user@your-server "cd /path/to/laravel-project && composer install --no-dev --optimize-autoloader && php artisan migrate --force" only: - main

L’option --force est nécessaire pour exécuter les migrations en production sans confirmation interactive. Assurez-vous que votre utilisateur SSH a les droits nécessaires pour exécuter les commandes sur le serveur.

Optimiser la configuration et les vues

Pour améliorer les performances de votre application Laravel en production, ajoutez les commandes suivantes après les migrations :

script: - rsync -avz --delete --exclude-from=.deployignore . user@your-server:/path/to/laravel-project/ - ssh user@your-server "cd /path/to/laravel-project && composer install --no-dev --optimize-autoloader && php artisan migrate --force && php artisan config:cache && php artisan view:cache && php artisan route:cache"

Ces commandes :

  • config:cache : Met en cache la configuration de l’application pour réduire les temps de chargement.
  • view:cache : Met en cache les vues compilées pour accélérer le rendu.
  • route:cache : Met en cache les routes pour optimiser le routage.

Ces optimisations sont particulièrement utiles pour les applications avec un trafic élevé.

Gérer les fichiers sensibles et les exclusions

Créer un fichier .deployignore

Pour éviter de déployer des fichiers inutiles ou sensibles, créez un fichier .deployignore à la racine de votre projet. Ce fichier fonctionne comme un .gitignore, mais spécifiquement pour le déploiement. Voici un exemple de contenu :

.env .env.* storage/*.key storage/logs/* storage/framework/cache/* storage/framework/sessions/* storage/framework/views/* bootstrap/cache/* node_modules/ vendor/ .git .gitlab-ci.yml .deployignore .DS_Store

Ce fichier exclut les fichiers d’environnement, les logs, les caches et les dépendances, qui ne sont pas nécessaires sur le serveur de production (ou qui devraient être générés dynamiquement).

Sécuriser les fichiers d’environnement

Le fichier .env ne doit jamais être déployé sur le serveur, car il contient des informations sensibles comme les clés API, les mots de passe et les jetons. À la place, utilisez les variables d’environnement de GitLab pour injecter ces valeurs directement dans le pipeline. Sur le serveur, créez un fichier .env minimal avec les valeurs par défaut :

APP_NAME=Laravel APP_ENV=production APP_KEY= APP_DEBUG=false APP_URL=https://votre-domaine.com LOG_CHANNEL=stack LOG_LEVEL=debug DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306 DB_DATABASE=votre_base_de_donnees DB_USERNAME=votre_utilisateur DB_PASSWORD=votre_mot_de_passe BROADCAST_DRIVER=log CACHE_DRIVER=file QUEUE_CONNECTION=sync SESSION_DRIVER=file SESSION_LIFETIME=120 REDIS_HOST=127.0.0.1 REDIS_PASSWORD=null REDIS_PORT=6379 MAIL_MAILER=smtp MAIL_HOST=mailpit MAIL_PORT=1025 MAIL_USERNAME=null MAIL_PASSWORD=null MAIL_ENCRYPTION=null MAIL_FROM_ADDRESS="hello@example.com" MAIL_FROM_NAME="${APP_NAME}"

Les valeurs sensibles (comme APP_KEY, DB_PASSWORD, etc.) seront injectées via les variables GitLab.

Dépannage et bonnes pratiques

Résoudre les erreurs courantes

Voici quelques problèmes fréquents et leurs solutions :

  • Erreur de permissions sur storage ou bootstrap/cache :
    • Sur le serveur, exécutez : chown -R www-data:www-data /path/to/laravel-project/storage et chmod -R 775 /path/to/laravel-project/storage.
    • Dans le pipeline, ajoutez une étape pour régler les permissions : ssh user@your-server "chown -R www-data:www-data /path/to/laravel-project/storage && chmod -R 775 /path/to/laravel-project/storage".
  • Échec des migrations de base de données :
    • Vérifiez que les variables d’environnement de la base de données sont correctement configurées dans GitLab.
    • Assurez-vous que l’utilisateur de la base de données a les droits nécessaires pour créer/modifier des tables.
    • Exécutez manuellement la commande php artisan migrate:status sur le serveur pour diagnostiquer les migrations en attente.
  • Problèmes de cache Laravel :
    • Si les vues ou les routes ne se mettent pas à jour, supprimez manuellement les fichiers dans bootstrap/cache
      Post Views: 22

Comments are closed.