docs(README): refonte ludique + Linux quickstart; ci: runners self-hosted,linux
This commit is contained in:
parent
fb1968f610
commit
7aee843d9d
160
README.md
160
README.md
@ -1,128 +1,82 @@
|
||||
# 4NK Project Template — Qualité, Sécurité et Open Source
|
||||
# 4NK Project Template — Qualité, Sécurité, Open Source ✨
|
||||
|
||||
Ce dépôt est le template de référence 4NK. Il formalise la démarche de qualité, de sécurité et d’open source applicable à tous les projets 4NK et fournit des supports initiaux (modèles CI/CD, règles Cursor, scripts, guides). Chaque projet doit l’adapter à ses spécificités, et proposer des améliorations en retour (feedback) vers ce template.
|
||||
Bienvenue dans le template 4NK. Objectifs: démarrer vite, rester propre, publier serein. Vous y trouverez des règles, des workflows CI, des scripts d’agents et une documentation prête à adapter.
|
||||
|
||||
## 📋 Table des Matières
|
||||
## 📦 Ce que vous obtenez
|
||||
|
||||
- Standards de qualité et sécurité (lint, audit, release‑guard)
|
||||
- Agents automatisés (qualité, docs, tests, sécurité, déploiement)
|
||||
- CI Gitea prête à l’emploi (self‑hosted, linux)
|
||||
- Documentation structurée: `docs/project/**` (ce dépôt) et `docs/templates/**` (modèles pour vos projets)
|
||||
|
||||
## 🏗️ Architecture
|
||||
## 🐧 Linux (Debian) — Prérequis rapides
|
||||
|
||||
### 🔄 Flux de Données
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install -y bash git curl jq ca-certificates
|
||||
# Lint Markdown
|
||||
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
|
||||
sudo apt install -y nodejs
|
||||
```
|
||||
|
||||
## ⚙️ Configuration locale (secrets)
|
||||
|
||||
## 🚀 Démarrage Rapide
|
||||
```bash
|
||||
bash scripts/deploy/setup.sh # crée ~/.4nk_template/.env (chmod 600)
|
||||
```
|
||||
À renseigner ensuite dans `~/.4nk_template/.env` (extraits):
|
||||
|
||||
### Prérequis
|
||||
- OPENAI_API_KEY, OPENAI_MODEL (si agents IA)
|
||||
- RELEASE_TOKEN (release via API Gitea)
|
||||
- BASE_URL (optionnel, par défaut `https://git.4nkweb.com`)
|
||||
|
||||
Plus d’infos: `docs/project/CONFIGURATION.md` et `docs/project/GITEA_SETUP.md`.
|
||||
|
||||
### Installation
|
||||
## 🤖 Exécuter les agents
|
||||
|
||||
```bash
|
||||
scripts/agents/run.sh # exécution complète, rapports dans tests/reports/agents
|
||||
scripts/agents/run.sh . . documentation # exécution ciblée (facultatif)
|
||||
```
|
||||
Fallback Windows: `scripts/agents/run.ps1`.
|
||||
|
||||
### Configuration SSH (Recommandé)
|
||||
Guide complet: `docs/project/AGENTS_RUNTIME.md`.
|
||||
|
||||
## 🔁 CI/CD (Gitea Actions)
|
||||
|
||||
- Runners: labels requis `self-hosted,linux` (voir `docs/project/GITEA_SETUP.md`)
|
||||
- Jobs clés: `markdownlint`, `agents-smoke`, `release-guard`, `release-create`
|
||||
- Secrets/Variables: `RELEASE_TOKEN`, `OPENAI_API_KEY`, `BASE_URL`, `OPENAI_*`
|
||||
|
||||
## 🚀 Release
|
||||
|
||||
```bash
|
||||
# Vérifier/mettre à jour la version
|
||||
cat TEMPLATE_VERSION
|
||||
|
||||
# Tagger (déclenche la release via API si RELEASE_TOKEN existe côté dépôt)
|
||||
git tag -a vYYYY.MM.P -m 'release: vYYYY.MM.P (latest)'
|
||||
git push origin vYYYY.MM.P
|
||||
```
|
||||
|
||||
Changelog: `CHANGELOG.md`. Gardien de release: `release-guard` en CI.
|
||||
|
||||
## 📚 Documentation
|
||||
|
||||
### 📖 Guides Principaux
|
||||
|
||||
- docs/TEMPLATE_ADAPTATION.md — Comment adapter ce template à votre projet
|
||||
- docs/TEMPLATE_FEEDBACK.md — Comment proposer des améliorations au template
|
||||
|
||||
|
||||
### 🔧 Guides Techniques
|
||||
|
||||
|
||||
### 🧪 Guides de Test
|
||||
|
||||
### 🌐 Guides Réseau
|
||||
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Services Disponibles
|
||||
|
||||
|
||||
### Variables d'Environnement
|
||||
|
||||
|
||||
## 🧪 Tests et Monitoring
|
||||
|
||||
### Tests de Base
|
||||
|
||||
### Monitoring
|
||||
|
||||
|
||||
### Tests de Performance
|
||||
|
||||
|
||||
## 🌐 Réseau de Relais
|
||||
|
||||
### Architecture Mesh
|
||||
|
||||
|
||||
### Ajout de Nœuds Externes
|
||||
|
||||
|
||||
### Configuration Externe
|
||||
|
||||
|
||||
## 🛠️ Développement
|
||||
|
||||
### Structure du Projet
|
||||
|
||||
|
||||
### Ajout d'un Nouveau Service
|
||||
|
||||
|
||||
### Modification de la Configuration
|
||||
|
||||
|
||||
## 🚨 Dépannage
|
||||
|
||||
### Problèmes Courants
|
||||
|
||||
#### 1. Ports Déjà Utilisés
|
||||
|
||||
|
||||
#### 2. Problèmes de Synchronisation
|
||||
|
||||
|
||||
#### 3. Problèmes de Connectivité
|
||||
|
||||
### Logs Détaillés
|
||||
|
||||
|
||||
### Healthchecks
|
||||
|
||||
|
||||
## 📈 Performance
|
||||
|
||||
### Ressources Recommandées
|
||||
|
||||
### Optimisations
|
||||
|
||||
- Projet (ce dépôt): `docs/project/`
|
||||
- Modèles à réutiliser: `docs/templates/`
|
||||
- Standards de qualité: `docs/project/QUALITY_STANDARDS.md`
|
||||
|
||||
## 🤝 Contribution
|
||||
|
||||
1. Fork le repository
|
||||
2. Créer une branche feature (`git checkout -b feature/nouvelle-fonctionnalite`)
|
||||
3. Commit les changements (`git commit -am 'Ajout de nouvelle fonctionnalité'`)
|
||||
4. Push la branche (`git push origin feature/nouvelle-fonctionnalite`)
|
||||
5. Créer une Pull Request
|
||||
|
||||
Pour les améliorations du template lui‑même (règles, CI, scripts), se référer à `docs/TEMPLATE_FEEDBACK.md` et utiliser le type d’issue « Template Feedback ».
|
||||
- Fork → branche → PR (CI verte, docs/changelog à jour)
|
||||
- Respect des règles éditoriales (français, pas de secrets, pas d’exemples applicatifs)
|
||||
|
||||
## 📄 Licence
|
||||
|
||||
Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.
|
||||
MIT — voir `LICENSE`.
|
||||
|
||||
## 🆘 Support
|
||||
|
||||
Pour obtenir de l'aide :
|
||||
|
||||
1. Consulter la [documentation](docs/)
|
||||
2. Vérifier les [issues existantes](https://git.4nkweb.com/4nk/4NK_node/issues)
|
||||
3. Créer une nouvelle issue avec les détails du problème
|
||||
4. Inclure les logs et la configuration utilisée
|
||||
|
||||
---
|
||||
- Lire `docs/project/INDEX.md`
|
||||
- Ouvrir une issue si besoin
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user