Configurazione

Dove Antimatter conserva le sue impostazioni, i tre modi per modificarle (Console di Sistema, variabili di ambiente, amctl) e dove vengono scritti i log.

Dove risiedono le impostazioni

Ogni impostazione del server ha un nome composto da una sezione e una chiave, ad esempio ServiceSettings.SiteURL o EmailSettings.SMTPServer. Insieme formano una configurazione, conservata in uno di due posti:

Nel database. Il file di compose del sito imposta AM_CONFIG all'URL di connessione PostgreSQL, quindi la configurazione è una riga nel database e il contenitore non conserva nulla su disco. Più server che condividono un unico database condividono anche la loro configurazione.
In un file. Senza AM_CONFIG, il server legge config/config.json accanto alla directory bin/ (/antimatter/config/config.json nell'immagine Docker). Il pacchetto di rilascio e i file compose di produzione di antimatter-docker funzionano in questo modo, così come i pacchetti .deb e .rpm, il cui file è /etc/antimatter/config/config.json. Mantieni questo file leggibile solo dall'utente del server: contiene password e chiavi.

AM_CONFIG (o il flag --config del comando antimatter) accetta un percorso di file o un URL postgres://. Le impostazioni che non specifichi assumono il loro valore predefinito.

Per spostare una configurazione esistente da un file al database, esegui questo sul server, poi avvia il server con AM_CONFIG impostato sullo stesso URL:

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

Variabili di ambiente

Qualsiasi impostazione può anche essere fornita come variabile di ambiente. Le variabili hanno la priorità sulla configurazione memorizzata, il che le rende adatte a ciò che appartiene alla distribuzione: il database, l'URL del sito, l'archiviazione dei file, le porte.

Regola di denominazione

Scrivi AM_, poi la sezione, poi la chiave, in maiuscolo e separate da trattini bassi. Le parole all'interno di un nome di sezione o chiave non sono separate:

Impostazione	Variabile
`ServiceSettings.SiteURL`	`AM_SERVICESETTINGS_SITEURL`
`SqlSettings.DataSource`	`AM_SQLSETTINGS_DATASOURCE`
`EmailSettings.SMTPServer`	`AM_EMAILSETTINGS_SMTPSERVER`
`PrivacySettings.EnableUserBlocking`	`AM_PRIVACYSETTINGS_ENABLEUSERBLOCKING`

Le impostazioni booleane accettano true o false; i numeri sono numeri semplici.
Le impostazioni di elenco accettano i loro valori separati da spazi, ad esempio AM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER="X-Forwarded-For X-Real-IP".
Le impostazioni che sono oggetti accettano JSON. L'unica variabile di questo tipo per le app è AM_PLUGINSETTINGS_PLUGINS, e sostituisce le impostazioni di tutte le app in una volta sola: imposta le impostazioni delle app nella Console di Sistema o con amctl invece (vedi sotto).
Le configurazioni Mattermost precedenti utilizzano il prefisso MM_, ad esempio MM_SQLSETTINGS_DATASOURCE. Funziona ancora come alias legacy. Se entrambe le variabili sono impostate, quella con il prefisso AM_ ha la precedenza.

Un'impostazione definita tramite variabile è bloccata nella Console di Sistema, con la nota "Questa impostazione è stata configurata tramite una variabile d'ambiente. Non può essere modificata tramite la Console di Sistema." Non viene scritta nella configurazione salvata: rimuovi la variabile e il valore salvato verrà nuovamente applicato.

Con Docker Compose

Aggiungi le variabili sotto environment: del servizio antimatter, oppure in un file compose.override.yaml accanto a compose.yaml (Compose lo legge automaticamente e il file sopravvive agli aggiornamenti del file scaricato):

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

Applica le modifiche con docker compose up -d, che ricrea il contenitore.

Variabili lette dalle app

Alcune variabili non sono impostazioni e non hanno un campo nella Console di Sistema: AM_CONFIG (dove si trova la configurazione) e AM_AI_ENCRYPTION_KEY e AM_AI_ENCRYPTION_PREVIOUS_KEYS, la chiave che cifra le chiavi API delle connessioni ai modelli (vedi AI).

Alcune app leggono le proprie variabili, impostate sul servizio antimatter: l'app Chiamate legge AM_CALLS_* (vedi Chiamate e voce), e l'app GIF legge AM_GIFS_SERVICE_URL, AM_GIFS_API_KEY e AM_GIFS_UPLOAD_KEY (vedi App integrate).

La Console di Sistema

La Console di Sistema è l'area di amministrazione dell'app web, destinata agli amministratori di sistema. Per aprirla, clicca sulla tua immagine in alto nella barra laterale dell'app e scegli Console di Sistema, oppure vai a https://chat.example.com/admin_console. La sua barra laterale ha una casella Trova impostazioni che cerca in tutte le pagine.

The System Console, with its sidebar of sections on the left and the SAML 2.0 settings page on the right. — La Console di Sistema. La barra laterale raggruppa le pagine in sezioni come Reporting, Gestione utenti e Ambiente.

Le sue sezioni sono:

Segnalazione: statistiche e registri del server.
Gestione utenti: utenti, gruppi, community (elenchati come Team), canali, permessi e amministrazione delegata.
Attributi di sistema: attributi personalizzati del profilo e accesso basato su attributi.
Ambiente: server web, database, archiviazione file, proxy immagini, SMTP, notifiche push, limitazione delle richieste, registrazione eventi, durata delle sessioni, monitoraggio delle prestazioni.
Configurazione sito: branding, utenti e squadre, notifiche, post, condivisione dei file e altri comportamenti a livello di server.
Autenticazione: registrazione, accesso tramite email e password, MFA, AD/LDAP, SAML 2.0, OAuth 2.0, OpenID Connect e accesso per ospiti.
AI: connessioni ai modelli e le funzionalità AI integrate (riscrittura, riassunti, traduzione automatica, sintesi vocale). Vedi AI.
Plugins: gestione delle app e le impostazioni di ciascuna app installata.
Integrazioni: webhook, comandi con barra, account bot, GIF, sintesi vocale, CORS.
Conformità: conservazione dei dati, esportazione e monitoraggio della conformità, registri di audit, termini di servizio personalizzati.
Sperimentale: funzionalità che potrebbero cambiare.

In questa guida, un'impostazione è indicata come il suo percorso nella Console di Sistema, poi la sua etichetta, poi la sua chiave di configurazione, ad esempio Console di Sistema › Configurazione sito › Utenti e squadre › Attiva ignorare, bloccare e richieste di messaggio (PrivacySettings.EnableUserBlocking).

La maggior parte delle modifiche viene applicata non appena si fa clic su Salva. Alcune (l'indirizzo di ascolto, alcune impostazioni del database e della cache) richiedono un riavvio, come indicato nella pagina.

Ambiente di lavoro o comunità

Ogni comunità ha un tipo, che ne definisce alcuni valori predefiniti:

Comunità, per una comunità pubblica o amatoriale: le chiamate sono disattivate nei suoi canali (le persone parlano nei canali vocali) e solo i suoi amministratori, e i ruoli che gestiscono i canali, possono archiviarli.
Ambiente di lavoro, per un'azienda o un'organizzazione: le chiamate sono attive nei suoi canali e gli amministratori di un canale (chiunque l'abbia creato, e quelli a cui hanno conferito i diritti di amministratore) possono archiviarlo.

Console di Sistema › Configurazione sito › Utenti e squadre › Tipo di nuove community (TeamSettings.DefaultCommunityKind, AM_TEAMSETTINGS_DEFAULTCOMMUNITYKIND) definisce il tipo delle community create in seguito: community (valore predefinito) o workplace. Un preset di layout scelto durante la creazione di una community ne imposta il tipo. Gli amministratori di ogni community possono modificarne il tipo in seguito, in Impostazioni del team › Canali › Tipo di community.

Per un'azienda, impostalo su Ambiente di lavoro prima di creare la prima community, oppure prima di aggiornare un server esistente alla versione 0.9.0: l'aggiornamento assegna a ogni community esistente il valore impostato in quel momento (vedi Aggiornamento alla versione 0.9.0).

Lo strumento da riga di comando amctl

amctl gestisce un server da riga di comando: utenti, community, canali, app, configurazione, attività e altro ancora. Comunica con il server in uno di due modi.

Modalità locale, sul server

La modalità locale consente a amctl di comunicare con il server tramite un socket Unix, senza effettuare l'accesso. È abilitata nell'immagine Docker e nei pacchetti .deb e .rpm. Su un server installato da un archivio, attivala con ServiceSettings.EnableLocalMode (AM_SERVICESETTINGS_ENABLELOCALMODE=true). Il socket è /var/tmp/antimatter_local.socket per impostazione predefinita (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

Chiunque possa utilizzare il socket, o eseguire docker compose exec sull'host, dispone di pieni diritti di amministratore di sistema.

Remoto, con un account

Da qualsiasi macchina, accedi con un account di amministratore di sistema (o con un token di accesso personale), quindi esegui i comandi su quel server:

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

Comandi di configurazione

Comando	Funzione
`amctl config get ServiceSettings.SiteURL`	Stampa un'impostazione.
`amctl config set TeamSettings.EnableOpenServer false`	Modifica un'impostazione. Le impostazioni di tipo elenco accettano più valori.
`amctl config patch settings.json`	Fonde un file JSON di impostazioni nella configurazione.
`amctl config show`	Stampa l'intera configurazione in formato JSON.
`amctl config edit`	Apre la configurazione nell'editor (`$EDITOR`).
`amctl config reset`	Reimposta le impostazioni ai valori predefiniti.
`amctl config reload`	Ricarica la configurazione dalla sua posizione di archiviazione, dopo una modifica eseguita al di fuori del server.

Le impostazioni delle app si trovano sotto PluginSettings.Plugins.<app id>, con chiavi in minuscolo. Ad esempio, per impostare l'URL del servizio e la chiave dell'app GIF dall'host 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

Altri comandi utili: amctl user create, amctl user deactivate, amctl team create, amctl plugin list, amctl plugin enable, amctl system supportpacket e amctl logs. Esegui amctl help <command> per le opzioni di ciascuno.

Log

Il server scrive i log in due posizioni, ciascuna con il proprio livello (DEBUG, INFO, WARN o ERROR), configurato in Console di Sistema › Ambiente › Registrazione:

Destinazione	Impostazioni	Valori predefiniti
La console (output standard)	Scrive i logs sulla console (`LogSettings.EnableConsole`), Livello log di console (`LogSettings.ConsoleLevel`), Log su console in formato JSON (`LogSettings.ConsoleJson`)	attivo, `DEBUG`, JSON
Un file, `antimatter.log`	File di log (`LogSettings.EnableFile`), Livello di log file (`LogSettings.FileLevel`), Cartella file di log (`LogSettings.FileLocation`)	attivo, `INFO`, la directory `logs/` accanto a `bin/`

I file di log vengono ruotati a 100 MB e quelli vecchi compressi.

Il file compose del sito disattiva la registrazione in file (AM_LOGSETTINGS_ENABLEFILE=false), quindi i log sono presenti solo nell'output del contenitore:

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

Il livello di console è impostato su DEBUG per impostazione predefinita, il che è molto verboso. Su un server molto attivo, imposta AM_LOGSETTINGS_CONSOLELEVEL=INFO. Il file config.json dell'archivio di rilascio e dei pacchetti lo ha già impostato su INFO. Con un archivio di rilascio sotto systemd, l'output della console va al journal (journalctl -u antimatter) e il file a /opt/antimatter/logs/antimatter.log. I pacchetti disattivano la registrazione su file, quindi i loro log sono presenti solo nel journal.

Quando la registrazione su file è attiva, gli amministratori di sistema possono anche leggere le ultime righe di log in Console di Sistema › Segnalazione › Log del Server, oppure con amctl logs.