docs: ajouter documentation complète du projet dans docs/
This commit is contained in:
syoul
39
docs/README.md
Normal file
39
docs/README.md
Normal file
@@ -0,0 +1,39 @@
|
|||||||
|
# Documentation AJR Technology Radar
|
||||||
|
|
||||||
|
Bienvenue dans la documentation du projet AJR Technology Radar (CoeurBox).
|
||||||
|
|
||||||
|
## Vue d'ensemble
|
||||||
|
|
||||||
|
Le Technology Radar AJR est une application web interactive qui présente les technologies, outils, méthodes et plateformes utilisées et évaluées par AJR. Il est basé sur le framework [aoe_technology_radar](https://github.com/AOEpeople/aoe_technology_radar).
|
||||||
|
|
||||||
|
Le radar est organisé en quatre quadrants et quatre anneaux (rings) pour classifier chaque technologie selon son niveau d'adoption et sa catégorie.
|
||||||
|
|
||||||
|
## Structure de la documentation
|
||||||
|
|
||||||
|
Cette documentation est organisée en plusieurs sections :
|
||||||
|
|
||||||
|
- **[Architecture](./architecture.md)** - Structure du projet, organisation des fichiers et composants
|
||||||
|
- **[Configuration](./configuration.md)** - Configuration du radar, quadrants, anneaux et personnalisation
|
||||||
|
- **[Développement](./developpement.md)** - Guide pour développer et tester localement
|
||||||
|
- **[Déploiement](./deploiement.md)** - Instructions pour déployer le radar en production
|
||||||
|
- **[Contribution](./contribution.md)** - Guide pour ajouter de nouvelles technologies au radar
|
||||||
|
|
||||||
|
## Liens utiles
|
||||||
|
|
||||||
|
- **Radar en ligne** : https://www.coeurbox.syoul.fr
|
||||||
|
- **Dépôt Git** : https://git.open.us.org/AJR/TechradarDev
|
||||||
|
- **Framework source** : https://github.com/AOEpeople/aoe_technology_radar
|
||||||
|
|
||||||
|
## Démarrage rapide
|
||||||
|
|
||||||
|
Pour démarrer rapidement le projet en local :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
npm run serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Puis ouvrir http://localhost:3000/techradar dans votre navigateur.
|
||||||
|
|
||||||
|
Pour plus de détails, consultez le [guide de développement](./developpement.md).
|
||||||
|
|
||||||
98
docs/architecture.md
Normal file
98
docs/architecture.md
Normal file
@@ -0,0 +1,98 @@
|
|||||||
|
# Architecture du projet
|
||||||
|
|
||||||
|
## Vue d'ensemble
|
||||||
|
|
||||||
|
Le projet AJR Technology Radar est une application web statique construite avec le framework `aoe_technology_radar`. L'application génère un site web interactif à partir de fichiers Markdown organisés par dates de release.
|
||||||
|
|
||||||
|
## Structure des répertoires
|
||||||
|
|
||||||
|
```
|
||||||
|
TechradarDev/
|
||||||
|
├── radar/ # Contenu du radar organisé par dates
|
||||||
|
│ ├── 2017-03-01/ # Release de mars 2017
|
||||||
|
│ ├── 2018-03-01/ # Release de mars 2018
|
||||||
|
│ ├── 2019-11-01/ # Release de novembre 2019
|
||||||
|
│ ├── 2021-07-01/ # Release de juillet 2021
|
||||||
|
│ ├── 2022-03-28/ # Release de mars 2022
|
||||||
|
│ ├── 2023-02-23/ # Release de février 2023
|
||||||
|
│ ├── 2023-11-01/ # Release de novembre 2023
|
||||||
|
│ ├── 2024-07-10/ # Release de juillet 2024
|
||||||
|
│ └── 2025-04-10/ # Release d'avril 2025 (actuelle)
|
||||||
|
├── public/ # Fichiers statiques publics
|
||||||
|
│ ├── images/ # Images utilisées dans les descriptions
|
||||||
|
│ ├── logo.svg # Logo AJR
|
||||||
|
│ ├── favicon.ico # Icône du site
|
||||||
|
│ └── robots.txt # Configuration pour les robots
|
||||||
|
├── docker/ # Configuration Docker pour le déploiement
|
||||||
|
│ ├── Dockerfile # Image Docker de production
|
||||||
|
│ ├── docker-compose.yml # Configuration Docker Compose
|
||||||
|
│ ├── docker-compose.labels.yml # Labels pour le déploiement
|
||||||
|
│ └── docker-compose.local.yml # Configuration locale
|
||||||
|
├── docs/ # Documentation du projet
|
||||||
|
├── config.json # Configuration principale du radar
|
||||||
|
├── custom.css # Styles personnalisés
|
||||||
|
├── about.md # Page "À propos" du radar
|
||||||
|
├── package.json # Dépendances Node.js
|
||||||
|
├── Dockerfile # Dockerfile alternatif (racine)
|
||||||
|
├── docker-compose.yml # Docker Compose alternatif (racine)
|
||||||
|
├── docker-entrypoint.sh # Script d'entrée Docker
|
||||||
|
└── .drone.yml # Configuration CI/CD Drone
|
||||||
|
```
|
||||||
|
|
||||||
|
## Format des fichiers radar
|
||||||
|
|
||||||
|
Chaque technologie (blip) est définie dans un fichier Markdown avec un en-tête YAML front matter :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Nom de la technologie"
|
||||||
|
ring: adopt|trial|assess|hold
|
||||||
|
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
|
||||||
|
tags: [tag1, tag2]
|
||||||
|
---
|
||||||
|
|
||||||
|
Description de la technologie en Markdown.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Métadonnées
|
||||||
|
|
||||||
|
- **title** : Nom de la technologie
|
||||||
|
- **ring** : Anneau du radar (adopt, trial, assess, hold)
|
||||||
|
- **quadrant** : Quadrant du radar
|
||||||
|
- **tags** : Tags pour le filtrage (optionnel)
|
||||||
|
|
||||||
|
## Flux de traitement
|
||||||
|
|
||||||
|
1. **Lecture des fichiers** : Le framework lit tous les fichiers `.md` dans les dossiers `radar/`
|
||||||
|
2. **Parsing** : Extraction des métadonnées YAML et du contenu Markdown
|
||||||
|
3. **Génération** : Création d'une application React statique
|
||||||
|
4. **Build** : Compilation en fichiers HTML/CSS/JS statiques
|
||||||
|
5. **Serve** : Service via un serveur web statique
|
||||||
|
|
||||||
|
## Dépendances principales
|
||||||
|
|
||||||
|
- **aoe_technology_radar** : Framework principal (dépendance GitHub)
|
||||||
|
- **Node.js** : Runtime JavaScript (version 20+)
|
||||||
|
- **npm** : Gestionnaire de paquets
|
||||||
|
|
||||||
|
## Configuration
|
||||||
|
|
||||||
|
La configuration principale se trouve dans `config.json` et définit :
|
||||||
|
- Les quadrants et leurs descriptions
|
||||||
|
- Les anneaux (rings) et leurs significations
|
||||||
|
- Les couleurs et le style
|
||||||
|
- Les options d'affichage
|
||||||
|
- Les métadonnées du site
|
||||||
|
|
||||||
|
Voir [configuration.md](./configuration.md) pour plus de détails.
|
||||||
|
|
||||||
|
## Build et déploiement
|
||||||
|
|
||||||
|
Le projet utilise deux commandes principales :
|
||||||
|
- `npm run build` : Génère les fichiers statiques
|
||||||
|
- `npm run serve` : Lance un serveur de développement
|
||||||
|
|
||||||
|
Le déploiement se fait via Docker avec plusieurs configurations selon l'environnement.
|
||||||
|
|
||||||
|
Voir [deploiement.md](./deploiement.md) pour plus de détails.
|
||||||
|
|
||||||
173
docs/configuration.md
Normal file
173
docs/configuration.md
Normal file
@@ -0,0 +1,173 @@
|
|||||||
|
# Configuration
|
||||||
|
|
||||||
|
## Fichier config.json
|
||||||
|
|
||||||
|
Le fichier `config.json` contient toute la configuration du radar. Il définit l'apparence, le comportement et la structure du radar.
|
||||||
|
|
||||||
|
## Structure de configuration
|
||||||
|
|
||||||
|
### Paramètres de base
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"basePath": "/",
|
||||||
|
"baseUrl": "",
|
||||||
|
"editUrl": "https://git.open.us.org/syoul/TechradarDev/_edit/main/radar/{release}/{id}.md",
|
||||||
|
"logoFile": "logo.svg"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- **basePath** : Chemin de base pour l'application (modifié dynamiquement en Docker)
|
||||||
|
- **baseUrl** : URL de base du site
|
||||||
|
- **editUrl** : Template d'URL pour éditer les fichiers (utilise {release} et {id})
|
||||||
|
- **logoFile** : Nom du fichier logo dans `public/`
|
||||||
|
|
||||||
|
### Options d'affichage (toggles)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"toggles": {
|
||||||
|
"showChart": true,
|
||||||
|
"showTagFilter": true,
|
||||||
|
"showQuadrantList": true,
|
||||||
|
"showEmptyRings": false
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- **showChart** : Affiche le graphique radar interactif
|
||||||
|
- **showTagFilter** : Active le filtre par tags
|
||||||
|
- **showQuadrantList** : Affiche la liste des quadrants
|
||||||
|
- **showEmptyRings** : Affiche les anneaux vides
|
||||||
|
|
||||||
|
### Sections
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"sections": ["radar", "tags", "list"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Définit l'ordre des sections dans l'interface.
|
||||||
|
|
||||||
|
### Couleurs
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"colors": {
|
||||||
|
"foreground": "#fff",
|
||||||
|
"background": "#173d7a",
|
||||||
|
"highlight": "#029df7",
|
||||||
|
"content": "#fff",
|
||||||
|
"text": "#575757",
|
||||||
|
"link": "#029df7",
|
||||||
|
"border": "rgba(255, 255, 255, 0.1)",
|
||||||
|
"tag": "rgba(255, 255, 255, 0.1)"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Personnalisation des couleurs de l'interface.
|
||||||
|
|
||||||
|
### Quadrants
|
||||||
|
|
||||||
|
Les quadrants définissent les quatre catégories principales :
|
||||||
|
|
||||||
|
1. **Languages & Frameworks** : Langages et frameworks de développement
|
||||||
|
2. **Methods & Patterns** : Méthodes et patterns de développement
|
||||||
|
3. **Platforms & Operations** : Plateformes et opérations
|
||||||
|
4. **Tools** : Outils de développement
|
||||||
|
|
||||||
|
Chaque quadrant a :
|
||||||
|
- **id** : Identifiant unique
|
||||||
|
- **title** : Titre affiché
|
||||||
|
- **description** : Description du quadrant
|
||||||
|
- **color** : Couleur associée
|
||||||
|
|
||||||
|
### Anneaux (Rings)
|
||||||
|
|
||||||
|
Les anneaux classifient les technologies selon leur niveau d'adoption :
|
||||||
|
|
||||||
|
1. **Adopt** : Recommandé, utilisé avec succès
|
||||||
|
2. **Trial** : À essayer, prometteur
|
||||||
|
3. **Assess** : À évaluer, à surveiller
|
||||||
|
4. **Hold** : À éviter, à remplacer
|
||||||
|
|
||||||
|
Chaque anneau a :
|
||||||
|
- **id** : Identifiant unique
|
||||||
|
- **title** : Titre affiché
|
||||||
|
- **description** : Description de l'anneau
|
||||||
|
- **color** : Couleur associée
|
||||||
|
- **radius** : Rayon dans le graphique (0-1)
|
||||||
|
- **strokeWidth** : Épaisseur du trait
|
||||||
|
|
||||||
|
### Flags (Drapeaux)
|
||||||
|
|
||||||
|
Les flags marquent les changements entre versions :
|
||||||
|
|
||||||
|
- **new** : Nouveau dans cette version
|
||||||
|
- **changed** : Modifié récemment
|
||||||
|
- **default** : Inchangé
|
||||||
|
|
||||||
|
### Graphique
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"chart": {
|
||||||
|
"size": 800,
|
||||||
|
"blipSize": 12
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- **size** : Taille du graphique en pixels
|
||||||
|
- **blipSize** : Taille des points (blips) sur le graphique
|
||||||
|
|
||||||
|
### Labels (Textes)
|
||||||
|
|
||||||
|
Les labels permettent de personnaliser tous les textes de l'interface, notamment :
|
||||||
|
- Titre du site
|
||||||
|
- Textes des pages
|
||||||
|
- Messages d'erreur
|
||||||
|
- Placeholders
|
||||||
|
- Footer
|
||||||
|
|
||||||
|
## Personnalisation
|
||||||
|
|
||||||
|
### Modifier les couleurs
|
||||||
|
|
||||||
|
Éditez la section `colors` dans `config.json` avec les codes hexadécimaux souhaités.
|
||||||
|
|
||||||
|
### Ajouter un quadrant
|
||||||
|
|
||||||
|
Ajoutez un nouvel objet dans le tableau `quadrants` avec les propriétés requises.
|
||||||
|
|
||||||
|
### Modifier les descriptions
|
||||||
|
|
||||||
|
Les descriptions des quadrants et anneaux peuvent être modifiées directement dans `config.json`.
|
||||||
|
|
||||||
|
### Styles personnalisés
|
||||||
|
|
||||||
|
Le fichier `custom.css` permet d'ajouter des styles CSS personnalisés qui seront appliqués à l'application.
|
||||||
|
|
||||||
|
## Variables d'environnement
|
||||||
|
|
||||||
|
En Docker, la variable `BASE_PATH` peut être utilisée pour modifier dynamiquement le `basePath` dans `config.json`. Le script `docker-entrypoint.sh` effectue cette modification au démarrage.
|
||||||
|
|
||||||
|
## Tags disponibles
|
||||||
|
|
||||||
|
Les tags suivants sont établis pour classifier les technologies :
|
||||||
|
|
||||||
|
- architecture
|
||||||
|
- security
|
||||||
|
- devops
|
||||||
|
- frontend
|
||||||
|
- agile
|
||||||
|
- coding
|
||||||
|
- quality assurance
|
||||||
|
- ci/cd
|
||||||
|
- ux/ui
|
||||||
|
- documentation
|
||||||
|
|
||||||
|
Les tags sont utilisés dans les fichiers Markdown des blips et permettent le filtrage dans l'interface.
|
||||||
|
|
||||||
200
docs/contribution.md
Normal file
200
docs/contribution.md
Normal file
@@ -0,0 +1,200 @@
|
|||||||
|
# Guide de contribution
|
||||||
|
|
||||||
|
## Vue d'ensemble
|
||||||
|
|
||||||
|
Ce guide explique comment contribuer au Technology Radar AJR en ajoutant, modifiant ou supprimant des technologies (blips).
|
||||||
|
|
||||||
|
## Processus de contribution
|
||||||
|
|
||||||
|
### 1. Préparer l'environnement
|
||||||
|
|
||||||
|
Voir le [guide de développement](./developpement.md) pour l'installation et la configuration de l'environnement local.
|
||||||
|
|
||||||
|
### 2. Créer une branche
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git checkout -b feature/nom-de-la-technologie
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Ajouter ou modifier un blip
|
||||||
|
|
||||||
|
#### Ajouter un nouveau blip
|
||||||
|
|
||||||
|
1. Créer un fichier Markdown dans le dossier de release approprié :
|
||||||
|
```
|
||||||
|
radar/2025-04-10/nom-technologie.md
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Utiliser le format standard :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Nom de la technologie"
|
||||||
|
ring: adopt|trial|assess|hold
|
||||||
|
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
|
||||||
|
tags: [tag1, tag2]
|
||||||
|
---
|
||||||
|
|
||||||
|
Description de la technologie.
|
||||||
|
|
||||||
|
## Avantages
|
||||||
|
|
||||||
|
- Point 1
|
||||||
|
- Point 2
|
||||||
|
|
||||||
|
## Cas d'usage AJR
|
||||||
|
|
||||||
|
Description de l'utilisation chez AJR.
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Modifier un blip existant
|
||||||
|
|
||||||
|
1. Localiser le fichier dans le dossier de release
|
||||||
|
2. Modifier le contenu ou les métadonnées
|
||||||
|
3. Si vous changez le ring ou le quadrant, documenter la raison
|
||||||
|
|
||||||
|
#### Supprimer un blip
|
||||||
|
|
||||||
|
Si une technologie doit être retirée du radar :
|
||||||
|
- La déplacer vers le ring "hold" plutôt que de la supprimer
|
||||||
|
- Ou la supprimer complètement si elle n'est plus pertinente
|
||||||
|
|
||||||
|
### 4. Tester localement
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Vérifier :
|
||||||
|
- L'affichage correct du blip
|
||||||
|
- Le positionnement dans le bon quadrant et ring
|
||||||
|
- La lisibilité du contenu
|
||||||
|
- Le fonctionnement des tags
|
||||||
|
|
||||||
|
### 5. Commiter les changements
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git add radar/2025-04-10/nom-technologie.md
|
||||||
|
git commit -m "feat: ajouter [technologie] au quadrant [quadrant]"
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Pousser et créer une pull request
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git push origin feature/nom-de-la-technologie
|
||||||
|
```
|
||||||
|
|
||||||
|
Créer une pull request sur le dépôt Git.
|
||||||
|
|
||||||
|
## Guidelines de contenu
|
||||||
|
|
||||||
|
### Choix du ring
|
||||||
|
|
||||||
|
- **Adopt** : Technologie utilisée avec succès dans plusieurs projets, stable et recommandée
|
||||||
|
- **Trial** : Technologie testée avec succès, à considérer pour de nouveaux projets
|
||||||
|
- **Assess** : Technologie prometteuse, à évaluer selon les besoins
|
||||||
|
- **Hold** : Technologie à éviter ou à remplacer, mais peut être maintenue dans les projets existants
|
||||||
|
|
||||||
|
### Choix du quadrant
|
||||||
|
|
||||||
|
- **Languages & Frameworks** : Langages de programmation et frameworks de développement
|
||||||
|
- **Methods & Patterns** : Méthodologies, patterns architecturaux, pratiques de développement
|
||||||
|
- **Platforms & Operations** : Plateformes cloud, infrastructure, services opérationnels
|
||||||
|
- **Tools** : Outils de développement, utilitaires, logiciels
|
||||||
|
|
||||||
|
### Tags
|
||||||
|
|
||||||
|
Utiliser les tags établis :
|
||||||
|
- architecture
|
||||||
|
- security
|
||||||
|
- devops
|
||||||
|
- frontend
|
||||||
|
- agile
|
||||||
|
- coding
|
||||||
|
- quality assurance
|
||||||
|
- ci/cd
|
||||||
|
- ux/ui
|
||||||
|
- documentation
|
||||||
|
|
||||||
|
Ajouter plusieurs tags si la technologie couvre plusieurs domaines.
|
||||||
|
|
||||||
|
### Qualité du contenu
|
||||||
|
|
||||||
|
- **Clarté** : Description claire et concise
|
||||||
|
- **Pertinence** : Focus sur l'utilisation chez AJR
|
||||||
|
- **Objectivité** : Présenter les avantages et inconvénients
|
||||||
|
- **Concision** : Rester factuel et éviter les détails superflus
|
||||||
|
|
||||||
|
## Format des commits
|
||||||
|
|
||||||
|
Utiliser des messages de commit clairs :
|
||||||
|
|
||||||
|
```
|
||||||
|
feat: ajouter [technologie] au quadrant [quadrant]
|
||||||
|
fix: corriger la description de [technologie]
|
||||||
|
update: déplacer [technologie] de trial à adopt
|
||||||
|
docs: améliorer la documentation de [technologie]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Créer une nouvelle release
|
||||||
|
|
||||||
|
Quand créer une nouvelle release :
|
||||||
|
|
||||||
|
1. **Périodicité** : Généralement tous les 3-6 mois
|
||||||
|
2. **Changements significatifs** : Plusieurs nouveaux blips ou changements majeurs
|
||||||
|
3. **Événements** : Après des évaluations importantes
|
||||||
|
|
||||||
|
### Processus de release
|
||||||
|
|
||||||
|
1. Créer un nouveau dossier avec la date :
|
||||||
|
```bash
|
||||||
|
mkdir radar/2025-07-15
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Copier les blips pertinents depuis la release précédente
|
||||||
|
|
||||||
|
3. Ajouter les nouveaux blips
|
||||||
|
|
||||||
|
4. Mettre à jour les blips existants si nécessaire
|
||||||
|
|
||||||
|
5. Documenter les changements majeurs
|
||||||
|
|
||||||
|
## Review process
|
||||||
|
|
||||||
|
Les contributions sont revues pour :
|
||||||
|
|
||||||
|
- **Exactitude** : Les informations sont correctes
|
||||||
|
- **Pertinence** : La technologie est pertinente pour AJR
|
||||||
|
- **Format** : Le format Markdown est correct
|
||||||
|
- **Classification** : Le ring et quadrant sont appropriés
|
||||||
|
- **Qualité** : Le contenu est clair et utile
|
||||||
|
|
||||||
|
## Questions fréquentes
|
||||||
|
|
||||||
|
### Puis-je ajouter une technologie que je n'ai pas encore utilisée ?
|
||||||
|
|
||||||
|
Non. Le radar ne contient que des technologies testées au moins une fois par l'équipe.
|
||||||
|
|
||||||
|
### Comment décider entre deux quadrants ?
|
||||||
|
|
||||||
|
Choisir le quadrant le plus approprié. Si c'est ambigu, discuter avec l'équipe.
|
||||||
|
|
||||||
|
### Puis-je modifier un blip d'une release précédente ?
|
||||||
|
|
||||||
|
Généralement non. Les releases précédentes sont figées. Créer un nouveau blip dans la release actuelle si nécessaire.
|
||||||
|
|
||||||
|
### Comment gérer les technologies obsolètes ?
|
||||||
|
|
||||||
|
Les déplacer vers le ring "hold" avec une explication de pourquoi elles ne sont plus recommandées.
|
||||||
|
|
||||||
|
## Ressources
|
||||||
|
|
||||||
|
- [Guide de développement](./developpement.md)
|
||||||
|
- [Configuration](./configuration.md)
|
||||||
|
- [Architecture](./architecture.md)
|
||||||
|
- Framework source : https://github.com/AOEpeople/aoe_technology_radar
|
||||||
|
|
||||||
|
## Contact
|
||||||
|
|
||||||
|
Pour toute question sur les contributions, contacter l'équipe AJR ou ouvrir une issue sur le dépôt Git.
|
||||||
|
|
||||||
239
docs/deploiement.md
Normal file
239
docs/deploiement.md
Normal file
@@ -0,0 +1,239 @@
|
|||||||
|
# Guide de déploiement
|
||||||
|
|
||||||
|
## Vue d'ensemble
|
||||||
|
|
||||||
|
Le projet peut être déployé de plusieurs façons :
|
||||||
|
- Docker Compose (recommandé pour la production)
|
||||||
|
- Docker simple
|
||||||
|
- Build statique avec serveur web
|
||||||
|
|
||||||
|
## Déploiement avec Docker
|
||||||
|
|
||||||
|
### Configuration Docker
|
||||||
|
|
||||||
|
Le projet contient plusieurs configurations Docker :
|
||||||
|
|
||||||
|
- `docker/Dockerfile` : Dockerfile principal avec multi-stage build
|
||||||
|
- `docker/docker-compose.yml` : Configuration de base
|
||||||
|
- `docker/docker-compose.labels.yml` : Labels pour le reverse proxy
|
||||||
|
- `docker/docker-compose.local.yml` : Configuration pour développement local
|
||||||
|
- `Dockerfile` (racine) : Dockerfile alternatif
|
||||||
|
- `docker-compose.yml` (racine) : Docker Compose alternatif
|
||||||
|
|
||||||
|
### Build de l'image Docker
|
||||||
|
|
||||||
|
#### Avec le Dockerfile principal
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd docker
|
||||||
|
docker compose build
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Avec build args
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build \
|
||||||
|
--build-arg BASE_PATH="/techradar" \
|
||||||
|
--build-arg UID=1000 \
|
||||||
|
--build-arg GID=1000 \
|
||||||
|
-f docker/Dockerfile \
|
||||||
|
-t techradar:latest \
|
||||||
|
.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Variables d'environnement
|
||||||
|
|
||||||
|
- **BASE_PATH** : Chemin de base pour l'application (défaut: `/`)
|
||||||
|
- **UID** : User ID pour l'utilisateur dans le conteneur (défaut: 1000)
|
||||||
|
- **GID** : Group ID pour l'utilisateur dans le conteneur (défaut: 1000)
|
||||||
|
|
||||||
|
### Démarrage avec Docker Compose
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd docker
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
L'application sera accessible sur le port 3000.
|
||||||
|
|
||||||
|
### Configuration du basePath
|
||||||
|
|
||||||
|
Le script `docker-entrypoint.sh` modifie dynamiquement le `basePath` dans `config.json` au démarrage du conteneur en utilisant la variable d'environnement `BASE_PATH`.
|
||||||
|
|
||||||
|
## Déploiement statique
|
||||||
|
|
||||||
|
### Build des fichiers statiques
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
Les fichiers sont générés dans le répertoire `build/`.
|
||||||
|
|
||||||
|
### Servir avec un serveur web
|
||||||
|
|
||||||
|
#### Nginx
|
||||||
|
|
||||||
|
```nginx
|
||||||
|
server {
|
||||||
|
listen 80;
|
||||||
|
server_name coeurbox.syoul.fr;
|
||||||
|
root /chemin/vers/build;
|
||||||
|
index index.html;
|
||||||
|
|
||||||
|
location / {
|
||||||
|
try_files $uri $uri/ /index.html;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Apache
|
||||||
|
|
||||||
|
```apache
|
||||||
|
<VirtualHost *:80>
|
||||||
|
ServerName coeurbox.syoul.fr
|
||||||
|
DocumentRoot /chemin/vers/build
|
||||||
|
|
||||||
|
<Directory /chemin/vers/build>
|
||||||
|
Options Indexes FollowSymLinks
|
||||||
|
AllowOverride All
|
||||||
|
Require all granted
|
||||||
|
</Directory>
|
||||||
|
</VirtualHost>
|
||||||
|
```
|
||||||
|
|
||||||
|
## Déploiement avec Drone CI
|
||||||
|
|
||||||
|
Le projet est configuré pour le déploiement automatique via Drone CI (`.drone.yml`).
|
||||||
|
|
||||||
|
### Pipeline de déploiement
|
||||||
|
|
||||||
|
1. **Build** : Construction de l'image Docker
|
||||||
|
2. **Déploiement** : Lancement du conteneur avec Docker Compose
|
||||||
|
3. **Notification** : Envoi d'une notification Telegram
|
||||||
|
|
||||||
|
### Configuration Drone
|
||||||
|
|
||||||
|
Le pipeline utilise :
|
||||||
|
- Variables d'environnement dynamiques basées sur le dépôt Git
|
||||||
|
- Labels pour le reverse proxy (Traefik)
|
||||||
|
- Notifications Telegram en cas de succès/échec
|
||||||
|
|
||||||
|
### Variables d'environnement Drone
|
||||||
|
|
||||||
|
- `DRONE_REPO_OWNER` : Propriétaire du dépôt
|
||||||
|
- `DRONE_REPO_NAME` : Nom du dépôt
|
||||||
|
- `DRONE_COMMIT_BRANCH` : Branche du commit
|
||||||
|
|
||||||
|
Ces variables sont utilisées pour générer le `BASE_PATH` dynamiquement.
|
||||||
|
|
||||||
|
## Déploiement en production
|
||||||
|
|
||||||
|
### Étapes recommandées
|
||||||
|
|
||||||
|
1. **Préparer l'environnement**
|
||||||
|
```bash
|
||||||
|
git clone https://git.open.us.org/AJR/TechradarDev.git
|
||||||
|
cd TechradarDev
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Configurer les variables**
|
||||||
|
- Définir `BASE_PATH` selon votre configuration
|
||||||
|
- Ajuster les ports si nécessaire
|
||||||
|
|
||||||
|
3. **Build et démarrage**
|
||||||
|
```bash
|
||||||
|
cd docker
|
||||||
|
docker compose -f docker-compose.yml -f docker-compose.labels.yml up -d --build
|
||||||
|
```
|
||||||
|
|
||||||
|
4. **Vérifier le déploiement**
|
||||||
|
- Accéder à l'URL configurée
|
||||||
|
- Vérifier les logs : `docker compose logs -f`
|
||||||
|
|
||||||
|
### Reverse proxy
|
||||||
|
|
||||||
|
Le projet est configuré pour fonctionner derrière un reverse proxy (Traefik) via les labels dans `docker-compose.labels.yml`.
|
||||||
|
|
||||||
|
### Sécurité
|
||||||
|
|
||||||
|
- Utiliser HTTPS en production
|
||||||
|
- Configurer les headers de sécurité appropriés
|
||||||
|
- Limiter l'accès si nécessaire
|
||||||
|
- Surveiller les logs
|
||||||
|
|
||||||
|
## Mise à jour
|
||||||
|
|
||||||
|
### Mettre à jour le contenu
|
||||||
|
|
||||||
|
1. Modifier les fichiers dans `radar/`
|
||||||
|
2. Rebuild l'image :
|
||||||
|
```bash
|
||||||
|
docker compose build
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
### Mettre à jour les dépendances
|
||||||
|
|
||||||
|
1. Modifier `package.json` si nécessaire
|
||||||
|
2. Rebuild l'image complète
|
||||||
|
|
||||||
|
## Monitoring
|
||||||
|
|
||||||
|
### Logs Docker
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Voir les logs
|
||||||
|
docker compose logs -f
|
||||||
|
|
||||||
|
# Logs du dernier démarrage
|
||||||
|
docker compose logs --tail=100
|
||||||
|
```
|
||||||
|
|
||||||
|
### Santé de l'application
|
||||||
|
|
||||||
|
L'application expose le port 3000. Vérifier la santé avec :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl http://localhost:3000/techradar
|
||||||
|
```
|
||||||
|
|
||||||
|
## Rollback
|
||||||
|
|
||||||
|
En cas de problème, revenir à une version précédente :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Arrêter le conteneur actuel
|
||||||
|
docker compose down
|
||||||
|
|
||||||
|
# Checkout une version précédente
|
||||||
|
git checkout <commit-hash>
|
||||||
|
|
||||||
|
# Rebuild et redémarrer
|
||||||
|
docker compose build
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Problème de basePath
|
||||||
|
|
||||||
|
Si l'application ne se charge pas correctement :
|
||||||
|
- Vérifier la variable `BASE_PATH`
|
||||||
|
- Vérifier les logs du conteneur
|
||||||
|
- Vérifier la configuration du reverse proxy
|
||||||
|
|
||||||
|
### Problème de permissions
|
||||||
|
|
||||||
|
Si des erreurs de permissions apparaissent :
|
||||||
|
- Vérifier les UID/GID dans le Dockerfile
|
||||||
|
- Vérifier les permissions des volumes montés
|
||||||
|
|
||||||
|
### Problème de build
|
||||||
|
|
||||||
|
Si le build échoue :
|
||||||
|
- Vérifier la version de Node.js
|
||||||
|
- Vérifier les dépendances npm
|
||||||
|
- Nettoyer le cache : `docker system prune -a`
|
||||||
|
|
||||||
189
docs/developpement.md
Normal file
189
docs/developpement.md
Normal file
@@ -0,0 +1,189 @@
|
|||||||
|
# Guide de développement
|
||||||
|
|
||||||
|
## Prérequis
|
||||||
|
|
||||||
|
- **Node.js** : Version 20 ou supérieure
|
||||||
|
- **npm** : Gestionnaire de paquets Node.js
|
||||||
|
- **Git** : Pour cloner et gérer le dépôt
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Cloner le dépôt
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.open.us.org/AJR/TechradarDev.git
|
||||||
|
cd TechradarDev
|
||||||
|
```
|
||||||
|
|
||||||
|
### Installer les dépendances
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install
|
||||||
|
```
|
||||||
|
|
||||||
|
Cette commande installe le framework `aoe_technology_radar` depuis GitHub.
|
||||||
|
|
||||||
|
## Développement local
|
||||||
|
|
||||||
|
### Démarrer le serveur de développement
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run serve
|
||||||
|
```
|
||||||
|
|
||||||
|
Le serveur démarre sur http://localhost:3000/techradar
|
||||||
|
|
||||||
|
### Build de production
|
||||||
|
|
||||||
|
Pour générer les fichiers statiques :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run build
|
||||||
|
```
|
||||||
|
|
||||||
|
Les fichiers générés sont créés dans le répertoire `build/` (généré par le framework).
|
||||||
|
|
||||||
|
## Structure des fichiers radar
|
||||||
|
|
||||||
|
### Créer un nouveau blip
|
||||||
|
|
||||||
|
1. Créer un nouveau fichier Markdown dans le dossier de release approprié :
|
||||||
|
```
|
||||||
|
radar/2025-04-10/nom-technologie.md
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Utiliser le format suivant :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Nom de la technologie"
|
||||||
|
ring: adopt|trial|assess|hold
|
||||||
|
quadrant: languages-and-frameworks|methods-and-patterns|platforms-and-aoe-services|tools
|
||||||
|
tags: [tag1, tag2]
|
||||||
|
---
|
||||||
|
|
||||||
|
Description de la technologie en Markdown.
|
||||||
|
|
||||||
|
## Avantages
|
||||||
|
|
||||||
|
- Point 1
|
||||||
|
- Point 2
|
||||||
|
|
||||||
|
## Cas d'usage
|
||||||
|
|
||||||
|
Description des cas d'usage chez AJR.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Format des métadonnées
|
||||||
|
|
||||||
|
- **title** (obligatoire) : Nom de la technologie
|
||||||
|
- **ring** (obligatoire) : `adopt`, `trial`, `assess`, ou `hold`
|
||||||
|
- **quadrant** (obligatoire) : Un des quatre quadrants définis dans `config.json`
|
||||||
|
- **tags** (optionnel) : Tableau de tags pour le filtrage
|
||||||
|
|
||||||
|
### Exemple complet
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
title: "Docker"
|
||||||
|
ring: trial
|
||||||
|
quadrant: tools
|
||||||
|
tags: [devops, ci/cd]
|
||||||
|
---
|
||||||
|
|
||||||
|
Docker est une plateforme de conteneurisation qui permet de packager des applications avec leurs dépendances.
|
||||||
|
|
||||||
|
## Avantages
|
||||||
|
|
||||||
|
- Isolation des environnements
|
||||||
|
- Portabilité entre environnements
|
||||||
|
- Facilite le déploiement
|
||||||
|
|
||||||
|
## Utilisation chez AJR
|
||||||
|
|
||||||
|
Nous utilisons Docker pour containeriser nos applications et faciliter le déploiement.
|
||||||
|
```
|
||||||
|
|
||||||
|
## Modifier un blip existant
|
||||||
|
|
||||||
|
1. Localiser le fichier dans le dossier de release approprié
|
||||||
|
2. Modifier le contenu Markdown
|
||||||
|
3. Si nécessaire, modifier les métadonnées (ring, quadrant, tags)
|
||||||
|
4. Tester localement avec `npm run serve`
|
||||||
|
|
||||||
|
## Créer une nouvelle release
|
||||||
|
|
||||||
|
1. Créer un nouveau dossier avec la date au format `YYYY-MM-DD` :
|
||||||
|
```bash
|
||||||
|
mkdir radar/2025-07-15
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Copier les blips pertinents depuis la release précédente ou créer de nouveaux blips
|
||||||
|
|
||||||
|
3. Mettre à jour les blips existants si nécessaire
|
||||||
|
|
||||||
|
## Ajouter des images
|
||||||
|
|
||||||
|
1. Placer les images dans `public/images/`
|
||||||
|
2. Référencer dans les fichiers Markdown :
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
## Personnalisation CSS
|
||||||
|
|
||||||
|
Le fichier `custom.css` permet d'ajouter des styles personnalisés. Les styles sont appliqués globalement à l'application.
|
||||||
|
|
||||||
|
## Débogage
|
||||||
|
|
||||||
|
### Vérifier les erreurs de format
|
||||||
|
|
||||||
|
Le framework valide les fichiers Markdown. En cas d'erreur :
|
||||||
|
- Vérifier la syntaxe YAML front matter
|
||||||
|
- Vérifier que les valeurs de `ring` et `quadrant` correspondent aux valeurs définies dans `config.json`
|
||||||
|
- Vérifier la syntaxe Markdown
|
||||||
|
|
||||||
|
### Problèmes courants
|
||||||
|
|
||||||
|
1. **Erreur de parsing YAML** : Vérifier les guillemets et l'indentation
|
||||||
|
2. **Blip non affiché** : Vérifier que le quadrant et le ring sont corrects
|
||||||
|
3. **Images non chargées** : Vérifier le chemin relatif depuis `public/`
|
||||||
|
|
||||||
|
## Workflow recommandé
|
||||||
|
|
||||||
|
1. Créer une branche Git pour vos modifications
|
||||||
|
2. Ajouter/modifier les fichiers radar
|
||||||
|
3. Tester localement avec `npm run serve`
|
||||||
|
4. Vérifier l'affichage et le formatage
|
||||||
|
5. Commiter et pousser les changements
|
||||||
|
6. Créer une pull request si applicable
|
||||||
|
|
||||||
|
## Commandes utiles
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Installer les dépendances
|
||||||
|
npm install
|
||||||
|
|
||||||
|
# Démarrer le serveur de développement
|
||||||
|
npm run serve
|
||||||
|
|
||||||
|
# Build de production
|
||||||
|
npm run build
|
||||||
|
|
||||||
|
# Vérifier les fichiers modifiés
|
||||||
|
git status
|
||||||
|
|
||||||
|
# Voir les différences
|
||||||
|
git diff
|
||||||
|
```
|
||||||
|
|
||||||
|
## Intégration continue
|
||||||
|
|
||||||
|
Le projet utilise Drone CI pour l'intégration continue. Voir `.drone.yml` pour la configuration.
|
||||||
|
|
||||||
|
Les builds automatiques :
|
||||||
|
- Construisent l'image Docker
|
||||||
|
- Déploient sur l'environnement de test
|
||||||
|
- Envoient des notifications Telegram
|
||||||
|
|
||||||
Reference in New Issue
Block a user