Configuration

Emplacement des paramètres, les trois façons de les modifier (Console système, variables d’environnement, amctl) et destination des journaux.

Emplacement des paramètres

Chaque paramètre du serveur a un nom composé d’une section et d’une clé, par exemple ServiceSettings.SiteURL ou EmailSettings.SMTPServer. Ensemble, ils forment une configuration, stockée dans l’un des deux endroits suivants :

• Dans la base de données. Le fichier de composition du site définit AM_CONFIG à l’URL de connexion PostgreSQL, de sorte que la configuration est une ligne de la base de données et que le conteneur ne conserve rien sur le disque. Plusieurs serveurs partageant une même base de données partagent également leur configuration.
• Dans un fichier. Sans AM_CONFIG, le serveur lit config/config.json à côté de son répertoire bin/ (/antimatter/config/config.json dans l'image Docker). L'archive de la version de production et les fichiers compose de production d'antimatter-docker fonctionnent ainsi, tout comme les paquets .deb et .rpm, dont le fichier est /etc/antimatter/config/config.json. Gardez ce fichier lisible uniquement par l'utilisateur du serveur : il contient des mots de passe et des clés.

AM_CONFIG (ou l’option --config de la commande antimatter) accepte soit un chemin de fichier, soit une URL postgres://. Les paramètres omis prennent leur valeur par défaut.

Pour déplacer une configuration existante d’un fichier vers la base de données, exécutez ceci sur le serveur, puis démarrez le serveur avec AM_CONFIG défini à la même URL :

amctl --local config migrate /opt/antimatter/config/config.json \
    "postgres://antimatter:PASSWORD@localhost:5432/antimatter?sslmode=disable&connect_timeout=10"

Variables d’environnement

Tout paramètre peut également être fourni sous forme de variable d’environnement. Les variables priment sur la configuration stockée, ce qui les rend adaptées à ce qui relève du déploiement : la base de données, l’URL du site, le stockage de fichiers, les ports.

Règle de nommage

Écrivez AM_, puis la section, puis la clé, en majuscules et séparées par des tirets bas. Les mots à l’intérieur d’un nom de section ou de clé ne sont pas séparés :

• Les paramètres booléens prennent true ou false ; les nombres sont des nombres simples.
• Les paramètres de liste prennent leurs valeurs séparées par des espaces, par exemple AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP".
• Les paramètres qui sont des objets prennent du JSON. La seule variable de ce type pour les applications est AM_PLUGINSETTINGS_PLUGINS, et elle remplace les paramètres de toutes les applications d’un coup : définissez les paramètres des applications dans la Console système ou avec amctl à la place (voir ci-dessous).
• Les installations Mattermost antérieures utilisent le préfixe MM_, par exemple MM_SQLSETTINGS_DATASOURCE. Il fonctionne toujours en tant qu'alias de compatibilité. Si les deux sont définis, la variable AM_ prend le dessus.

Un paramètre défini par une variable est verrouillé dans la Console système, avec la note « Ce paramètre a été défini par une variable d'environnement. Il ne peut pas être modifié via la Console système. ». Il n'est pas écrit dans la configuration stockée : supprimez la variable et la valeur stockée s'appliquera à nouveau.

Avec Docker Compose

Ajoutez les variables sous environment: du service antimatter, ou dans un compose.override.yaml à côté de compose.yaml (Compose le lit automatiquement, et il survit aux mises à jour du fichier téléchargé) :

services:
  antimatter:
    environment:
      AM_EMAILSETTINGS_SMTPSERVER: smtp.example.com
      AM_EMAILSETTINGS_SMTPPORT: "587"
      AM_LOGSETTINGS_CONSOLELEVEL: INFO

Appliquez les modifications avec docker compose up -d, ce qui recrée le conteneur.

Variables lues par les applications

Certaines variables ne sont pas des paramètres et n'ont pas de champ dans la Console système : AM_CONFIG (l'emplacement de la configuration), ainsi que AM_AI_ENCRYPTION_KEY et AM_AI_ENCRYPTION_PREVIOUS_KEYS, la clé qui chiffre les clés API des connexions aux modèles (voir IA).

Certaines applications lisent leurs propres variables, définies sur le service antimatter : l'application Calls lit AM_CALLS_* (voir Appels et voix), et l'application GIFs lit AM_GIFS_SERVICE_URL, AM_GIFS_API_KEY et AM_GIFS_UPLOAD_KEY (voir Applications intégrées).

La Console système

La Console système est la zone d'administration de l'application web, destinée aux administrateurs système. Pour l'ouvrir, cliquez sur votre photo en haut de la barre latérale de l'application et choisissez Console système, ou accédez à https://chat.example.com/admin_console. Sa barre latérale comporte une zone Trouver des paramètres qui recherche sur toutes les pages.

Ses sections sont :

• Rapport : statistiques et journaux du serveur.
• Gestion des utilisateurs : utilisateurs, groupes, communautés (listées en tant qu'Équipes), canaux, permissions et administration déléguée.
• Attributs système : attributs de profil personnalisés et accès basé sur les attributs.
• Environnement : serveur web, base de données, stockage de fichiers, proxy d'images, SMTP, notifications push, limitation de débit, journalisation, durées de session, surveillance des performances.
• Configuration du site : identité visuelle, utilisateurs et équipes, notifications, messages, partage de fichiers et autres comportements globaux du serveur.
• Authentification : inscription, connexion par e-mail et mot de passe, MFA, AD/LDAP, SAML 2.0, OAuth 2.0, OpenID Connect et accès invité.
• IA : connexions aux modèles et fonctionnalités intégrées d'IA (réécriture, résumés, traduction automatique, synthèse vocale). Voir IA.
• Plugins : gestion des applications et paramètres de chaque application installée.
• Intégrations : webhooks, commandes slash, comptes de bots, GIFs, synthèse vocale, CORS.
• Conformité : rétention des données, export et surveillance de la conformité, journal d’audit, conditions d’utilisation personnalisées.
• Fonctionnalités expérimentales : fonctionnalités susceptibles d’évoluer.

Dans ce guide, un paramètre est indiqué par son chemin dans la Console système, puis son libellé, puis sa clé de configuration, par exemple Console système › Configuration du site › Utilisateurs et équipes › Activer l’ignorance, le blocage et les demandes de message (PrivacySettings.EnableUserBlocking).

La plupart des modifications s’appliquent dès que vous cliquez sur Enregistrer. Quelques-unes (l’adresse d’écoute, certains paramètres de base de données et de cache) nécessitent un redémarrage, et la page l’indique.

Entreprise ou communauté

Chaque communauté a un type, qui définit certains de ses paramètres par défaut :

• Communauté, pour une communauté publique ou de loisir : les appels sont désactivés dans ses canaux (les personnes parlent dans les canaux vocaux), et seuls ses administrateurs, ainsi que les rôles qui gèrent les canaux, peuvent les archiver.
• Entreprise, pour une entreprise ou une organisation : les appels sont activés dans ses canaux, et les administrateurs d'un canal (celui qui l'a créé, ainsi que ceux qu'ils ont nommés administrateurs) peuvent également l'archiver.

Console système › Configuration du site › Utilisateurs et équipes › Type des nouvelles communautés (TeamSettings.DefaultCommunityKind, AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND) est le type des communautés créées à partir de ce moment : community (par défaut) ou workplace. Un préréglage de mise en page choisi lors de la création d'une communauté définit son propre type. Les administrateurs de chaque communauté peuvent modifier son type ultérieurement, dans Paramètres de l’équipe › Canaux › Type de la communauté.

L’outil en ligne de commande amctl

amctl permet de gérer un serveur depuis la ligne de commande : utilisateurs, communautés, canaux, applications, configuration, tâches, etc. Il communique avec le serveur de l’une des deux manières suivantes.

Mode local, sur le serveur

Le mode local permet à amctl de communiquer avec le serveur via un socket Unix, sans s'identifier. Il est activé dans l'image Docker ainsi que dans les paquets .deb et .rpm. Sur un serveur installé à partir d'une archive, activez-le avec ServiceSettings.EnableLocalMode (AM_SERVICESETTINGS_ENABLELOCALMODE=true). Le socket est par défaut /var/tmp/antimatter_local.socket (ServiceSettings.LocalModeSocketLocation).

# with Docker Compose
docker compose exec antimatter amctl --local system status
# with a release archive
sudo -u antimatter /opt/antimatter/bin/amctl --local system status
# with the .deb or .rpm package
sudo -u antimatter amctl --local system status

À distance, avec un compte

Depuis n’importe quel appareil, connectez-vous avec un compte d’administrateur système (ou un jeton d’accès personnel), puis exécutez des commandes sur ce serveur :

amctl auth login https://chat.example.com --name prod --username admin
amctl system status

Commandes de configuration

Les paramètres des applications se trouvent sous PluginSettings.Plugins.<app id>, avec des clés en minuscules. Par exemple, pour définir l’URL de service et la clé de l’application GIF depuis l’hôte Docker :

docker compose exec -T antimatter amctl --local config patch /dev/stdin <<'EOF'
{"PluginSettings": {"Plugins": {"com.antimatterchat.gifs": {
  "serviceurl": "http://gifs:8080/v2",
  "apikey": "the GIFS_API_KEY of your .env"
}}}}
EOF

Autres commandes utiles : amctl user create, amctl user deactivate, amctl team create, amctl plugin list, amctl plugin enable, amctl system supportpacket et amctl logs. Exécutez amctl help <command> pour voir les options de chacune.

Journaux

Le serveur écrit ses journaux dans deux emplacements, chacun avec son propre niveau (DEBUG, INFO, WARN ou ERROR), défini dans Console système › Environnement › Journalisation :

Les fichiers journaux sont archivés à 100 Mo et les anciens sont compressés.

Le fichier compose du site désactive la journalisation dans un fichier (AM_LOGSETTINGS_ENABLEFILE=false), de sorte que les journaux ne sont disponibles que dans la sortie du conteneur :

docker compose logs -f antimatter
docker compose logs --since 1h antimatter | grep -i error

Le niveau de la console est par défaut DEBUG, ce qui est très détaillé. Sur un serveur très sollicité, définissez AM_LOGSETTINGS_CONSOLELEVEL=INFO. Le fichier config.json de l'archive de publication et des paquets est déjà configuré sur INFO. Avec une archive de publication sous systemd, la sortie de la console est envoyée au journal (journalctl -u antimatter) et le fichier journal est situé dans /opt/antimatter/logs/antimatter.log. Les paquets désactivent la journalisation dans un fichier, de sorte que leurs journaux ne sont disponibles que dans le journal système.

Lorsque la journalisation dans un fichier est activée, les administrateurs système peuvent également lire les dernières lignes du journal dans Console système › Rapport › Journaux du serveur, ou avec amctl logs.