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