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](https://docs.docker.com/engine/install/) |
| curl       | —               | `apt install curl` |
| systemd    | —               | Inclus sur Debian/Ubuntu/Rocky |

---

## Installation rapide (one-liner)

```bash
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

```bash
# 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

```bash
# É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

```bash
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` :

```bash
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 :

```bash
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 :

```nginx
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](https://git.jeanbonapp.com/jeanbon/ScriptVPS)