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)
AGENT_APPS_DIR	/home	Racine des applications compose (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;

---

Applications compose (agent 1.4.0+)

L'agent expose les fichiers compose rangés selon la convention /home/<application>/compose.yaml (les noms compose.yml, docker-compose.yml et docker-compose.yaml sont également reconnus). L'interface web permet de les lister, les éditer, en créer de nouveaux et déployer.

Route agent	Effet
GET /apps	Liste les dossiers de /home contenant un fichier compose, avec le nombre de conteneurs actifs
GET /apps/{nom}/compose	Contenu du fichier
PUT /apps/{nom}/compose	Écrit le fichier (deploy: true enchaîne sur un déploiement)
POST /apps	Crée /home/<nom>/ et son fichier compose
POST /apps/{nom}/up	docker compose pull puis up -d dans le dossier

Garde-fous appliqués :

• Validation avant écriture. Le contenu est d'abord vérifié par docker compose config sur un fichier temporaire, dans le dossier de l'application pour que .env et chemins relatifs soient résolus comme au déploiement. Un fichier invalide est refusé et rien n'est écrit.
• Sauvegarde. L'ancienne version est copiée en <fichier>.bak avant chaque écriture.
• Périmètre. Le nom d'application est restreint à [A-Za-z0-9][A-Za-z0-9._-]* et le chemin résolu doit rester directement sous AGENT_APPS_DIR — les .. et les liens symboliques sortants sont rejetés.
• Taille limitée à 512 kB par fichier.
• Réservé aux administrateurs, comme le terminal.

Si vos applications ne sont pas sous /home, changez AGENT_APPS_DIR dans /opt/vps-monitor-agent/.env puis redémarrez le service.

---

Dépôt source

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