Installer avec Docker Compose¶

Trois installations sont proposées. Toutes démarrent sans règle de redémarrage automatique des conteneurs surveillés.

Besoin	Fichiers	Accès local
Agent seul et API	`docker-compose.yml`	`http://127.0.0.1:9808`
Agent et interface web	Base et `docker-compose.ui.yml`	`https://localhost:8443`
Historique et graphiques	`examples/monitoring/compose.yaml`	Grafana sur le port 3000

Socket Docker filtré par défaut¶

L’installateur détecte le groupe du socket et construit le proxy. Pour utiliser Compose manuellement, exportez le groupe dans chaque nouveau shell, ou inscrivez sa valeur numérique dans le fichier local .env du projet. Depuis la racine :

export DOCKER_SOCKET_GID=$(stat -c %g "${DOCKER_SOCKET_PATH:-/var/run/docker.sock}")
docker compose up -d --build --wait

Seul le proxy monte le socket de l’hôte. L’agent le joint sur un réseau privé et le proxy ne publie aucun port hôte. Par défaut, l’agent peut lire la version, la liste et les détails des conteneurs, leurs statistiques, les événements et les détails d’une image par son empreinte. L’inspection peut révéler les variables d’environnement et les montages. Gardez ce réseau privé.

Pour autoriser d’autres opérations, exportez la variable voulue, puis relancez la commande Compose. Chaque valeur est une liste d’identifiants complets séparés par des espaces. Obtenez un identifiant avec docker inspect -f '{{.Id}}' NOM. Actualisez la liste après toute recréation du conteneur. Pour révoquer les nouvelles requêtes, supprimez la variable avec unset et réappliquez la configuration.

Variable	Droits sur les conteneurs désignés
`MONIT_PROXY_EXEC_TARGETS`	Sondes de fichiers et commandes Docker exec sans le mode privilégié, y compris en tant que root dans le conteneur
`MONIT_PROXY_LIFECYCLE_TARGETS`	Démarrage, arrêt et redémarrage

Choisissez uniquement des conteneurs de confiance. Une commande dans un conteneur privilégié ou disposant du socket Docker ou du système de fichiers hôte peut donner accès à l’hôte. Le proxy lui-même conserve le vrai socket. Les règles de supervision et les jetons pour les actions manuelles se configurent séparément. L’ancien fichier docker-compose.socket-proxy.yml reste accepté pour les commandes existantes.

Migrer un agent existant¶

Conservez votre installation actuelle jusqu’à la migration. L’installateur s’arrête s’il détecte un agent existant qui utilise directement le socket.

Sauvegardez les fichiers Compose, la configuration et l’état. Gardez le nom de projet et son volume. Relevez les règles et sondes qui nécessitent un exec ou une action sur un conteneur.
Renseignez le GID du socket et les identifiants complets des cibles comme indiqué plus haut. Conservez ces valeurs pour les prochains appels à Compose.
Dans le nouveau dépôt, reprenez le nom de projet et vos fichiers de surcharge. Vérifiez avec docker compose config que seul le proxy monte le socket. Retirez de l’agent tout ancien montage du socket et toute surcharge de DOCKER_HOST.
Appliquez la configuration vérifiée avec docker compose up -d --build --wait et les fichiers choisis. Vérifiez /readyz, puis testez vos sondes et actions sur une cible jetable autorisée. Pour revenir en arrière, reprenez les anciens fichiers et le même nom de projet. Utilisez up -d --remove-orphans après vérification des services qui seront retirés. Conservez le volume d’état.

Installation guidée¶

Sur Linux amd64, installer Git, Docker Engine, son plugin Compose v2 avec up --wait et curl. Pour le tableau de bord, prévoir Python 3 et OpenSSL.

git clone --branch v1.3.3 --depth 1 https://github.com/decryptus/monit-docker.git
cd monit-docker
./install.sh

Appuyer sur Entrée pour ajouter le tableau de bord local. Au premier lancement, choisir un identifiant et un mot de passe de 12 caractères minimum. Le script vérifie la collecte et la demande d’authentification HTTPS, puis affiche le nombre de conteneurs et l’adresse. Le certificat local autosigné est valable sept jours. Après une connexion SSH, suivre l’exemple de tunnel affiché depuis son poste. Relancer ./install.sh --ui dans le même dossier réutilise les identifiants et le volume existants. Pour l’API seule, utiliser ./install.sh --agent-only. Pour retirer une interface déjà installée, suivre la procédure d’arrêt ci-dessous.

Préparer la machine¶

Utiliser Docker Engine sous Linux, son socket Unix local et une version récente du plugin Compose avec up --wait. Le compte doit pouvoir accéder à Docker. Les images publiées ciblent Linux amd64 ; une autre architecture demande une compilation ou une émulation vérifiée séparément. Docker Desktop doit utiliser les conteneurs Linux. Sous Windows, exécuter les commandes dans WSL avec l’intégration Docker. La préparation de l’UI demande aussi Python 3 et OpenSSL.

git clone https://github.com/decryptus/monit-docker.git
cd monit-docker
docker compose version
docker info

Pour Docker rootless, définir DOCKER_SOCKET_PATH avec le chemin absolu du socket local. Les contextes Docker distants ne sont pas couverts par cette procédure.

Lancer seulement l’agent¶

docker compose config --quiet
docker compose up -d --wait --wait-timeout 180
curl -f http://127.0.0.1:9808/readyz
curl -f http://127.0.0.1:9808/v1/status

La collecte tourne toutes les 30 secondes après la fin du cycle précédent. readyz renvoie HTTP 200 lorsque les mesures sont fraîches et la collecte réussie. En cas d’erreur, consulter docker compose ps et docker compose logs --tail=100 monit-docker.

L’API de l’agent écoute sur la boucle locale. Seul le proxy monte le socket Docker.

Ajouter l’interface web¶

python3 examples/ui/prepare.py --self-signed
docker compose -f docker-compose.yml -f docker-compose.ui.yml config --quiet
docker compose -f docker-compose.yml -f docker-compose.ui.yml up -d --wait --wait-timeout 180

Saisir un identifiant et un mot de passe d’au moins 12 caractères. Ouvrir https://localhost:8443. Le certificat local est autosigné et valable sept jours ; le navigateur signale qu’il n’est pas reconnu. Pour un vrai déploiement, utiliser un certificat de confiance selon le guide UI.

La préparation se fait une seule fois et refuse d’écraser les secrets existants. Réutiliser examples/ui/secrets.local aux démarrages suivants. L’UI utilise le même agent, sans Prometheus ni Grafana, et n’active aucun bouton de contrôle des conteneurs. L’API de l’agent reste accessible sur la boucle locale.

Conserver la même liste de fichiers pour arrêter cette installation :

docker compose -f docker-compose.yml -f docker-compose.ui.yml down

Cette commande conserve le volume d’état et les secrets. --volumes supprimerait les données du volume : ne pas l’ajouter pour un arrêt normal. Pour revenir à l’agent seul, arrêter avec les deux fichiers, puis relancer le fichier de base. Les surcharges avancées d’actions et de journal du dossier examples/ui ont leur propre procédure ; ne pas les mélanger avec ces fichiers racine.

Régler les ports et mettre à jour¶

Définir MONIT_DOCKER_PORT, UI_PORT ou DOCKER_SOCKET_PATH dans le shell avant Compose si nécessaire. UI_BIND vaut 127.0.0.1 par défaut. Garder le même nom de projet et le même répertoire pour réutiliser le volume.

Les images de l’agent et de l’UI sont fixées à 1.3.3. Pour une évolution, choisir des versions correspondantes, préserver la configuration et les données, puis utiliser pull et up -d --wait avec la même liste de fichiers. Un simple pull ne remplace pas les conteneurs en cours d’exécution.

Remplacer l’ancien exemple cron¶

L’ancien fichier racine utilisait latest, montait tout /var/run et exécutait des règles cron, dont un signal PHP-FPM. Le nouveau lance uniquement serve en observation. Les anciens jobs MONIT_DOCKER_CRONS ne seront plus exécutés.

Avant la mise à jour, sauvegarder hors du dépôt l’ancien Compose, la configuration, les états et les journaux. Arrêter l’ancienne installation avec ce fichier et son nom de projet d’origine. Pour conserver des jobs, reprendre explicitement leurs cibles et règles selon le guide cron, avec un état persistant et une simulation préalable. Aucune conversion automatique des règles n’est effectuée.

À partir de la version 1.3.0, la commande monit-docker serve peut aussi lire ses réglages dans monit-docker.yml. Exemple :

serve:
  port: 9810
  interval: 60
  rsc: [status, health]
  status_token_file: /run/secrets/status

Une option explicite en ligne de commande est prioritaire. Avec cet exemple, serve --port 9808 --rsc pid écoute sur 9808, collecte uniquement le PID et conserve l’intervalle et le chemin du jeton définis dans le fichier. Les listes rsc et cmd sont remplacées en entier. Pour les noms de clés, remplacer les tirets des options longues par des traits de soulignement. La simulation ponctuelle utilise toujours --dry-run. Pour désactiver temporairement un booléen activé dans serve:, utilisez --no-allow-actions, --no-allow-maintenance ou --no-trust-proxy-user.

Pour protéger la lecture de /v1/status, montez un fichier secret dans l’agent et ajoutez --status-token-file /run/secrets/status après serve. Le fichier contient 64 caractères hexadécimaux minuscules. Utilisez un secret distinct pour chaque usage. Les clients envoient le jeton dans l’en-tête Bearer de la requête. Si vous utilisez le tableau de bord, configurez son proxy pour ajouter cet en-tête uniquement sur la route de statut. Voir le guide de l’agent.

Continuer avec une démonstration¶

Le tutoriel mémoire ajoute un conteneur jetable et permet d’activer explicitement un seul redémarrage automatique. La limite mémoire du conteneur et la sélection exacte évitent de prendre un service existant comme cible.

La pile Prometheus et Grafana reste une installation distincte pour l’historique. Arrêter la pile minimale ou modifier ses ports avant de la lancer. Les notifications demandent une configuration supplémentaire.

Réglages de cron, stats et monit¶

La version 1.3.0 permet de placer les valeurs habituelles dans trois sections de monit-docker.yml. Exemple pour une lecture de métriques :

stats:
  rsc: [cpu_percent, mem_usage]
  output: json
monit:
  rsc: [status]

monit-docker stats --output text utilise les ressources du fichier et affiche du texte. Avec monit --rsc status, seules les mesures demandées sont lues, même si le YAML définit une commande. Pour programmer une règle, renseignez cron.cmd et cron.state_file, puis testez avec monit-docker --name web cron --dry-run. Le guide cron contient un exemple complet.