Project

General

Profile

Download (7.9 KB) Statistics
| Branch: | Revision:

davca-cm/README.md @ b8ad0125

Voici une version enrichie et plus technique de ton README.md. J'ai ajouté des détails sur la structure, la gestion des variables d'environnement et, comme demandé, une section spécifique pour le déploiement sur un serveur Apache via un fichier .htaccess.

🚀 Projet Vue.js : Guide Complet

Ce guide détaille les étapes pour installer, configurer, optimiser et déployer l'application sur un serveur de production.

📁 Structure du Projet

  • src/ : Code source de l'application (Composants, Vuex/Pinia, Router).
  • public/ : Fichiers statiques (favicon, index.html).
  • dist/ : Dossier généré après le build pour la production.
  • .env : Variables d'environnement (API keys, URLs).

⚙️ 1. Installation et Configuration

Prérequis

  • Node.js : v16+ recommandé.
  • Gestionnaire de paquets : npm (inclus avec Node).

Installation

# Installation des dépendances
npm install

Variables d'environnement

Créez un fichier .env.local à la racine pour vos configurations locales :

VUE_APP_API_URL=https://api.monsite.com

💻 2. Développement Local

Pour lancer l'application en mode développement (avec rafraîchissement automatique) :

npm run serve

Note : Par défaut, le projet tourne sur http://localhost:8080.

🏗️ 3. Préparation pour la Production (Build)

Avant de déployer, vous devez transformer le code source en fichiers optimisés pour le web.

npm run build

Cette commande crée un dossier /dist contenant :

  • Un fichier index.html unique.
  • Des fichiers JS et CSS minifiés (pour un chargement rapide).
  • Les assets (images, polices) optimisés.

🌐 4. Déploiement sur Hébergement Mutualisé (Apache)

Lorsque vous déployez une Single Page Application (SPA), le serveur doit être configuré pour rediriger toutes les requêtes vers index.html. Sans cela, si un utilisateur rafraîchit une page comme /contact, il obtiendra une erreur 404.

Étapes de déploiement :

  1. Connectez-vous à votre serveur via FTP (FileZilla) ou via le gestionnaire de fichiers de votre hébergeur (Hostinger, OVH, etc.).
  2. Transférez le contenu du dossier /dist (et non le dossier lui-même) vers le répertoire racine de votre site (souvent public_html ou www).
  3. Créez un fichier nommé .htaccess à la racine de votre hébergement.

Configuration du fichier .htaccess :

Copiez et collez le code suivant pour gérer le routage Vue Router :

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteBase /
  
  # Si le fichier ou le répertoire demandé existe, on l'affiche normalement
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  
  # Sinon, on redirige tout vers index.html pour que Vue Router prenne le relais
  RewriteRule . /index.html [L]
</IfModule>

🧪 Maintenance et Qualité

Action Commande
Linter npm run lint (Nettoyage automatique du code)
Tests npm run test:unit (Vérification des composants)

Parfait, l'automatisation via GitLab CI/CD va te simplifier la vie : à chaque fois que tu feras un git push, GitLab va compiler ton projet et l'envoyer directement sur ton serveur via FTP (ou SSH).

Voici comment configurer cela.

🤖 5. Automatisation avec GitLab CI/CD

Pour mettre cela en place, tu dois créer un fichier nommé .gitlab-ci.yml à la racine de ton projet.

Étape A : Préparer les variables secrètes

Ne mets jamais tes identifiants FTP dans ton code. Va dans ton projet GitLab :

  1. Settings > CI/CD > Variables.
  2. Ajoute les variables suivantes :
  • FTP_USER : Ton nom d'utilisateur FTP.
  • FTP_PASSWORD : Ton mot de passe FTP.
  • FTP_HOST : L'adresse de ton serveur (ex: ftp.monsite.com).

Étape B : Le fichier .gitlab-ci.yml

Copie ce contenu dans ton fichier :

stages:
  - build
  - deploy

# 1. Étape de compilation
build_project:
  stage: build
  image: node:18
  script:
    - npm install
    - npm run build
  artifacts:
    paths:
      - dist/
    expire_in: 1 hour
  only:
    - main # Ne se lance que sur la branche principale

# 2. Étape de déploiement via FTP
deploy_ftp:
  stage: deploy
  image: mwolff/lftp # Image légère contenant un client FTP
  script:
    # Connexion et synchronisation du dossier dist vers le serveur
    - lftp -e "set ftp:ssl-allow no; open $FTP_HOST; user $FTP_USER $FTP_PASSWORD; mirror -X .* -X .git* -R dist/ ./; quit"
  only:
    - main

📝 Mise à jour du README.md (Section CI/CD)

Ajoute cette section à ton fichier README.md pour que tes collaborateurs (ou ton futur toi) sachent comment le déploiement fonctionne :

## 🤖 Automatisation (CI/CD)

Ce projet utilise **GitLab CI/CD** pour le déploiement automatique.

### Workflow :
1. **Build** : À chaque push sur la branche `main`, GitLab installe les dépendances et génère le dossier `/dist`.
2. **Deploy** : Les fichiers compilés sont automatiquement transférés par FTP sur le serveur de production.

### Configuration :
Les variables de connexion sont stockées de manière sécurisée dans les paramètres CI/CD de GitLab (`FTP_USER`, `FTP_PASSWORD`, `FTP_HOST`).

C'est une excellente idée. Tester un pipeline permet d'éviter de casser la production à cause d'une petite erreur de frappe dans une variable secrète.

Voici comment procéder pour vérifier et déboguer ton déploiement GitLab CI/CD.

🔍 1. Vérifier l'état du Pipeline

Dès que tu fais un git push, rends-toi dans GitLab :

  1. Dans le menu de gauche, va dans Build > Pipelines.
  2. Tu verras une ligne avec un badge Running (bleu), Passed (vert) ou Failed (rouge).
  3. Clique sur le badge de statut pour voir les deux étapes : build_project et deploy_ftp.

🛠️ 2. Analyser les erreurs courantes

Si l'étape deploy_ftp échoue (badge rouge), clique sur le job pour lire les logs de la console. Voici les erreurs classiques :

A. Erreur de connexion (Login failed)

  • Symptôme : lftp: Login failed: 530 Incorrect password.
  • Solution : Vérifie tes variables dans Settings > CI/CD > Variables. Attention aux espaces en trop au début ou à la fin du mot de passe.

B. Problème de certificat SSL

  • Symptôme : Le job tourne en boucle ou affiche Fatal error: Certificate verification: Not trusted.
  • Solution : Dans le fichier .gitlab-ci.yml, j'ai ajouté set ftp:ssl-allow no;. C'est souvent nécessaire sur les hébergements mutualisés classiques qui n'acceptent pas le FTPS sécurisé par défaut via script.

C. Dossier cible incorrect

  • Symptôme : Le pipeline réussit, mais le site n'est pas mis à jour.
  • Solution : Dans la commande mirror, le dernier argument est ./. Si ton site est dans un sous-dossier (ex: /www), change-le en mirror ... dist/ /www/.

🧪 3. Test local (Avant de push)

tester si tes identifiants FTP fonctionnent sans attendre GitLab, tu peux utiliser un client FTP comme FileZilla, ou mieux, tester la commande lftp si tu es sous Linux/Mac :

# Test de connexion rapide
lftp -u mon_user,mon_password -e "ls; quit" ftp.mon-serveur.com

📝 Mise à jour finale du README.md

Ajoute cette petite section "Dépannage" pour garder une trace de comment fixer le pipeline :

### 🔧 Dépannage du déploiement
Si le déploiement échoue dans GitLab :
1. Vérifiez que les variables `FTP_HOST`, `FTP_USER` et `FTP_PASSWORD` sont bien configurées dans GitLab CI/CD.
2. Assurez-vous que le serveur accepte les connexions passives (configuré par défaut dans le script lftp).
3. En cas d'erreur 404 après déploiement, vérifiez que le fichier `.htaccess` est bien présent à la racine du serveur.

Une dernière chose : Souhaites-tu que je te montre comment ajouter une notification (par email ou Slack) pour être prévenu automatiquement quand le déploiement réussit ?

(6-6/13)