Exploiter l'instance

Ce que couvre cette page

Cette page donne les gestes courants de l'administrateur d'une instance installée chez vous : lire la santé des services, les arrêter et les démarrer, lire les journaux, gérer le cache de parcours des points de restauration et retirer un agent du parc.

Les écrans du travail de tous les jours sont dans Espace MSP et dans Tableau de bord et problèmes. Cette page ne traite que l'hôte et la plateforme.

Prérequis

• Un accès root sur l'hôte, ou un compte membre du groupe docker, dans le dossier de déploiement de l'instance, pour les commandes.
• Le rôle Administrateur plateforme, avec une session du portail, pour la page Santé. Une clé API et un accès MCP ne lisent pas cette page. Voir Rôles et droits.

1. Lire la santé dans le portail

1. Ouvrez le portail avec un compte Administrateur plateforme.

2. Dans le menu Plateforme, cliquez Santé.

3. Lisez l'en-tête. Il donne la date de la lecture, et ce rappel : un processus sans signal depuis 30 secondes est En retard.

4. Lisez la carte Gateways. Ce sont les serveurs qui portent les connexions des agents.

   Colonne	Ce qu'elle donne
   Nœud	Le nom du processus.
   État	En vie ou En retard.
   Dernier signal	L'âge du dernier signal.
   Connexions d'agents	Le nombre de connexions d'agents ouvertes sur ce nœud.

5. Lisez la carte Workers. Ce sont les processus qui exécutent les tâches.

   Colonne	Ce qu'elle donne
   Worker	Le nom du processus.
   État	En vie ou En retard.
   Dernier signal	L'âge du dernier signal.
   Tâches en cours	Le nombre de tâches que ce worker traite.

6. Lisez la carte Files. Elle donne, pour chaque file, le nombre de tâches En attente, En cours, Différées et En échec. Le portail met le nombre de tâches en échec en rouge dès la première.

Chaque gateway et chaque worker écrit un signal toutes les 10 secondes. La page les relit au même rythme. Un processus sans signal depuis 30 secondes passe En retard : il peut être arrêté, et les tâches qu'il tient n'avancent plus. Un processus sans signal depuis 24 heures n'apparaît plus dans la liste.

Une carte vide signale que les processus de ce type ne tournent pas. Vérifiez alors l'état des services sur l'hôte.

2. Lire l'état des services et les journaux

1. Ouvrez une session sur l'hôte, dans le dossier de déploiement de l'instance.

2. Lisez l'état des services :

   docker compose ps

3. Lisez les journaux d'un service. Les journaux sont au format JSON, une ligne par entrée :

   docker compose logs -f api

Remplacez api par le nom du service à suivre. Le fichier docker-compose.yml du bundle donne la liste des services.

Les journaux de l'hôte ne portent pas les actions des utilisateurs du portail. Ces actions sont dans le Journal d'audit.

3. Arrêter et démarrer l'instance

1. Arrêtez les services :

   docker compose stop

2. Démarrez les services et attendez qu'ils soient sains :

   docker compose up -d --wait

La commande docker compose down retire les conteneurs et garde les données.

Ne lancez jamais docker compose down -v sur une instance en service. Cette commande supprime la base de données, donc les clés des dépôts de vos clients.

Pendant un arrêt, les agents ne sauvegardent plus et ne restaurent plus. Ils se reconnectent seuls au démarrage suivant.

4. Gérer le cache de parcours des points de restauration

Quand un technicien ouvre un dossier d'un point de restauration dans le portail, l'instance lit le dépôt du client. Elle garde un cache par dépôt, dans un volume Docker. La première ouverture d'un dépôt télécharge son index. Les ouvertures suivantes lisent l'index dans le cache et sont plus rapides. Voir Restaurer des fichiers depuis le portail.

Le cache ne porte que des fichiers chiffrés du dépôt : son index et ses arborescences. Il ne porte aucun nom de fichier en clair.

La taille du cache se règle avec SNAPSHOT_TREE_CACHE_MAX_BYTES dans .env, en octets. Le défaut est 5368709120, soit 5 Gio. Au-dessus de cette taille, l'instance supprime le cache des dépôts utilisés le moins récemment. Elle ne supprime jamais le cache d'un dépôt en cours de lecture : le volume peut donc dépasser cette valeur pendant un court moment.

Au démarrage, puis une fois par heure, l'instance supprime le cache des dépôts supprimés et celui des dépôts qui ne sont plus en service.

Videz le cache quand le volume prend trop de place sur le disque. Arrêtez les services de tâches d'abord.

1. Ouvrez une session sur l'hôte, dans le dossier de déploiement de l'instance.

2. Relevez le nom du volume :

   docker volume ls | grep worker-tree-cache

3. Arrêtez le worker, retirez son conteneur, supprimez le volume, puis démarrez de nouveau :

   docker compose stop worker
   docker compose rm -f worker
   docker volume rm baastide_worker-tree-cache
   docker compose up -d --wait

La première ouverture de chaque dépôt est lente de nouveau après cette opération.

5. Retirer un agent du parc

Le retrait d'un agent demande deux actions séparées :

1. Retirez l'agent de la machine. Voir Désinstaller l'agent.
2. Supprimez l'endpoint dans le portail. Voir Supprimer un endpoint ou un client.

Tant que vous ne supprimez pas l'endpoint, il reste dans la liste du client, hors ligne. La suppression prend effet après 72 heures, et vous pouvez l'annuler pendant ce délai. Les données de sauvegarde sont ensuite gardées 7 jours, puis purgées. Voir Délai de 72 heures.

Pour réinstaller l'agent sur la même machine, ne le désinstallez pas. Relancez la commande d'installation : elle garde l'identité de la machine.

6. Les autres commandes d'administration

L'instance porte un service d'administration. Lancez ses commandes avec docker compose run --rm -T admin <commande>, dans le dossier de déploiement.

Commande	Ce qu'elle fait
bootstrap-platform-admin --admin-email <email> --admin-locale fr	Envoie la première invitation d'un administrateur de la plateforme.
renew-platform-admin-invitation --admin-email <email> --admin-locale fr	Envoie une nouvelle invitation et annule le lien précédent.
create-bucket --pool p1 --name <bucket> --target-bytes <n>	Ajoute un bucket du même compte S3 au pool de stockage.
export-keys	Exporte les clés des dépôts hors de l'instance. Voir Séquestre des clés.
import-check	Contrôle un fichier d'export des clés, sans la base de données. Le fichier doit être monté dans le conteneur. Voir Séquestre des clés.
register-agent-release	Enregistre une version de l'agent. Voir Mettre à jour l'instance.

Le code de sortie 0 de bootstrap-platform-admin indique que l'invitation est enregistrée, ou qu'une invitation existe déjà. Dans ce second cas, la commande n'envoie rien. Le code 0 n'indique pas que l'email est arrivé. Pour envoyer de nouveau, corrigez le réglage SMTP, puis lancez renew-platform-admin-invitation.

Après l'activation du premier administrateur, créez les administrateurs suivants dans le portail. Dans le menu Plateforme, cliquez Administrateurs.

Limites et précautions

• docker compose down -v supprime la base de données et les clés des dépôts. Ne lancez jamais cette commande sur une instance en service.
• Ne lancez qu'un seul worker. Deux workers ne doivent jamais partager le volume du cache de parcours.
• Supprimez le volume du cache de parcours seulement quand le worker est arrêté.
• Une invitation d'administrateur de la plateforme ne donne aucun accès avant son acceptation. Une nouvelle invitation annule le lien précédent.
• La page Santé montre l'état du moment. Elle ne garde pas d'historique. Pour l'historique des tâches, voir Suivre une tâche de sauvegarde.
• Un processus En retard n'est pas toujours arrêté : un hôte très chargé donne aussi cet état. Vérifiez l'état des services sur l'hôte avant de conclure.
• La désinstallation d'un agent ne supprime ni l'endpoint ni ses sauvegardes. Ce sont deux actions séparées.
• Réglez le bucket de sauvegarde de la plateforme et surveillez son état. Voir Sauvegarder et restaurer l'instance.