Revision b8ad0125
Added by chrisker85 2 months ago
| README.md | ||
|---|---|---|
|
# davca-cm
|
||
|
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
|
||
|
|
||
|
## Getting started
|
||
|
Ce guide détaille les étapes pour installer, configurer, optimiser et déployer l'application sur un serveur de production.
|
||
|
|
||
|
To make it easy for you to get started with GitLab, here's a list of recommended next steps.
|
||
|
## 📁 Structure du Projet
|
||
|
|
||
|
Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
|
||
|
* `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).
|
||
|
|
||
|
## Add your files
|
||
|
---
|
||
|
|
||
|
* [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
|
||
|
* [Add files using the command line](https://docs.gitlab.com/topics/git/add_files/#add-files-to-a-git-repository) or push an existing Git repository with the following command:
|
||
|
## ⚙️ 1. Installation et Configuration
|
||
|
|
||
|
### Prérequis
|
||
|
|
||
|
* **Node.js** : v16+ recommandé.
|
||
|
* **Gestionnaire de paquets** : npm (inclus avec Node).
|
||
|
|
||
|
### Installation
|
||
|
|
||
|
```bash
|
||
|
# Installation des dépendances
|
||
|
npm install
|
||
|
|
||
|
```
|
||
|
|
||
|
### Variables d'environnement
|
||
|
|
||
|
Créez un fichier `.env.local` à la racine pour vos configurations locales :
|
||
|
|
||
|
```env
|
||
|
VUE_APP_API_URL=https://api.monsite.com
|
||
|
|
||
|
```
|
||
|
|
||
|
---
|
||
|
|
||
|
## 💻 2. Développement Local
|
||
|
|
||
|
Pour lancer l'application en mode développement (avec rafraîchissement automatique) :
|
||
|
|
||
|
```bash
|
||
|
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.
|
||
|
|
||
|
```bash
|
||
|
npm run build
|
||
|
|
||
|
```
|
||
|
cd existing_repo
|
||
|
git remote add origin https://gitlab.com/tube4j/davca/davca-cm.git
|
||
|
git branch -M main
|
||
|
git push -uf origin main
|
||
|
|
||
|
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 :
|
||
|
|
||
|
```apache
|
||
|
<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>
|
||
|
|
||
|
```
|
||
|
|
||
|
## Integrate with your tools
|
||
|
---
|
||
|
|
||
|
* [Set up project integrations](https://gitlab.com/tube4j/davca/davca-cm/-/settings/integrations)
|
||
|
## 🧪 Maintenance et Qualité
|
||
|
|
||
|
## Collaborate with your team
|
||
|
| Action | Commande |
|
||
|
| --- | --- |
|
||
|
| **Linter** | `npm run lint` (Nettoyage automatique du code) |
|
||
|
| **Tests** | `npm run test:unit` (Vérification des composants) |
|
||
|
|
||
|
* [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
|
||
|
* [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
|
||
|
* [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
|
||
|
* [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
|
||
|
* [Set auto-merge](https://docs.gitlab.com/user/project/merge_requests/auto_merge/)
|
||
|
---
|
||
|
|
||
|
## Test and Deploy
|
||
|
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).
|
||
|
|
||
|
Use the built-in continuous integration in GitLab.
|
||
|
Voici comment configurer cela.
|
||
|
|
||
|
* [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/)
|
||
|
* [Analyze your code for known vulnerabilities with Static Application Security Testing (SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
|
||
|
* [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
|
||
|
* [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
|
||
|
* [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
|
||
|
---
|
||
|
|
||
|
***
|
||
|
## 🤖 5. Automatisation avec GitLab CI/CD
|
||
|
|
||
|
# Editing this README
|
||
|
Pour mettre cela en place, tu dois créer un fichier nommé `.gitlab-ci.yml` à la racine de ton projet.
|
||
|
|
||
|
When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thanks to [makeareadme.com](https://www.makeareadme.com/) for this template.
|
||
|
### Étape A : Préparer les variables secrètes
|
||
|
|
||
|
## Suggestions for a good README
|
||
|
Ne mets jamais tes identifiants FTP dans ton code. Va dans ton projet GitLab :
|
||
|
|
||
|
Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
|
||
|
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`).
|
||
|
|
||
|
## Name
|
||
|
Choose a self-explaining name for your project.
|
||
|
|
||
|
## Description
|
||
|
Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
|
||
|
|
||
|
## Badges
|
||
|
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
|
||
|
### Étape B : Le fichier `.gitlab-ci.yml`
|
||
|
|
||
|
## Visuals
|
||
|
Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
|
||
|
Copie ce contenu dans ton fichier :
|
||
|
|
||
|
## Installation
|
||
|
Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
|
||
|
```yaml
|
||
|
stages:
|
||
|
- build
|
||
|
- deploy
|
||
|
|
||
|
## Usage
|
||
|
Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
|
||
|
# 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
|
||
|
|
||
|
## Support
|
||
|
Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
|
||
|
# 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
|
||
|
|
||
|
## Roadmap
|
||
|
If you have ideas for releases in the future, it is a good idea to list them in the README.
|
||
|
```
|
||
|
|
||
|
## Contributing
|
||
|
State if you are open to contributions and what your requirements are for accepting them.
|
||
|
---
|
||
|
|
||
|
For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
|
||
|
## 📝 Mise à jour du README.md (Section CI/CD)
|
||
|
|
||
|
You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
|
||
|
Ajoute cette section à ton fichier `README.md` pour que tes collaborateurs (ou ton futur toi) sachent comment le déploiement fonctionne :
|
||
|
|
||
|
## Authors and acknowledgment
|
||
|
Show your appreciation to those who have contributed to the project.
|
||
|
```markdown
|
||
|
## 🤖 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 :
|
||
|
|
||
|
```bash
|
||
|
# 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 :
|
||
|
|
||
|
```markdown
|
||
|
### 🔧 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.
|
||
|
|
||
|
```
|
||
|
|
||
|
## License
|
||
|
For open source projects, say how it is licensed.
|
||
|
---
|
||
|
|
||
|
## Project status
|
||
|
If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
|
||
|
**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 ?
|
||
change