A complete Mattermost installation consists of three major components: a proxy server, a database server, and the Mattermost server. You can install all components on one machine, or you can install each component on its own machine. If you have only two machines, then install the proxy and the Mattermost server on one machine, and install the database on the other machine.

For the database, you can install either MySQL or PostgreSQL. The proxy is NGINX.

Install and set up the database for use by the Mattermost server. You can install either MySQL or PostgreSQL.

To install MySQL on Debian Buster:

Log into the server that will host the database, and open a terminal window.

Download the MySQL repository package.

wgethttps://dev.mysql.com/get/mysql-apt-config_0.8.13-1_all.deb

Install the repository

sudodpkg-imysql-apt-config*

Update your local package list.

sudoapt-getupdate

Add the MySQL repo MySQL.

sudoapt-getinstallmysql-server

Note

During the install, you’ll be prompted to create a password for the MySQL root user. Make a note of the password because you’ll need it in the next step.

Log in to MySQL as root.

mysql-uroot-p

When prompted, enter the root password that you created when installing MySQL.

Create the Mattermost user ‘mmuser’.

mysql>createuser'mmuser'@'%'identifiedby'mmuser-password';

Note

Use a password that is more secure than ‘mmuser-password’.

The ‘%’ means that mmuser can connect from any machine on the network. However, it’s more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command:

mysql>createuser'mmuser'@'10.10.10.2'identifiedby'mmuser-password';

Create the Mattermost database.

mysql>createdatabasemattermost;

Grant access privileges to the user ‘mmuser’.

mysql>grantallprivilegesonmattermost.*to'mmuser'@'%';

Log out of MySQL.

mysql>exit

With the database installed and the initial setup complete, you can now install the Mattermost server.

Install and set up the database for use by the Mattermost server. You can install either PostgreSQL or MySQL.

Assume that the IP address of this server is 10.10.10.1

To install PostgreSQL on Debian Buster:

Log in to the server that will host the database and issue the following command:

sudoapt-getinstallpostgresqlpostgresql-contrib

When the installation is complete, the PostgreSQL server is running, and a Linux user account called postgres has been created.

Log in to the postgres account.

sudo--login--userpostgres

Start the PostgreSQL interactive terminal.

psql

Create the Mattermost database.

postgres=#CREATEDATABASEmattermost;

Create the Mattermost user ‘mmuser’.

postgres=#CREATEUSERmmuserWITHPASSWORD'mmuser-password';

Note

Use a password that is more secure than ‘mmuser-password’.

Grant the user access to the Mattermost database.

postgres=#GRANTALLPRIVILEGESONDATABASEmattermosttommuser;

Exit the PostgreSQL interactive terminal.

postgres=#\q

Log out of the postgres account.

exit

(Optional) If you use a different server for your database and the Mattermost app server, you may allow PostgreSQL to listen on all assigned IP Addresses. To do so, open /etc/postgresql/9.4/main/postgresql.conf as root in a text editor. As a best practice, ensure that only the Mattermost server is able to connect to the PostgreSQL port using a firewall.

Find the following line:

#listen_addresses='localhost'

Uncomment the line and change localhost to *:

listen_addresses='*'

Restart PostgreSQL for the change to take effect:

sudosystemctlrestartpostgresql

Modify the file pg_hba.conf to allow the Mattermost server to communicate with the database.

If the Mattermost server and the database are on the same machine:

Open /etc/postgresql/9.4/main/pg_hba.conf as root in a text editor.

Find the following line:

localallallpeer

Change peer to trust:

localallalltrust

If the Mattermost server and the database are on different machines:

Open /etc/postgresql/9.4/main/pg_hba.conf as root in a text editor.

Add the following line to the end of the file, where {mattermost-server-IP} is the IP address of the machine that contains the Mattermost server.

hostallall{mattermost-server-IP}/32md5

Reload PostgreSQL:

sudosystemctlreloadpostgresql

Verify that you can connect with the user mmuser.

If the Mattermost server and the database are on the same machine, use the following command:

psql--dbname=mattermost--username=mmuser--password

If the Mattermost server is on a different machine, log into that machine and use the following command:

The storage directory will contain all the files and images that your users post to Mattermost, so you need to make sure that the drive is large enough to hold the anticipated number of uploaded files and images.

Set up a system user and group called mattermost that will run this service, and set the ownership and permissions.

Create the Mattermost user and group:

sudouseradd--system--user-groupmattermost

Set the user and group mattermost as the owner of the Mattermost files:

sudochown-Rmattermost:mattermost/opt/mattermost

Give write permissions to the mattermost group:

sudochmod-Rg+w/opt/mattermost

Set up the database driver in the file /opt/mattermost/config/config.json. Open the file in a text editor and make the following changes:

If you are using PostgreSQL:

Set "DriverName" to "postgres"

Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> with the appropriate values:

If you are using MySQL, replace postgresql.service with mysql.service in 2 places in the [Unit] section.

Note

If you have installed MySQL or PostgreSQL on a dedicated server then you need to remove the After=postgresql.service and Requires=postgresql.service or After=mysql.service and Requires=mysql.service lines in the [Unit] section or the Mattermost service will not start.

Open a browser and navigate to your Mattermost instance. For example, if the IP address of the Mattermost server is 10.10.10.2 then go to http://10.10.10.2:8065.

Create the first team and user. The first user in the system has the system_admin role, which gives you access to the System Console.

Open the System Console. To open the System Console, click your username at the top of the navigation panel, and in the menu that opens, click System Console.

Set the Site URL:

In the GENERAL section of the System Console, click Configuration in prior versions or System Console > Environment > Web Server in versions after 5.12.

In the Site URL field, set the URL that users point their browsers at. For example, https://mattermost.example.com. If you are using HTTPS, make sure that you set up TLS, either on Mattermost Server or on a proxy.

Set up email notifications.

In the NOTIFICATIONS section of the System Console, make the following changes:

Set Enable Email Notifications to true

Set Notification Display Name to No-Reply

Set Notification From Address to {your-domain-name} For example, example.com

In the NOTIFICATIONS section of the System Console in prior versions or System Console > Environment > SMTP in versions after 5.12, also make the following changes:

Set SMTP Server Username to {SMTP-username} For example, admin@example.com

Set SMTP Server Password to {SMTP-password}

Set SMTP Server to {SMTP-server} For example, mail.example.com

Set SMTP Server Port to 465

Set Connection Security to TLS or STARTTLS, depending on what the SMTP server accepts.

Click Test Connection.

After your connection is working, click Save.

Set up the file and image storage location.

Note

Files and images that users attach to their messages are not stored in the database. Instead, they are stored in a location that you specify. You can store the files on the local file system or in Amazon S3.

Make sure that the location has enough free space. The amount of storage that’s required depends on the number of users and on the number and size of files that users attach to messages.

In the FILES section of the System Console, click Storage in prior versions or System Console > Environment > File Storage in versions after 5.12.

If you store the files locally, set File Storage System to Local File System, and then either accept the default for the Local Storage Directory or enter a location. The location must be a directory that exists and has write permissions for the Mattermost server. It can be an absolute path or a relative path. Relative paths are relative to the mattermost directory.

If you store the files on Amazon S3, set File Storage System to Amazon S3 and enter the appropriate values for your Amazon account.

Click Save.

Review the other settings in the System Console to make sure everything is as you want it.

The easiest option is to set up TLS on the Mattermost Server, but if you expect to have more than 200 users, use a proxy for better performance. A proxy server also provides standard HTTP request logs.

Note

Your Mattermost server must be accessible from the Let’s Encrypt CA in order to verify your domain name and issue the certificate. Be sure to open your firewall and configure any reverse proxies to forward traffic to ports 80 and 443. More information can be found at Let’s Encrypt.

Configure TLS on the Mattermost Server:

In System Console > Environment > Web Server (or System Console > General > Configuration in versions prior to 5.12).

Change the Listen Address setting to :443.

Change the Connection Security setting to TLS.

Change the Forward port 80 to 443 setting to true.

Activate the CAP_NET_BIND_SERVICE capability to allow Mattermost to bind to low ports.

sudosetcapcap_net_bind_service=+ep/opt/mattermost/bin/mattermost

Install the security certificate. You can use Let’s Encrypt to automatically install and setup the certificate, or you can specify your own certificate.

To use a Let’s Encrypt certificate:

The certificate is retrieved the first time that a client tries to connect to the Mattermost server. Certificates are retrieved for any hostname a client tries to reach the server at.

Change the Use Let’s Encrypt setting to true.

Restart the Mattermost server for these changes to take effect.

Note

If Let’s Encrypt is enabled, forward port 80 through a firewall, with Forward80To443config.json setting set to true to complete the Let’s Encrypt certification.

To use your own certificate:

Change the Use Let’s Encrypt setting to false.

Change the TLS Certificate File setting to the location of the certificate file.

Change the TLS Key File setting to the location of the private key file.

NGINX is configured using a file in the /etc/nginx/sites-available directory. You need to create the file and then enable it. When creating the file, you need the IP address of your Mattermost server and the fully qualified domain name (FQDN) of your Mattermost website.

To configure NGINX as a proxy

Log in to the server that hosts NGINX and open a terminal window.

Create a configuration file for Mattermost.

sudotouch/etc/nginx/sites-available/mattermost

On RHEL 7: sudotouch/etc/nginx/conf.d/mattermost

3. Open the file /etc/nginx/sites-available/mattermost as root in a text editor and replace its contents, if any, with the following lines. Make sure that you use your own values for the Mattermost server IP address and FQDN for server_name.
On RHEL 7, open the file /etc/nginx/conf.d/mattermost.

If everything is working, you will see the HTML for the Mattermost signup page.

Restrict access to port 8065.

By default, the Mattermost server accepts connections on port 8065 from every machine on the network. Use your firewall to deny connections on port 8065 to all machines except the machine that hosts NGINX and the machine that you use to administer Mattermost server. If you’re installing on Amazon Web Services, you can use security groups to restrict access.

Now that NGINX is installed and running, you can configure it to use SSL, which allows you to use HTTPS connections and the HTTP/2 protocol.

This is likely due to a failing cross-origin check. A check is applied for WebSocket code to see if the Origin header is the same as the host header. If it’s not, a 403 error is returned. Open the file /etc/nginx/sites-available/mattermost
as root in a text editor and make sure that the host header being set in the proxy is dynamic:

Then in config.json set the AllowCorsFrom setting to match the domain being used by clients. You may need to add variations of the host name that clients may send. Your NGINX log will be helpful in diagnosing the problem.

Using SSL gives greater security by ensuring that communications between Mattermost clients and the Mattermost server are encrypted. It also allows you to configure NGINX to use the HTTP/2 protocol.

Although you can configure HTTP/2 without SSL, both Firefox and Chrome browsers support HTTP/2 on secure connections only.

You can use any certificate that you want, but these instructions show you how to download and install certificates from Let’s Encrypt, a free certificate authority.

Note

If Let’s Encrypt is enabled, forward port 80 through a firewall, with Forward80To443config.json setting set to true to complete the Let’s Encrypt certification.

To configure SSL and HTTP/2:

Log in to the server that hosts NGINX and open a terminal window.

Install git.

If you are using Ubuntu or Debian:

sudoapt-getinstallgit

If you are using RHEL:

sudoyuminstallgit

Clone the Let’s Encrypt repository on GitHub.

gitclonehttps://github.com/letsencrypt/letsencrypt

Change to the letsencrypt directory.

cdletsencrypt

Stop NGINX.

On Ubuntu 14.04 and RHEL 6:

sudoservicenginxstop

On Ubuntu 16.04, Ubuntu 18.04 and RHEL 7:

sudosystemctlstopnginx

Run netstat to make sure that nothing is listening on port 80.

netstat-na|grep':80.*LISTEN'

Run the Let’s Encrypt installer.

./letsencrypt-autocertonly--standalone

When prompted, enter your domain name. After the installation is complete, you can find the certificate in the /etc/letsencrypt/live directory.

Open the file /etc/nginx/sites-available/mattermost as root in a text editor and update the server section to incorporate the highlighted lines in the following sample. Make sure to replace {domain-name} with your own domain name, in 3 places.