AJR/TechradarDev
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

refactor: réorganiser la documentation en séparant app et data

Browse Source 
- Création de docs/app/ pour la documentation de l'application
- Création de docs/data/ pour les données utilisées par l'application
- Déplacement de la documentation technique vers docs/app/
- Déplacement des données métier vers docs/data/
- Mise à jour de tous les liens et références dans les fichiers
- Mise à jour des scripts (extract-technologies.js, analyze-business-metrics.js)
- Mise à jour des fichiers JavaScript (custom.js, strategie-link.js)
- Création de README.md dans docs/, docs/app/ et docs/data/
- Mise à jour du Readme.md principal avec les nouveaux chemins
This commit is contained in:
syoul
2025-12-03 14:35:36 +01:00
parent 6add0ece80
commit 055e4a9281
21 changed files with 219 additions and 92 deletions
Download Patch File Download Diff File Expand all files Collapse all files

64
docs/app/README.md Normal file
View File

@@ -0,0 +1,64 @@
# 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
### Données du Radar Technologique Laplank
Les données utilisées par l'application sont dans le dossier [`../data/`](../data/) :
- **[Technologies Duniter](../data/technologies-duniter.md)** - Liste des technologies de l'écosystème Duniter/Ğ1
- **[Profil Team](../data/profil-team.md)** - Profils et compétences des membres de l'équipe
- **[Stratégie d'Évolution Technique](../data/strategie-evolution-technique.md)** - Vision et roadmap technique
- **[Stratégie Business](../data/strategie-business.md)** - Analyse stratégique business
- **[Analyse Stratégique](../data/analyse-strategique.md)** - Rapport d'analyse généré automatiquement
## 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
### Radar Principal
Pour démarrer rapidement le radar principal en local :
```bash
npm install
npm run serve
```
Puis ouvrir http://localhost:3000/techradar dans votre navigateur.
### Radar Technologique Laplank
Pour démarrer le radar technologique Laplank en local :
```bash
npm install
npm run serve-business
```
Le serveur démarre sur http://localhost:3006
**Note** : Le radar technologique Laplank est protégé par un mot de passe (`laplank-radar`).
Pour plus de détails, consultez le [guide de développement](./developpement.md) et le [guide du radar technologique Laplank](./guide-radar-business.md).

138
docs/app/architecture.md Normal file
View File

@@ -0,0 +1,138 @@
# 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 principal 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)
├── radar-business/ # Contenu du radar business
│ ├── 2025-01-15/ # Release business de janvier 2025
│ ├── config-business.json # Configuration du radar business
│ ├── FORMAT-BLIP.md # Format des blips business
│ └── README.md # Documentation du radar business
├── 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
│ └── strategie-script.js # Script pour les pages de stratégie dynamiques
├── scripts/ # Scripts utilitaires
│ ├── serve-business.sh # Script pour servir le radar business en local
│ ├── start-business.sh # Script de démarrage pour Docker
│ ├── extract-technologies.js # Extraction des technologies depuis la doc
│ └── analyze-business-metrics.js # Analyse des métriques business
├── 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
├── config.json.backup # Backup de la config (généré par serve-business.sh)
├── custom.css # Styles personnalisés
├── about.md # Page "À propos" du radar
├── package.json # Dépendances Node.js
├── Dockerfile # Dockerfile alternatif (racine)
├── Dockerfile.business # Dockerfile pour le radar business
├── docker-compose.yml # Docker Compose alternatif (racine)
├── docker-compose.business.yml # Docker Compose pour le radar business
├── 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.
## Radar Technologique Laplank
Le Radar Technologique Laplank est un tech radar classique avec :
- **Configuration spécifique** : `radar-business/config-business.json`
- **Quadrants business** : Technologies Différenciantes, Commodité, Risque, Émergentes
- **Anneaux classiques** : Hold, Assess, Trial, Adopt
- **Historique par release** : Organisation des technologies par date (radar-business/YYYY-MM-DD/)
- **Pages de stratégie** : Pages dynamiques générées via `public/strategie-script.js`
- **Protection par mot de passe** : Authentification client-side (mot de passe : `laplank-radar`)
- **Base path** : `/` (racine, pas de sous-chemin)
### Scripts de stratégie
Le fichier `public/strategie-script.js` contient :
- La logique de protection par mot de passe
- La conversion Markdown vers HTML pour les pages de stratégie
- La gestion de la navigation dans le header
- Le contenu des trois pages de stratégie :
- Stratégie d'Évolution Technique
- Stratégie Business
- Opportunités DataViz Expert
## Build et déploiement
Le projet utilise plusieurs commandes :
- `npm run build` : Génère les fichiers statiques du radar principal
- `npm run serve` : Lance un serveur de développement du radar principal (port 3000)
- `npm run serve-business` : Lance un serveur de développement du radar business (port 3006)
Le déploiement se fait via Docker avec plusieurs configurations selon l'environnement :
- **Radar principal** : Via `docker/Dockerfile` ou `Dockerfile`
- **Radar Technologique Laplank** : Via `Dockerfile.business` et `docker-compose.business.yml` (Portainer)
Voir [deploiement.md](./deploiement.md) pour plus de détails.

196
docs/app/configuration.md Normal file
View File

@@ -0,0 +1,196 @@
# 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",
"jsFile": "strategie-script.js"
}
```
- **basePath** : Chemin de base pour l'application (vide `""` pour servir à la racine `/`)
- **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/`
- **jsFile** : Fichier JavaScript personnalisé à charger (optionnel, utilisé pour le radar business)
### 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.
## Configuration du Radar Technologique Laplank
Le Radar Technologique Laplank utilise une configuration spécifique dans `radar-business/config-business.json` :
### Différences principales
- **basePath** : `""` (vide) pour servir à la racine
- **jsFile** : `"strategie-script.js"` pour charger le script de stratégie
- **Quadrants business** : Technologies Différenciantes, Commodité, Risque, Émergentes
- **Anneaux classiques** : Hold, Assess, Trial, Adopt
- **Couleurs** : Thème vert (`#1a4d3a` pour le background, `#2ecc71` pour les accents)
### Script de stratégie
Le fichier `public/strategie-script.js` est chargé automatiquement et fournit :
- Protection par mot de passe (authentification client-side)
- Pages de stratégie dynamiques (Markdown converti en HTML)
- Navigation dans le header
## 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.
Pour le Radar Technologique Laplank, le `basePath` est fixé à `""` (vide) dans `config-business.json` pour servir l'application à la racine.
## 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/app/contribution.md Normal file
View 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.

295
docs/app/deploiement.md Normal file
View File

@@ -0,0 +1,295 @@
# 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
- Portainer (pour le Radar Business)
## 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
- `Dockerfile.business` : Dockerfile spécifique pour le Radar Business
- `docker-compose.business.yml` : Docker Compose pour le Radar Business (Portainer)
### 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 du Radar Technologique Laplank avec Portainer
Le Radar Technologique Laplank est déployé via Portainer en utilisant une stack Docker Compose.
### Configuration Portainer
1. **Créer une nouvelle stack** dans Portainer
2. **Nom de la stack** : `laplank-radar-business` (ou autre nom)
3. **Méthode** : Git Repository
4. **Repository URL** : URL du dépôt Git (ex: `https://git.open.us.org/AJR/TechradarDev.git`)
5. **Branch** : `dev-biz` (ou la branche appropriée)
6. **Compose path** : `docker-compose.business.yml`
### Configuration Docker Compose Laplank
Le fichier `docker-compose.business.yml` configure :
- **Port** : 3006 (mappé depuis le port 3000 du conteneur)
- **Image** : Construite depuis `Dockerfile.business`
- **Environnement** : `NODE_ENV=production`
- **Restart policy** : `unless-stopped`
### Dockerfile Business
Le `Dockerfile.business` :
- Utilise Node.js 20 Alpine
- Configure les variables d'environnement pour désactiver Husky
- Installe les dépendances avec `--ignore-scripts`
- Patche le package `aoe_technology_radar` pour inclure `gray-matter`
- Pré-installe `.techradar` pendant le build
- Applique la configuration business (`config-business.json`)
- Expose le port 3000
- Démarre via `scripts/start-business.sh`
### Authentification Git pour Portainer
Si le dépôt est privé, utiliser un **Personal Access Token** (Gitea) :
1. Créer un token dans Gitea avec les permissions de lecture
2. Utiliser l'URL : `https://<token>@git.open.us.org/AJR/TechradarDev.git`
### Mise à jour
Pour mettre à jour le Radar Technologique Laplank dans Portainer :
1. **Pull latest image** : Dans Portainer, utiliser "Pull latest image"
2. **Rebuild** : Ou reconstruire la stack depuis Git
## 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
**Radar Principal** : Expose le port 3000. Vérifier avec :
```bash
curl http://localhost:3000/techradar
```
**Radar Technologique Laplank** : Expose le port 3006 (mappé depuis 3000). Vérifier avec :
```bash
curl http://localhost:3006/
```
Note : Le Radar Technologique Laplank est protégé par un mot de passe, donc la réponse peut être l'écran d'authentification.
## 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`

205
docs/app/developpement.md Normal file
View File

@@ -0,0 +1,205 @@
# 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 (Radar Principal)
```bash
npm run serve
```
Le serveur démarre sur http://localhost:3000/techradar
### Démarrer le serveur de développement (Radar Business)
```bash
npm run serve-business
```
Le serveur démarre sur http://localhost:3006
**Note importante** : Le script `serve-business.sh` :
- Sauvegarde temporairement `config.json` et le dossier `radar/`
- Copie `radar-business/config-business.json` vers `config.json`
- Copie `radar-business/2025-01-15/` vers `radar/`
- Restaure la configuration originale à la sortie (Ctrl+C)
Le Radar Technologique Laplank est protégé par un mot de passe : `laplank-radar`
### 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
![Description](images/nom-image.png)
```
## 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

249
docs/app/guide-radar-business.md Normal file
View File

@@ -0,0 +1,249 @@
# Guide d'Utilisation du Radar Technologique Laplank
## Introduction
Le Radar Technologique Laplank est un tech radar classique pour suivre l'évolution des technologies de l'écosystème Laplank/Duniter/Ğ1. Il permet de suivre l'adoption des technologies au fil du temps avec un historique par release.
## Accès
Le Radar Technologique Laplank est accessible sur le **port 3006** et est protégé par un **mot de passe** : `laplank-radar`
L'authentification est gérée côté client via `localStorage` (session valide jusqu'à fermeture du navigateur).
## Structure du Radar
### Quadrants
Le radar est organisé en 4 quadrants business :
1. **Technologies Différenciantes** : Créent un avantage concurrentiel
2. **Technologies de Commodité** : Nécessaires mais non différenciantes
3. **Technologies à Risque** : Obsolètes, coûteuses, à migrer
4. **Technologies Émergentes** : Opportunités futures
### Anneaux (Rings)
Chaque technologie est classée dans un des 4 anneaux classiques :
1. **Adopt** : Technologies recommandées et utilisées avec succès. Stables et éprouvées, peuvent être adoptées en toute confiance pour de nouveaux projets.
2. **Trial** : Technologies à essayer. Prometteuses et testées avec succès dans certains contextes. À considérer pour de nouveaux projets.
3. **Assess** : Technologies à évaluer. Prometteuses mais nécessitent une évaluation approfondie avant adoption. À surveiller et tester.
4. **Hold** : Technologies à éviter ou à remplacer. Présentent des risques, sont obsolètes ou ne sont plus recommandées. À éviter pour de nouveaux projets.
## Historique des Technologies
Le Radar Technologique Laplank suit l'évolution des technologies au fil du temps avec un système d'historique par release.
### Structure par Release
Les technologies sont organisées par date de release dans des dossiers :
- `radar-business/2025-01-15/` : Release de janvier 2025
- `radar-business/2025-04-15/` : Release d'avril 2025 (exemple)
- etc.
### Suivi de l'Évolution
Chaque technologie peut évoluer entre les releases :
- **Nouveau** : Technologie ajoutée dans cette release
- **Modifié** : Technologie déplacée (ring ou quadrant) ou description mise à jour
- **Inchangé** : Technologie stable, pas de changement
### Créer une Nouvelle Release
Pour créer une nouvelle release :
1. Créer un nouveau dossier avec la date au format `YYYY-MM-DD` :
```bash
mkdir radar-business/2025-04-15
```
2. Copier les blips pertinents depuis la release précédente
3. Mettre à jour les blips existants si nécessaire (changement de ring, quadrant, description)
4. Ajouter les nouveaux blips pour les technologies nouvellement évaluées
## Métadonnées Business
Chaque technologie (blip) contient des métadonnées business :
### Métadonnées Standard
- **title** : Nom de la technologie
- **ring** : Anneau (adopt, trial, assess, hold)
- **quadrant** : Quadrant business
- **tags** : Tags pour le filtrage
### Métadonnées Business
- **businessImpact** : Impact sur le business (high, medium, low)
- **costToReplace** : Coût estimé de remplacement en euros
- **revenueImpact** : Impact sur les revenus (direct, indirect, none)
- **riskLevel** : Niveau de risque (high, medium, low)
- **maintenanceCost** : Coût annuel de maintenance en euros
- **differentiation** : Capacité de différenciation (high, medium, low)
### Métadonnées Compétences
- **competencyLevel** : Niveau moyen de compétence (expert, intermediate, beginner)
- **teamCoverage** : Nombre de personnes maîtrisant la technologie
- **skillGap** : Risque de compétence manquante (high, medium, low)
## Pages de Stratégie
Le Radar Technologique Laplank inclut trois pages de stratégie accessibles depuis le header :
1. **Stratégie Technique** : Vision et roadmap technique pour l'évolution du stack
2. **Business** : Analyse stratégique business autour de la dataviz et des flux économiques
3. **DataViz Expert** : Opportunités supplémentaires en dataviz (Smart Cities, Green Tech, KM, Cybersecurity)
Ces pages sont générées dynamiquement via `public/strategie-script.js` qui convertit le contenu Markdown en HTML.
### Contenu des Pages
Le contenu des pages de stratégie est intégré directement dans `public/strategie-script.js` :
- `docs/data/strategie-evolution-technique.md` : Stratégie d'évolution technique
- `docs/data/strategie-business.md` : Analyse business et opportunités
- `docs/data/opportunites-dataviz.md` et `docs/data/opportunites-dataviz-details.md` : Opportunités DataViz
Pour modifier le contenu, éditer directement `public/strategie-script.js` (sections `markdownContent`) ou les fichiers sources dans `docs/data/`.
## Utilisation
### Ajouter une Nouvelle Technologie
1. Créer un fichier Markdown dans `radar-business/2025-01-15/`
2. Utiliser le format défini dans `radar-business/FORMAT-BLIP.md`
3. Remplir toutes les métadonnées
4. Ajouter la description et les sections recommandées
### Modifier une Technologie Existante
1. Ouvrir le fichier Markdown correspondant
2. Modifier les métadonnées ou le contenu
3. Mettre à jour la date si changement significatif
### Analyser le Radar
1. Exécuter le script d'analyse :
```bash
node scripts/analyze-business-metrics.js
```
2. Consulter le rapport généré dans `docs/data/analyse-strategique.md`
### Générer les Blips
Pour régénérer les blips depuis `docs/data/technologies-duniter.md` :
```bash
node scripts/extract-technologies.js
```
## Interprétation des Résultats
### Technologies Critiques
Les technologies en ring "adopt" avec businessImpact "high" sont critiques. Elles nécessitent :
- Maintenance proactive
- Formation continue
- Documentation exhaustive
- Plans de continuité
### Technologies à Risque
Les technologies avec riskLevel "high" ou skillGap "high" présentent des risques. Actions recommandées :
- Formation ou recrutement
- Documentation
- Plan de migration si nécessaire
### Opportunités d'Innovation
Les technologies émergentes avec differentiation "high" sont des opportunités. Actions :
- POC (Proof of Concept)
- Évaluation de l'impact
- Adoption progressive
### Optimisation des Coûts
Les technologies de commodité avec maintenanceCost élevé peuvent être optimisées :
- Standardisation
- Automatisation
- Réduction des coûts
## Méthodologie d'Analyse
### 1. Collecte des Données
- Inventorier toutes les technologies
- Collecter les métadonnées business
- Analyser les compétences de l'équipe
### 2. Classification
- Classer par quadrant business
- Classer par ring (adopt, trial, assess, hold)
- Évaluer les métadonnées
### 3. Analyse
- Identifier les patterns
- Calculer les métriques
- Identifier les risques et opportunités
### 4. Recommandations
- Prioriser les actions
- Définir la roadmap
- Planifier les investissements
## Templates
### Template de Blip
Voir `radar-business/FORMAT-BLIP.md` pour le template complet.
### Template d'Analyse
Le script `analyze-business-metrics.js` génère automatiquement un rapport d'analyse.
## Maintenance
### Mise à Jour Régulière
- Mettre à jour les métadonnées trimestriellement
- Réviser les classifications annuellement
- Mettre à jour les coûts et risques
### Révision Stratégique
- Révision annuelle de la stratégie
- Ajustement des priorités
- Mise à jour de la roadmap
## Déploiement
Le Radar Technologique Laplank est déployé via Docker et Portainer :
- **Dockerfile** : `Dockerfile.business`
- **Docker Compose** : `docker-compose.business.yml`
- **Port** : 3006 (mappé depuis le port 3000 du conteneur)
- **Base path** : `/` (racine, pas de sous-chemin)
Voir [deploiement.md](./deploiement.md) pour les détails complets.
## Ressources
- **Format des blips** : `radar-business/FORMAT-BLIP.md`
- **Configuration** : `radar-business/config-business.json`
- **Script de stratégie** : `public/strategie-script.js`
- **Analyse stratégique** : `docs/data/analyse-strategique.md`
- **Stratégie d'évolution** : `docs/data/strategie-evolution-technique.md`
- **Stratégie business** : `docs/data/strategie-business.md`
- **Opportunités DataViz** : `docs/data/opportunites-dataviz.md` et `docs/data/opportunites-dataviz-details.md`
- **Technologies Duniter** : `docs/data/technologies-duniter.md`
- **Profil Team** : `docs/data/profil-team.md`
## Support
Pour toute question ou contribution, consulter la documentation ou contacter l'équipe technique.