Supervisor/README.md

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

Windows

Sur Windows, installer WSL2, Ubuntu, Docker et nvm.
Suivre la documentation suivante :
https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/windows

Linux

Sur Linux, installer Docker et nvm.
Suivre la documentation suivante :
https://wiki.malio.fr/bookstack/books/environnement-de-dev/chapter/linux

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

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.

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 :

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_REMOTE_HOST : commande shell utilisée pour la verification disque distante
• DISK_REMOTE_SCRIPT_DIR : dossier des scripts de vérification disque distante
• DISK_LOCAL_SCRIPT_DIR : commande shell utilisée pour la verification disque locale
• BACKUPS_HOUR : heure attendue des sauvegardes pour le contrôle de fraicheur

4. Installer les dépendances

npm install

5. Lancer le serveur de développement

npm run dev

Par défaut, l'application Nuxt sera accessible sur http://localhost:3000.

Configuration necessaire

Authentification API

Le middleware server/middleware/auth.ts protege toutes les routes /api/*, sauf /api/ping.

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

Securite

Le comportement actuel du projet repose sur une hypothèse d'exposition très forte.

• server/middleware/auth-cookie.ts pose automatiquement le cookie api_auth_token à tout visiteur qui charge l'interface web
• ce cookie permet ensuite d'accéder aux routes /api/* protégées par API_SECRET_KEY
• il n'existe pas de login utilisateur ni de contrôle d'identité distinct dans le dépôt

Conséquence :

• Supervisor doit être déployé uniquement sur un réseau de confiance, derrière un VPN, une restriction d'IP, un proxy d'authentification ou un autre contrôle d'accès externe
• si l'application est exposée publiquement sans protection supplémentaire, ce mécanisme ne constitue pas une authentification suffisante

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

Commandes déclarées dans package.json :

npm run dev
npm run build
npm run generate
npm run preview
npm run lint
npm run lint:fix

Usage :

• npm run dev : lance l'application en développement
• npm run build : construit l'application pour la production
• npm run generate : generee 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