Accueil
» Comment faire
»
Exécutez Mjölnir comme bot de modération de salle Matrix avec Docker
Exécutez Mjölnir comme bot de modération de salle Matrix avec Docker
Si la modération Matrix est répartie entre plusieurs comptes et salons personnels, utilisez Mjölnir comme bot dédié et attribuez aux modérateurs un salon d'administration privé pour leurs commandes. La configuration auto-hébergée la plus simple utilise Docker Compose, un compte Matrix distinct et un salon d'administration chiffré ; il vous suffit ensuite d'ajouter les salons communautaires que Mjölnir doit protéger et de vérifier ses permissions.
Ce que fait Mjölnir — et ce dont il a besoin
Mjölnir est un bot de modération Matrix qui applique des listes de règles et des actions de modération en tant que compte dédié. Le serveur principal est le serveur Matrix qui héberge les comptes utilisateurs et les salons. Un salon d'administration est un espace privé où les modérateurs autorisés exécutent les commandes du bot. Un salon protégé est un salon que Mjölnir surveille et peut modérer.
Pour suivre ce guide, vous devez disposer d'un compte Matrix sur le serveur principal, de l'autorisation de créer un compte bot et des salons, ainsi que d'un hôte avec Docker Engine et le plugin Docker Compose. Il n'est pas nécessaire de faire de Mjölnir un administrateur du serveur principal pour la modération des salons. Certaines actions à l'échelle du serveur, comme la désactivation d'utilisateurs ou la fermeture de salons, requièrent un compte Synapse et des privilèges d'administrateur serveur ; n'accordez pas ces privilèges sauf si votre cas d'utilisation l'exige. Consultez le dépôt officiel Mjölnir du projet .
1. Créez un compte bot et une salle de contrôle privée
Créez un compte dédié, par exemple @mjolnir:example.orgsur votre serveur personnel. N'utilisez pas le compte personnel d'un modérateur : des identifiants distincts facilitent la rotation des accès et permettent de différencier les actions du bot. Créez une salle privée pour les modérateurs, activez le chiffrement de bout en bout et invitez les modérateurs humains ainsi que le bot. Limitez l'accès à cette salle aux personnes de confiance. Toute personne présente dans la salle d'administration configurée peut exécuter des commandes, et Mjölnir ne propose pas de gestion plus fine des permissions au sein de cette salle.
Connectez-vous en tant que bot dans un profil de navigateur distinct ou une fenêtre de navigation privée pour obtenir son jeton d'accès Matrix via les paramètres d'aide et à propos d'Element . Copiez le jeton dans votre configuration en toute sécurité. Fermez cette fenêtre de navigateur sans vous déconnecter ; la déconnexion invalide le jeton. La documentation d'installation officielle recommande le chiffrement de l'espace d'administration et indique d'activer le chiffrement dans la configuration de Mjölnir afin que le bot puisse y communiquer.
La première tâche de configuration consiste à créer une identité de bot distincte ; ne divulguez jamais son jeton d’accès dans une capture d’écran ou un journal public.
2. Configurez Mjölnir pour votre serveur domestique
Sur l'hôte Docker, créez un répertoire de données persistant et copiez-y la configuration d'exemple du projet ./mjolnir/config/production.yaml. Le fichier d'exemple décrit les options supplémentaires ; ne définissez que les valeurs nécessaires à votre déploiement. Au minimum, utilisez l'URL de l'API client de votre serveur d'accueil, le jeton du bot, le chiffrement natif et l'ID ou l'alias de la salle Matrix de gestion.
Remplacez chaque valeur d'exemple. L'identifiant d'une salle commence par! ; un alias commence par# . Ne collez pas de matrix.tolien dansmanagementRoom . Traitez le fichier de configuration et le jeton comme des informations confidentielles : limitez l'accès au fichier, ne l'intégrez pas au système de contrôle de version et ne le publiez pas dans les demandes d'assistance. Si le bot ne parvient pas à déchiffrer la salle d'administration, vérifiez à nouveau le paramètre de chiffrement et assurez-vous que le bot a bien rejoint la salle.
L'exemple illustre les champs de configuration requis ; remplacez le serveur, le jeton et l'identifiant de salle d'exemple par vos propres valeurs.
3. Démarrez le service Docker Compose
Les instructions officielles de Docker utilisent l' matrixdotorg/mjolnirimage et montent un répertoire hôte à /datal' emplacement docker-compose.ymlsuivantmjolnir :
Depuis ce répertoire, démarrez Mjölnir docker compose up -d. Le répertoire monté conserve la configuration et les données du bot lors de la recréation du conteneur. Le guide officiel utilise l' latestétiquette `<version>` à titre d'exemple ; pour un serveur de production, choisissez une étiquette de version que vous avez testée et notez-la afin que les mises à jour soient effectuées en toute connaissance de cause. Après le démarrage, exécutez `<commande>` docker compose logs -f --tail 100 mjolnir. Attendez les messages de démarrage de Mjölnir dans la salle d'administration avant de continuer.
Démarrez le service depuis le répertoire contenant le fichier Compose, puis consultez ses journaux pour détecter les erreurs de démarrage.
4. Créez une liste de règles et protégez les chambres
Dans la salle d'administration, demandez au bot !mjolnir helps'il ne répond pas. Créez une liste de bannissement avec un code court et un alias de salle, puis définissez-la comme liste par défaut.
!mjolnir list create COC code-of-conduct-ban-list
!mjolnir default COC
Mjölnir crée la salle de discussion et vous y invite. Une liste de règles est une salle Matrix contenant des règles de modération ; vérifiez donc sa visibilité et ses membres avant de la partager. Ajoutez chaque salle communautaire que vous souhaitez que Mjölnir surveille :
Le bot a besoin de pouvoirs suffisants dans chaque salon protégé pour effectuer des actions de modération, notamment la possibilité de bannir des utilisateurs et de masquer des événements. Utilisez les paramètres de puissance du salon pour n'accorder que les permissions nécessaires. La verifycommande vérifie si Mjölnir dispose des permissions requises dans les salons protégés. Ajoutez le bot à un salon avant de le protéger. Ne configurez pas cette option protectAllJoinedRoomsà la légère : cela étend la protection aux salons auxquels le bot se connecte et rend la sélection salon par salon moins pertinente.
Une fois que le bot répond dans la salle de gestion privée, créez une liste et testez-y les commandes.
Vérifiez la configuration et évitez les erreurs courantes
Le bot est en ligne :docker compose ps le service est en cours d’exécution, les journaux ne montrent aucune erreur d’authentification ou de chiffrement répétée et le bot publie son état de démarrage dans la salle de gestion.
Les commandes sont restreintes : seuls les modérateurs peuvent les utiliser !mjolnir statusdans !mjolnir rulesle salon configuré. Ne testez pas les commandes dans un salon public.
Les pièces sont protégées :!mjolnir rooms liste les pièces concernées et !mjolnir verifyindique les niveaux de puissance adéquats.
Les secrets restent confidentiels : le jeton n’est ni dans un dépôt public, ni dans l’historique du shell, ni dans les journaux publiés. S’il est divulgué, révoquez-le ou renouvelez-le en vous déconnectant de la session du bot et en mettant à jour la configuration avant de redémarrer.
Si le bot reste silencieux, vérifiez d'abord que l'identifiant ou l'alias de la salle de gestion est exact et que le bot en est bien membre. Pour les salles chiffrées, assurez-vous que le chiffrement est activé et que le bot peut déchiffrer les messages. Si la modération échoue dans une seule salle, vérifiez qu'elle est protégée et que ses niveaux de puissance permettent l'action demandée. Pour la syntaxe des commandes et les options de configuration, consultez le guide du modérateur Mjölnir , le guide d'installation Docker et l'exemple de configuration .