Web server configuration settings

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 table. Changes to configuration settings in this section require a server restart before taking effect.

Tip

Each configuration value below includes a JSON path to access the value programmatically in the config.json file using a JSON-aware tool. For example, the SiteURL value is under ServiceSettings.

If using a tool such as jq, you’d enter: cat config/config.json | jq '.ServiceSettings.SiteURL'
When working with the config.json file manually, look for the key ServiceSettings, then within that object, find the key SiteURL.

Site URL

Available in legacy Enterprise Edition E10/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 Office 365, will fail.
- Plugins may not work as expected.

Listen address

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/E20

Forward insecure traffic from port 80 to port 442.

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

Connection security

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/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

TSL key file

Available in legacy Enterprise Edition E10/E20

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

String input

System Config path: REnvironment > Web Server
config.json setting: ".ServiceSettings.TLSKeyFile",
Environment variable: MM_SERVICESETTINGS_TLSKEYFILE

Use Let’s Encrypt

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/E20

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

File path

System Config path: Reporting > Team Statistics
config.json setting: ".ServiceSettings.LetsEncryptCertificateCacheFile",
Environment variable: MM_SERVICESETTINGS_LETSENCRYPTCERTIFICATECACHEFILE

Read timeout

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/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. 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.WriteTimeoutTimeout: 300",
Environment variable: MM_SERVICESETTINGS_WRITETIMEOUTTIMEOUT

Idle timeout

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/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 stati 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. based on the TLS Certificate File and TLS Key File specified above.

System Config path: Environment > Web Server
config.json setting: ".ServiceSettings.WebserverMode: gzip",
Environment variable: MM_SERVICESETTINGS_WEBSERVERMODE

Enable insecure outgoing connections

Available in legacy Enterprise Edition E10/E20

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

true: Outgoing HTTPS requests 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.
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

Managed resource paths

Available in legacy Enterprise Edition E10/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

Available in legacy Enterprise Edition E10/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

Purge all in-memory caches for sessions, accounts, and channels by pressing Purge All Caches in the System Console. 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

Note: Purging the caches may adversely impact performance. Deployments using High Availability will attempt to purge all the servers in the cluster.