Configuratie

Waar Antimatter zijn instellingen bewaart, de drie manieren om ze te wijzigen (Systeemconsole, omgevingsvariabelen, amctl) en waar de logs terechtkomen.

Waar de instellingen staan

Elke serverinstelling heeft een naam die bestaat uit een sectie en een sleutel, zoals ServiceSettings.SiteURL of EmailSettings.SMTPServer. Samen vormen ze één configuratie, die in een van de twee volgende locaties wordt opgeslagen:

• In de database. Het compose-bestand van de site zet AM_CONFIG in op de verbindings-URL van PostgreSQL, zodat de configuratie een rij in de database is en de container niets op de schijf bewaart. Meerdere servers die één database delen, delen ook hun configuratie.
• In een bestand. Zonder AM_CONFIG leest de server config/config.json naast de bin/-map (/antimatter/config/config.json in de Docker-image). De release-archief en de productie-compose-bestanden van antimatter-docker werken zo, net als de .deb- en .rpm-pakketten, waarvan het bestand /etc/antimatter/config/config.json heet. Houd dit bestand alleen leesbaar voor de gebruiker van de server: het bevat wachtwoorden en sleutels.

AM_CONFIG (of de --config-vlag van het antimatter-commando) accepteert zowel een bestandspad als een postgres://-URL. Instellingen die u niet opgeeft, krijgen hun standaardwaarde.

Om een bestaande configuratie van een bestand naar de database te verplaatsen, voert u dit op de server uit en start u de server daarna op met AM_CONFIG ingesteld op dezelfde URL:

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

Omgevingsvariabelen

Elke instelling kan ook als omgevingsvariabele worden opgegeven. Variabelen hebben voorrang op de opgeslagen configuratie, wat ze geschikt maakt voor wat bij de implementatie hoort: de database, de site-URL, de opslag van bestanden, de poorten.

Naamgevingsregel

Schrijf AM_, dan de sectie, dan de sleutel, in hoofdletters en gescheiden door underscores. De woorden binnen een sectie- of sleutelnaam worden niet gescheiden:

• Instellingen met een booleaanse waarde nemen true of false; getallen zijn gewone getallen.
• Lijst-instellingen nemen waarden gescheiden door spaties, bijvoorbeeld AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP".
• Instellingen die objecten zijn, nemen JSON. De enige dergelijke variabele voor apps is AM_PLUGINSETTINGS_PLUGINS, en deze vervangt de instellingen van elke app tegelijk: stel app-instellingen in via de Systeemconsole of met amctl (zie hieronder).
• Oudere Mattermost-installaties gebruiken het voorvoegsel MM_, bijvoorbeeld MM_SQLSETTINGS_DATASOURCE. Dit werkt nog steeds als verouderde alias. Als beide zijn ingesteld, heeft de AM_-variabele voorrang.

Een instelling die via een variabele is gegeven, is vergrendeld in de Systeemconsole, met de melding "Deze instelling is ingesteld via een omgevingsvariabele. Hij kan niet worden gewijzigd via de Systeemconsole." Hij wordt niet naar de opgeslagen configuratie geschreven: verwijder de variabele en de opgeslagen waarde wordt weer toegepast.

Met Docker Compose

Voeg variabelen toe onder environment: van de antimatter-service, of in een compose.override.yaml naast compose.yaml (Compose leest dit automatisch en het blijft behouden bij updates van het gedownloade bestand):

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

Pas wijzigingen toe met docker compose up -d, wat de container opnieuw aanmaakt.

Variabelen die door de apps worden gelezen

Enkele variabelen zijn geen instellingen en hebben geen veld in de Systeemconsole: AM_CONFIG (waar de configuratie staat), en AM_AI_ENCRYPTION_KEY en AM_AI_ENCRYPTION_PREVIOUS_KEYS, de sleutel die de API-sleutels van modelverbindingen versleutelt (zie AI).

Een aantal apps leest hun eigen variabelen, ingesteld op de antimatter-service: de Calls-app leest AM_CALLS_* (zie Gesprekken en spraak), en de GIFs-app leest AM_GIFS_SERVICE_URL, AM_GIFS_API_KEY en AM_GIFS_UPLOAD_KEY (zie Ingebouwde apps).

De Systeemconsole

De Systeemconsole is het beheergebied van de webapp, voor systeembeheerders. Om deze te openen, klikt u op uw foto bovenaan de apprail en kiest u Systeem console, of gaat u naar https://chat.example.com/admin_console. De zijbalk bevat een Instellingen zoeken-vak dat alle pagina's doorzoekt.

De secties zijn:

• Rapportage: statistieken en de serverlogboeken.
• Gebruikersbeheer: gebruikers, groepen, gemeenschappen (vermeld als Teams), kanalen, machtigingen en gedelegeerd beheer.
• Systeemkenmerken: aangepaste profielkenmerken en op kenmerken gebaseerde toegang.
• Omgeving: webserver, database, opslag van bestanden, afbeeldingsproxy, SMTP, pushmeldingen, limieten voor verzoeken, loggen, sessieduur en prestatiebewaking.
• Site Configuratie: huisstijl, gebruikers en teams, meldingen, berichten, bestanddelen en andere serverbrede instellingen.
• Authenticatie: registratie, inloggen met e-mail en wachtwoord, MFA, AD/LDAP, SAML 2.0, OAuth 2.0, OpenID Connect en gasttoegang.
• AI: modelverbindingen en de ingebouwde AI-functies (herformuleren, samenvattingen, automatische vertaling, tekst-naar-spraak). Zie AI.
• Plugins: appbeheer en de instellingen van elke geïnstalleerde app.
• Integraties: webhooks, slash-opdrachten, bot-accounts, GIFs, tekst-naar-spraak, CORS.
• Voldoet aan: bewaartermijnen, export en bewaking voor compliance, auditloggen en aangepaste servicevoorwaarden.
• Experimenteel: functies die kunnen veranderen.

In deze handleiding wordt een instelling aangegeven door het pad in de Systeemconsole, gevolgd door de labelnaam en de configuratie-sleutel. Bijvoorbeeld Systeemconsole › Site Configuratie › Gebruikers en Teams › Negeren, blokkeren en berichtverzoeken inschakelen (PrivacySettings.EnableUserBlocking).

De meeste wijzigingen worden toegepast zodra u op Opslaan klikt. Een paar (het luisteradres, sommige database- en cache-instellingen) vereist een herstart, en de pagina geeft dit aan.

Werkplek of community

Elke community heeft een type, dat enkele standaardwaarden bepaalt:

• Community, voor een publieke of hobby-community: gesprekken zijn uitgeschakeld in de kanalen (mensen praten in spraakkanaal), en alleen de beheerders en de rollen die kanalen beheren, kunnen kanalen archiveren.
• Werkplek, voor een bedrijf of organisatie: gesprekken zijn ingeschakeld in de kanalen, en de beheerders van een kanaal (de maker en degenen die zij tot beheerder hebben benoemd) kunnen het ook archiveren.

Systeem console › Site Configuratie › Gebruikers en Teams › Type van nieuwe communities (TeamSettings.DefaultCommunityKind, AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND) is het type van de communities die vanaf dan worden aangemaakt: community (standaard) of workplace. Een layout-preset gekozen bij het aanmaken van een community stelt het eigen type in. De beheerders van elke community kunnen het type later wijzigen in Teaminstellingen › Kanalen › Type van community.

Het commandoregelhulpmiddel amctl

amctl beheert een server vanaf de commandoregel: gebruikers, communities, kanalen, apps, configuratie, taken en meer. Het communiceert met de server op een van de twee manieren.

Lokale modus, op de server

Lokale modus laat amctl met de server communiceren via een Unix-socket, zonder in te loggen. Deze modus is ingeschakeld in het Docker-image en bij de .deb- en .rpm-pakketten. Op een server die is geïnstalleerd uit een archief, schakelt u deze in met ServiceSettings.EnableLocalMode (AM_SERVICESETTINGS_ENABLELOCALMODE=true). De socket is standaard /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

Afstand, met een account

Vanaf elk apparaat, log in met een systeembeheerderaccount (of een persoonlijke toegangstoken), en voer dan commando's uit tegen die server:

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

Configuratiecommando's

App-instellingen staan onder PluginSettings.Plugins.<app id>, met sleutels in kleine letters. Bijvoorbeeld, om de service-URL en sleutel van de GIFs-app in te stellen vanaf de Docker-host:

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

Andere nuttige opdrachten: amctl user create, amctl user deactivate, amctl team create, amctl plugin list, amctl plugin enable, amctl system supportpacket en amctl logs. Voer amctl help <command> uit voor de opties van elke opdracht.

Logboeken

De server schrijft zijn log naar twee locaties, elk met een eigen niveau (DEBUG, INFO, WARN of ERROR), ingesteld in Systeemconsole › Omgeving › Loggen:

Logbestanden worden geroteerd bij 100 MB en de oudere bestanden gecomprimeerd.

Het compose-bestand van de site schakelt het loggen naar een bestand uit (AM_LOGSETTINGS_ENABLEFILE=false), zodat de logboeken alleen in de container-uitvoer staan:

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

Het niveau van de console is standaard DEBUG, wat veel details toont. Op een drukke server stelt u AM_LOGSETTINGS_CONSOLELEVEL=INFO in. De config.json van het release-archief en van de pakketten is al ingesteld op INFO. Bij een release-archief onder systemd gaat de console-uitvoer naar het journal (journalctl -u antimatter) en het logbestand naar /opt/antimatter/logs/antimatter.log. De pakketten schakelen loggen naar bestand uit, zodat de logs alleen in het journal staan.

Wanneer loggen naar bestand is ingeschakeld, kunnen systeembeheerders de nieuwste logregels ook lezen in Systeemconsole › Rapportage › Server Logs, of met amctl logs.