ScriptVPS/vps-monitor/agent/INSTALL.md

VPS Monitor Agent — Guide d'installation

L'agent est un service léger à déployer sur chaque VPS à superviser.
Il expose une API REST locale que le backend central interroge pour lire l'état des conteneurs Docker et exécuter des actions.

---

Prérequis

Dépendance	Version minimale	Installation
Python 3	3.10+	apt install python3 python3-venv
Docker	24+	docs.docker.com
curl	—	apt install curl
systemd	—	Inclus sur Debian/Ubuntu/Rocky

---

Installation rapide (one-liner)

curl -fsSL https://git.jeanbonapp.com/jeanbon/ScriptVPS/raw/branch/main/vps-monitor/agent/install.sh \
  | sudo bash

La clé API et le port sont générés/affichés automatiquement à la fin.

---

Options disponibles

sudo bash install.sh [OPTIONS]

Options :
  --key   <clé>     Clé API à utiliser (générée aléatoirement si omise)
  --port  <port>    Port d'écoute de l'agent (défaut : 8001)
  --branch <nom>    Branche du dépôt à utiliser (défaut : main)
  --update          Met à jour l'agent sans changer la configuration
  --uninstall       Supprime complètement l'agent et le service

Exemples

# Installation avec une clé et un port personnalisés
sudo bash install.sh --key "ma-super-cle-secrete" --port 8002

# Installer depuis une branche de développement
sudo bash install.sh --branch develop

# Mettre à jour vers la dernière version
sudo bash install.sh --update

# Désinstaller
sudo bash install.sh --uninstall

---

Ce que fait le script

1. Télécharge agent.py et requirements.txt depuis le dépôt Gitea (branche configurable).
2. Crée /opt/vps-monitor-agent/ avec un environnement virtuel Python isolé.
3. Installe les dépendances Python (fastapi, uvicorn, docker).
4. Génère /opt/vps-monitor-agent/.env avec la clé API et le port (permissions 600).
5. Configure et démarre le service systemd vps-monitor-agent.
6. Affiche l'adresse IP publique et la clé API à copier dans le backend.

---

Arborescence installée

/opt/vps-monitor-agent/
├── agent.py          # Code de l'agent
├── requirements.txt  # Dépendances Python
├── .env              # Clé API et port (chmod 600)
└── venv/             # Environnement virtuel Python

---

Gestion du service

# État
systemctl status vps-monitor-agent

# Logs en direct
journalctl -u vps-monitor-agent -f

# Redémarrer
systemctl restart vps-monitor-agent

# Arrêter
systemctl stop vps-monitor-agent

---

Mise à jour

sudo bash install.sh --update

Le script --update :

• Retélécharge agent.py et requirements.txt depuis le dépôt.
• Met à jour les dépendances Python si besoin.
• Redémarre le service.
• Conserve la clé API et le port existants.

Pour mettre à jour le script lui-même avant de lancer --update :

curl -fsSL https://git.jeanbonapp.com/jeanbon/ScriptVPS/raw/branch/main/vps-monitor/agent/install.sh \
  -o install.sh && sudo bash install.sh --update

---

Configuration du backend central

Après l'installation, renseignez les informations de l'agent dans l'interface web :

Champ	Valeur
Hôte	IP publique du VPS
Port	Port choisi (défaut 8001)
Clé API	Affichée à la fin de l'installation

---

Variables d'environnement

Le fichier .env supporte les variables suivantes :

Variable	Défaut	Description
AGENT_API_KEY	(généré)	Clé secrète partagée avec le backend
AGENT_PORT	8001	Port TCP d'écoute
AGENT_MAX_EXEC_SESSIONS	10	Nombre de terminaux ouverts simultanément (voir ci-dessous)

Pour modifier la configuration sans réinstaller :

sudo nano /opt/vps-monitor-agent/.env
sudo systemctl restart vps-monitor-agent

---

Terminal interactif (agent 1.3.0+)

Depuis la version 1.3.0, l'agent expose un WebSocket /containers/{id}/exec qui ouvre un shell dans un conteneur, l'équivalent de docker exec -it <conteneur> bash (repli automatique sur sh si l'image n'a pas bash). L'interface web s'en sert pour le bouton « terminal » de chaque conteneur démarré.

À savoir :

• Réservé aux administrateurs. Le backend n'ouvre le WebSocket que pour un compte de rôle admin, après échange du JWT contre un ticket à usage unique valable 60 secondes — le jeton d'authentification ne transite donc jamais en query string.
• Désactivable globalement depuis Administration → Paramètres → Terminal des conteneurs.
• Portée réelle des droits : le shell s'exécute avec l'utilisateur par défaut de l'image, souvent root dans le conteneur. Un conteneur privilégié ou avec le socket Docker monté permet d'atteindre l'hôte — n'ouvrez ce droit qu'à des comptes de confiance.
• Mise à jour : bouton « Mettre à jour l'agent » dans l'interface, ou sudo bash install.sh --update. Les agents < 1.3.0 affichent un bouton terminal désactivé expliquant qu'une mise à jour est nécessaire.

Si l'interface est servie derrière un reverse proxy maison (autre que le nginx fourni), pensez à y relayer les WebSockets :

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;

---

Dépôt source

https://git.jeanbonapp.com/jeanbon/ScriptVPS