From 5184e26293ef23944e874f4e938f1cc89ec85f82 Mon Sep 17 00:00:00 2001 From: kevin Date: Tue, 17 Mar 2026 08:54:33 +0100 Subject: [PATCH] fix: readme --- README.md | 146 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 91 insertions(+), 55 deletions(-) diff --git a/README.md b/README.md index 98e1014..ad8e5ce 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,14 @@ -# Projet Monitoring +# Supervisor + +`Supervisor` est une application Nuxt qui centralise plusieurs besoins d'exploitation dans une interface web unique : + +- suivi de l'état general d'applications distantes +- consultation de l'espace disque local et distant +- visualisation de métriques système de la machine qui execute l'application +- contrôle et téléchargement de sauvegardes via SSH +- lecture de messages Discord depuis un canal configure + +Le nom du package npm visible dans le depot est `disk-monitor`, mais l'interface et la structure du projet exposent clairement le nom `Supervisor`. ## Installation du projet @@ -15,79 +25,105 @@ https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/linux ### Installation du projet Une fois les prérequis installés, cloner le dépôt puis installer les dépendances. +Les étapes ci-dessous sont celles qui sont réellement supportées par le depot. + +### 1. Cloner le depot + +```bash +git clone gitea@gitea.malio.fr:MALIO-DEV/Supervisor.git +cd Supervisor +``` + +### 2. Preparer le fichier d'environnement + +Le depot fournit un exemple dans `.env.example`. + +```bash +cp .env.example .env +``` + +### 3. Renseigner les variables necessaires + +#### Generation d'une valeur pour `API_SECRET_KEY` + +Le depot impose la presence d'un secret, mais ne fournit pas de commande officielle pour le générer. + +Exemple de commande compatible : + +```bash +openssl rand -hex 32 +``` +Cette commande sert simplement à produire une valeur aléatoire facile à placer dans `.env`. + +Les variables visibles dans le depot sont : + +- `API_SECRET_KEY` : secret attendu par le middleware d'authentification pour toutes les routes `/api/*` sauf `/api/ping` +- `DISCORD_BOT_TOKEN` : token du bot utilise par endpoint Discord +- `DISCORD_CHANNEL_ID` : identifiant du canal Discord a lire +- `BACKUPS_REMOTE_HOST` : hôte SSH cible pour les operations distantes +- `BACKUPS_REMOTE_ROOT` : dossier racine des sauvegardes sur l'hôte distant +- `BACKUPS_MAX_FILES` : nombre maximal de fichiers retournés par dossier de backup +- `DISK_COMMAND_REMOTE` : commande shell utilisée pour la verification disque distante +- `DISK_COMMAND_LOCAL` : commande shell utilisée pour la verification disque locale +- `BACKUP_SCRIPT_COMMAND_BACKUP_BDD_RECETTE` : commande a exécuter pour le script "Backup BDD recette" +- `BACKUP_SCRIPT_COMMAND_CHECK_STATUT_RECETTE` : commande à exécuter pour le script "Check statut recette" +- `BACKUP_SCRIPT_COMMAND_BACKUP_VAULTWARDEN` : commande à exécuter pour le script "Backup vault warden" +- `BACKUPS_HOUR` : heure attendue des sauvegardes pour le contrôle de fraicheur + +### 4. Installer les dépendances + ```bash npm install ``` -Lancer ensuite le serveur de développement. +### 5. Lancer le serveur de développement ```bash npm run dev ``` -L’application sera accessible sur : -http://localhost:3000 +Par défaut, l'application Nuxt sera accessible sûr . -Si une erreur liée à la version de Node apparaît, vérifier que Node ≥ 20 est utilisé via nvm. +## Configuration necessaire -nvm install 20 -nvm use 20 +### Authentification API -## Utilisation du projet -### Frontend +Le middleware `server/middleware/auth.ts` protege toutes les routes `/api/*`, sauf `/api/ping`. -Lancer le serveur de développement. -``` -npm run dev -``` -Compilation pour la production. -``` -npm run build -``` -Prévisualisation du build de production. -``` -npm run preview -``` +Consequence visible : + +- si `API_SECRET_KEY` est vide, les appels API sont refusés avec `401 Unauthorized` +- l'application web pose aussi un cookie HTTP-only via `server/middleware/auth-cookie.ts` pour réutiliser ce secret coté navigateur + +### SSH pour les backups + +Les fonctionnalités de backup utilisent `ssh` avec les options `BatchMode=yes` et `ConnectTimeout=5` dans `server/utils/ssh.ts`. Cela implique un accès sans saisie interactive de mot de passe. + +Elements a preparer cote SSH : + +- une cle privée disponible sur la machine qui execute `Supervisor` +- une clé ssh pour les différentes machines cibles, si necessaire pour les différents usages (backup BDD, backup Vault warden, check statut recette) + +Le depot ne fixe pas de noms de fichiers de clés SSH ni de chemin obligatoire. Les noms exacts ne sont donc pas vérifiables dans le code. ## Commandes utiles -Installation des dépendances. -``` -npm install -``` -Lancer le serveur de développement. -``` +Commandes déclarées dans `package.json` : + +```bash npm run dev -``` -Build de production. -``` npm run build -``` -Prévisualisation du build. -``` +npm run generate npm run preview +npm run lint +npm run lint:fix ``` -Supprimer les dépendances et réinstaller proprement. -``` -rm -rf node_modules package-lock.json -npm install -Déploiement -``` -Construire l’application. -``` -npm run build -``` -Les fichiers générés se trouvent dans : -.output/ -Le serveur peut ensuite être lancé avec : -``` -node .output/server/index.mjs -``` -Il est recommandé d’utiliser un reverse proxy comme Nginx en production. +Usage : -### Notes - -Les accès SSH ou les chemins système utilisés par les endpoints doivent rester côté serveur. -Ne jamais exposer de credentials dans le frontend. -Les variables sensibles doivent être stockées dans un fichier .env. \ No newline at end of file +- `npm run dev` : lance l'application en développement +- `npm run build` : construit l'application pour la production +- `npm run generate` : généré une sortie statique si ce mode est compatible avec votre usage +- `npm run preview` : prévisualisé le build Nuxt +- `npm run lint` : execute ESLint +- `npm run lint:fix` : applique les corrections ESLint automatiques : collecte périodique CPU, mémoire et réseau \ No newline at end of file