Configure the network environment in which Mattermost is deployed by going to System Console > Environment > Web Server, or by updating the config.json file as described in the following tables. Changes to configuration settings in this section require a server restart before taking effect.

Site URL#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The URL that users use to access Mattermost. The port number is required if it’s not a standard port, such as 80 or 443. This field is required.

Select the Test Live URL button in the System Console to validate the Site URL.

  • System Config path: Environment > Web Server

  • config.json setting: .ServiceSettings.SiteURL",

  • Environment variable: MM_SERVICESETTINGS_SITEURL

Notes:

  • The URL may contain a subpath, such as https://example.com/company/mattermost.

  • If you change the Site URL value, log out of the Desktop App, and sign back in using the new domain.

  • If Site URL is not set:

    • Email notifications will contain broken links, and email batching will not work.

    • Authentication via OAuth 2.0, including GitLab, Google, and Entra ID, will fail.

    • Plugins may not work as expected.

Web server listen address#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The address and port to which to bind and listen. Specifying :8065 will bind to all network interfaces. Specifying 127.0.0.1:8065 will only bind to the network interface having that IP address.

If you choose a port of a lower level (called “system ports” or “well-known ports”, in the range of 0-1023), you must have permissions to bind to that port.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.ListenAddress",

  • Environment variable: MM_SERVICESETTINGS_LISTENADDRESS

Forward port 80 to 443#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Forward insecure traffic from port 80 to port 443.

  • true: Forwards all insecure traffic from port 80 to secure port 443.

  • false: (Default) When using a proxy such as NGINX in front of Mattermost this setting is unnecessary and should be set to false.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.Forward80To443: false",

  • Environment variable: MM_SERVICESETTINGS_FORWARD80TO443

Web server connection security#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Connection security between Mattermost clients and the server.

  • Not specified: Mattermost will connect over an unsecure connection.

  • TLS: Encrypts the communication between Mattermost clients and your server. See the configuring TLS on Mattermost for more details.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.ConnectionSecurity",

  • Environment variable: MM_SERVICESETTINGS_CONNECTIONSECURITY

TLS certificate file#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The path to the certificate file to use for TLS connection security.

String input.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.TLSCertFile",

  • Environment variable: MM_SERVICESETTINGS_TLSCERTFILE

TLS key file#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The path to the TLS key file to use for TLS connection security.

String input.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.TLSKeyFile",

  • Environment variable: MM_SERVICESETTINGS_TLSKEYFILE

Use Let’s Encrypt#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable the automatic retrieval of certificates from Let’s Encrypt. See the configuring TLS on Mattermost documentation for more details on setting up Let’s Encrypt.

  • true: The certificate will be retrieved when a client attempts to connect from a new domain. This will work with multiple domains.

  • false: (Default) Manual certificate specification based on the TLS Certificate File and TLS Key File specified above.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.UseLetsEncrypt: false",

  • Environment variable: MM_SERVICESETTINGS_USELETSENCRYPT

Let’s Encrypt certificate cache file#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The path to the file where certificates and other data about the Let’s Encrypt service will be stored.

File path input.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.LetsEncryptCertificateCacheFile",

  • Environment variable: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE

Read timeout#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Maximum time allowed from when the connection is accepted to when the request body is fully read.

Numerical input in seconds. Default is 300 seconds.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.ReadTimeout: 300",

  • Environment variable: MM_SERVICESETTINGS_READTIMEOUT

Write timeout#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • If using HTTP (insecure), this is the maximum time allowed from the end of reading the request headers until the response is written.

  • If using HTTPS, it’s the total time from when the connection is accepted until the response is written.

Numerical input in seconds. Default is 300 seconds.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.WriteTimeout: 300",

  • Environment variable: MM_SERVICESETTINGS_WRITETIMEOUT

Idle timeout#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Set an explicit idle timeout in the HTTP server. This is the maximum time allowed before an idle connection is disconnected.

Numerical input in seconds. Default is 300 seconds.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.IdleTimeout: 300",

  • Environment variable: MM_SERVICESETTINGS_IDLETIMEOUT

Webserver mode#

Also available in legacy Mattermost Enterprise Edition E10 or E20

We recommend gzip to improve performance unless your environment has specific restrictions, such as a web proxy that distributes gzip files poorly.

  • gzip: (Default) The Mattermost server will serve static files compressed with gzip to improve performance. gzip compression applies to the HTML, CSS, Javascript, and other static content files that make up the Mattermost web client.

  • Uncompressed: The Mattermost server will serve static files uncompressed.

  • Disabled: The Mattermost server will not serve static files.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.WebserverMode: gzip",

  • Environment variable: MM_SERVICESETTINGS_WEBSERVERMODE

Enable insecure outgoing connections#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Configure Mattermost to allow insecure outgoing connections.

  • true: Outgoing HTTPS requests, including S3 clients, can accept unverified, self-signed certificates. For example, outgoing webhooks to a server with a self-signed TLS certificate, using any domain, will be allowed, and will skip TLS verification.

  • false: (Default) Only secure HTTPS requests are allowed.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.EnableInsecureOutgoingConnections: false",

  • Environment variable: MM_SERVICESETTINGS_ENABLEINSECUREOUTGOINGCONNECTIONS

Security note: Enabling this feature makes these connections susceptible to man-in-the-middle attacks.

Managed resource paths#

Also available in legacy Mattermost Enterprise Edition E10 or E20

A comma-separated list of paths within the Mattermost domain that are managed by a third party service instead of Mattermost itself.

Links to these paths will be opened in a new tab/window by Mattermost apps.

For example, if Mattermost is running on https://mymattermost.com, setting this to conference will cause links such as https://mymattermost.com/conference to open in a new window.

  • System Config path: Environment > Web Server

  • config.json setting: ".ServiceSettings.ManagedResourcePaths",

  • Environment variable: MM_SERVICESETTINGS_MANAGEDRESOURCEPATHS

Note: When using the Mattermost Desktop App, additional configuration is required to open the link within the Desktop App instead of in a browser. See the desktop managed resources documentation for details.

Reload configuration from disk#

Note

plans-img-yellow Available only on Enterprise plans

Also available in legacy Mattermost Enterprise Edition E10 or E20

You must change the database line in the config.json file, and then reload configuration to fail over without taking the server down.

Select the Reload configuration from disk button in the System Console after changing your database configuration. Then, go to Environment > Database and select Recycle Database Connections to complete the reload.

  • System Config path: Environment > Web Server

  • config.json setting: N/A

  • Environment variable: N/A

Purge all caches#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Purge all in-memory caches for sessions, accounts, and channels.

Select the Purge All Caches button in the System Console to purge all caches.

  • System Config path: Environment > Web Server

  • config.json setting: N/A

  • Environment variable: N/A

Note: Purging the caches may adversely impact performance. high availability cluster-based deployments will attempt to purge all the servers in the cluster

Websocket URL#

Also available in legacy Mattermost Enterprise Edition E10 or E20

You can configure the server to instruct clients on where they should try to connect websockets to.

String input.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.WebsocketURL: "",

  • Environment variable: MM_SERVICESETTINGS_WEBSOCKETURL

Note: We strongly recommend configuring a single websocket URL that matches the Site URL configuration setting.

License file location#

Note

plans-img-yellow Available only on Enterprise and Professional plans

Also available in legacy Mattermost Enterprise Edition E10 or E20

The path and filename of the license file on disk. On startup, if Mattermost can’t find a valid license in the database from a previous upload, it looks in this path for the license file.

String input. Can be an absolute path or a path relative to the mattermost directory.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.LicenseFileLocation: "",

  • Environment variable: MM_SERVICESETTINGS_LICENSEFILELOCATION

TLS minimum version#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The minimum TLS version used by the Mattermost server.

String input. Default is 1.2.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TLSMinVer: 1.2",

  • Environment variable: MM_SERVICESETTINGS_TLSMINVER

Note: This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy layer, such as NGINX.

Trusted proxy IP header#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Specified headers that will be checked, one by one, for IP addresses (order is important). All other headers are ignored.

String array input consisting of header names, such as ["X-Forwarded-For", "X-Real-Ip"].

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TrustedProxyIPHeader: []",

  • Environment variable: MM_SERVICESETTINGS_TRUSTEDPROXYIPHEADER

Notes:

  • The default value of [] means that no header will be trusted. Prior to v5.12, the absence of this configuration setting entry will have it set to ["X-Forwarded-For", "X-Real-Ip"] on upgrade to maintain backwards compatibility.

  • We recommend keeping the default setting when Mattermost is running without a proxy to avoid the client sending the headers and bypassing rate limiting and/or the audit log.

  • For environments that use a reverse proxy, this issue does not exist, provided that the headers are set by the reverse proxy. In those environments, only explicitly whitelist the header set by the reverse proxy and no additional values.

Enable Strict Transport Security (HSTS)#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • true: Adds the Strict Transport Security (HSTS) header to all responses, forcing the browser to request all resources via HTTPS.

  • false: (Default) No restrictions on TLS transport. Strict Transport Security (HSTS) header isn’t added to responses.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TLSStrictTransport: false",

  • Environment variable: MM_SERVICESETTINGS_TLSSTRICTTRANSPORT

See the Strict-Transport-Security documentation for details.

Secure TLS transport expiry#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The time, in seconds, that the browser remembers a site is only to be accessed using HTTPS. After this period, a site can’t be accessed using HTTP unless TLSStrictTransport is set to true.

Numerical input. Default is 63072000 (2 years).

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TLSStrictTransportMaxAge: 63072000",

  • Environment variable: MM_SERVICESETTINGS_TLSSTRICTTRANSPORTMAXAGE

See the Strict-Transport-Security documentation for details.

TLS cipher overwrites#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Set TLS ciphers overwrites to meet requirements from legacy clients which don’t support modern ciphers, or to limit the types of accepted ciphers.

If none specified, the Mattermost server assumes a set of currently considered secure ciphers, and allows overwrites in the edge case.

String array input.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.TLSOverwriteCiphers: []",

  • Environment variable: MM_SERVICESETTINGS_TLSOVERWRITECIPHERS

Notes:

  • This setting only takes effect if you are using the built-in server binary directly, and not using a reverse proxy layer, such as NGINX.

  • See the ServerTLSSupportedCiphers variable in /model/config.go for a list of ciphers considered secure.

Goroutine health threshold#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Set a threshold on the number of goroutines when the Mattermost system is considered to be in a healthy state.

When goroutines exceed this limit, a warning is returned in the server logs.

Numeric input. Default is -1 which turns off checking for the threshold.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.GoroutineHealthThreshold: -1",

  • Environment variable: MM_SERVICESETTINGS_GOROUTINEHEALTHTHRESHOLD

Allow cookies for subdomains#

Also available in legacy Mattermost Enterprise Edition E10 or E20

  • true: (Default) Allows cookies for subdomains by setting the domain parameter on Mattermost cookies.

  • false: Cookies not allowed for subdomains.

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.AllowCookiesForSubdomains: true",

  • Environment variable: MM_SERVICESETTINGS_ALLOWCOOKIESFORSUBDOMAINS

Cluster log timeout#

Note

plans-img-yellow Available only on Enterprise plans

Also available in legacy Mattermost Enterprise Edition E20

Define the frequency, in milliseconds, of cluster request time logging for performance monitoring.

Numerical input. Default is 2000 milliseconds (2 seconds).

  • System Config path: N/A

  • config.json setting: ".ServiceSettings.ClusterLogTimeoutMilliseconds: 2000",

  • Environment variable: MM_SERVICESETTINGS_CLUSTERLOGTIMEOUTMILLISECONDS

See the performance monitoring documentation for details.