About Mattermost
Deploy Mattermost
Get Started
Install Guides
Server Installation
Software and Hardware Requirements
Local Docker Setup
Mattermost Omnibus
Ubuntu 20.04 LTS
Kubernetes
Debian Buster
RHEL 8
CentOS, Oracle Linux, and Scientific Linux
Desktop/Mobile App Installation
Deployment Guide
Upgrade Mattermost
Scale Mattermost
Troubleshooting Guides
Changelogs
Other Resources
Mattermost Administration
Channels
Playbooks
Boards
Mattermost for Developers
Get Help With Mattermost
Community Chat
Docs » Deploy Mattermost » Installing Mattermost on RHEL 8
Search Edit
Installing Mattermost on RHEL 8
You can also use these instructions to install Mattermost on CentOS 8 or Oracle Linux 8. With the exception of the operating system that you install, the process is identical.
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.
Note
If you have any problems installing Mattermost, see the troubleshooting guide, or join the Mattermost user community for troubleshooting help.
For help with inviting users to your system, see inviting team members and other getting started information.
To submit an improvement or correction to this page, click Edit in the top-right corner of the page.
Install and configure the components in the following order. Note that you need only one database, either MySQL or PostgreSQL.
Installing Red Hat Enterprise Linux 8
Installing MySQL Database Server
Installing PostgreSQL Database
Installing Mattermost Server
Configuring Mattermost Server
Configuring TLS on Mattermost Server
Installing NGINX Server
Configuring NGINX as a proxy for Mattermost Server
NGINX Configuration FAQ
Why are Websocket connections returning a 403 error?
How do I setup an NGINX proxy with the Mattermost Docker installation?
Why does NGINX fail when installing GitLab CE with Mattermost on Azure?
Configuring NGINX with SSL and HTTP/2
NGINX Configuration FAQ
Installing Red Hat Enterprise Linux 8
Install the 64-bit version of RHEL 8 on each machine that hosts one or more of the components.
To install RHEL 8 Server:
To install RHEL 8, see the RedHat Installation Instructions.
After the system is installed, make sure that it’s up to date with the most recent security patches. Open a terminal window and issue the following commands:
sudo yum update
sudo yum upgrade
Now that the system is up to date, you can start installing the components that make up a Mattermost system.
Note
Ensure that the mailcap package is installed as it includes the mime.types file which is needed for the Mobile App to work correctly.
Installing MySQL Database Server
Install and set up the database for use by the Mattermost server. You can install either MySQL or PostgreSQL.
To install MySQL on RHEL 8
Log in to the server that will host the database, and open a terminal window.
Install MySQL.
Note
If you have additional questions about the process reference the MySQL docs here that matches your system. If your RHEL is a fresh install, you’ll need to add the MySQL Yum repository. You can also use the MySQL repo - https://repo.mysql.com/.
Once downloaded, install it: sudo yum localinstall platform-and-version-specific-package-name.rpm. This will be the rpm package you installed in step 2. Now run a sudo yum update, this could take some time.
Next disable the system MySQL:
sudo yum module disable mysql
and then install MySQL.
sudo yum install mysql-community-server
Start the MySQL server.
sudo systemctl start mysqld.service
Note
The first time that you start MySQL, the superuser account 'root'@'localhost' is created with a password. Run the command below to get this password. sudo grep 'temporary password' /var/log/mysqld.log. Also the first time that you start MySQL, the validate_password plugin is installed. The plugin forces passwords to contain at least one upper case letter, one lower case letter, one digit, and one special character, and that the total password length is at least 8 characters.
Change the root password. Log in with the the command below. Use the password found in sudo grep 'temporary password' /var/log/mysqld.log.
mysql -u root -p
Change the password. At the prompt, type the following command. Be sure to replace Password42! with the password that you want to use:
mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'Password42!';
Set MySQL to start automatically when the machine starts.
sudo systemctl enable mysqld
Create the Mattermost user mmuser.
mysql> create user 'mmuser'@'%' identified by 'mmuser-password';
Note
Use a password that’s 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> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';
Create the Mattermost database.
mysql> create database mattermost;
Grant access privileges to the user mmuser.
mysql> grant all privileges on mattermost.* to 'mmuser'@'%';
Note
This query grants the MySQL user we just created all privileges on the database for convenience. If you need more security you can use this query to grant the user only the privileges necessary to run Mattermost.
mysql> GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE, REFERENCES ON mattermost.* TO 'mmuser'@'%';
Log out of MySQL.
mysql> exit
With the database installed and the initial setup complete, you can now install the Mattermost server.
Installing PostgreSQL Database
Log in to the server that will host the database, and open a terminal window.
Confirm this version is PostgreSQL version 10 or higher. You can do this by running psql -V. If this isn’t version 10 or higher you can reference the PostgreSQL documentation here to install an updated version of PostgreSQL.
Initialize the database.
sudo postgresql-setup initdb
Set PostgreSQL to start on boot.
sudo systemctl enable postgresql
Start the PostgreSQL server.
sudo systemctl start postgresql
Switch to the postgres Linux user account that was created during the installation.
sudo -iu postgres
Start the PostgreSQL interactive terminal.
psql
Create the Mattermost database.
postgres=# CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0;
Create the Mattermost user mmuser.
postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser-password';
Note
Use a password that is more secure than ‘mmuser-password’.
Grant the user access to the Mattermost database.
postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
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/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.
Open /var/lib/pgsql/data/postgresql.conf as root in a text editor.
Find the following line:
listen_addresses = 'localhost'
Uncomment the line and change localhost to *:
listen_addresses = '*'
Restart PostgreSQL for the change to take effect:
sudo systemctl restart postgresql
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 /var/lib/pgsql/data/pg_hba.conf as root in a text editor.
Find the following lines:
local all all peer
host all all ::1/128 ident
Change peer and ident to trust:
local all all trust
host all all ::1/128 trust
If the Mattermost server and the database are on different machines:
Open /var/lib/pgsql/data/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.
host all all {mattermost-server-IP}/32 md5
Reload PostgreSQL:
sudo systemctl reload postgresql
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:
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.
Set "DataSource" to the following value, replacing and with the appropriate values. Also make sure that the database name is mattermost instead of mattermost_test:
Test the Mattermost server to make sure everything works.
Change to the mattermost directory:
cd /opt/mattermost
Start the Mattermost server as the user mattermost:
sudo -u mattermost ./bin/mattermost
When the server starts, it shows some log information and the text Server is listening on :8065. You can stop the server by pressing CTRL+C in the terminal window.
Set up Mattermost to use the systemd init daemon which handles supervision of the Mattermost process.
Create the Mattermost configuration file:
sudo touch /etc/systemd/system/mattermost.service
Open the configuration file in a text editor, and copy the following lines into the file:
You should see the HTML that’s returned by the Mattermost server.
Now that Mattermost is installed and running, it’s time to create the admin user and configure Mattermost for use.
Configuring Mattermost Server
Create the System Admin user and set up Mattermost for general use.
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.
To open the System Console, select the Product menu in the top-left corner of the navigation panel, then select System Console.
Set the Site URL:
Open System Console > Environment > Web Server.
In the Site URL field, set the URL that users point their browsers at. For example, https://mattermost.example.com. If you’re using HTTPS, make sure that you set up TLS, either on Mattermost server or on a proxy.
Set up email notifications.
In Site Configuration > Notifications 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 System Console > Environment > SMTP 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
Select Save
Select Test Connection.
Open System Console > Environment > File Storage to set up the file and image storage location.
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.
Note
Files and images that users attach to their messages are not stored in the database. Instead, they’re stored in a location that you specify, such as the local file system or in Amazon S3.
Make sure that the location has enough free space. The amount of storage required depends on the number of users and the number and size of files that users attach to messages.
Select Save to apply the configuration.
Review and configure any other settings that may be applicable.
Restart Mattermost.
sudo systemctl restart mattermost
Configuring TLS on Mattermost Server
You have two options if you want users to connect with HTTPS:
Set up TLS on Mattermost Server.
Install a proxy such as NGINX and set up TLS on the proxy.
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.
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 Forward80To443 config.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.
Restart the Mattermost server for these changes to take effect.
Note
Password-protected certificates are not supported.
Using TLS on NGINX (as a proxy)
Note
Do not set up TLS on Mattermost before before doing so for NGINX. It breaks the connection as the TLS prevents it from successfully communicating with the Mattermost server.
NGINX will act as a forward proxy to encrypt the traffic between the client and Mattermost server. After installing the SSL certificate, the incoming traffic will be handled via NGINX on port 443 exposed to the internet, proxy to the Mattermost server running on port 80.
(Optional) Upstream encryption between NGINX to Mattermost server is allowed.
Follow NGINX’s guide on setting up SSL Termination for TCP Upstream Servers.
Other helpful resources:
NGINX’s SSL blog
NGINX’s SSL guide
Installing NGINX Server
In a production setting, use a proxy server for greater security and performance of Mattermost.
The main benefits of using a proxy are as follows:
SSL termination
HTTP to HTTPS redirect
Port mapping :80 to :8065
Standard request logs
To install NGINX on RHEL 7 or 8:
Log in to the server that will host the proxy, and open a terminal window.
Create the file /etc/yum.repos.d/nginx.repo.
sudo touch /etc/yum.repos.d/nginx.repo
If you are on RHEL 8 you can skip to Step 4. Install NGINX.
Open the file as root in a text editor and add the following contents, where {version} is 7 for RHEL 7:
If NGINX is running, you see the following output:
<!DOCTYPE html>
Welcome to nginx!
.
.
.
Thank you for using nginx.
What to do next
Map a fully qualified domain name (FQDN) such as mattermost.example.com to point to the NGINX server.
Configure NGINX to proxy connections from the Internet to the Mattermost Server.
Configuring NGINX as a proxy for Mattermost Server
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.
sudo touch /etc/nginx/sites-available/mattermost
On RHEL 7 and 8: sudo touch /etc/nginx/conf.d/mattermost
Open the file /etc/nginx/sites-available/mattermost as root user 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 and 8, open the file /etc/nginx/conf.d/mattermost.
SSL and HTTP/2 with server push are enabled in the provided configuration example.
Note
If you’re going to use Let’s Encrypt to manage your SSL certificate, stop here at step 3 here and see the NGINX HTTP/2 & SSL product documentation for details.
You’ll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate.
Note that the IP address included in the examples in this documentation may not match your network configuration.
If you’re running NGINX on the same machine as Mattermost, and NGINX resolves localhost to more than one IP address (IPv4 or IPv6), we recommend using 127.0.0.1 instead of localhost.
upstream backend {
server 10.10.10.2:8065;
keepalive 32;
}
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.
NGINX Configuration FAQ
Why are Websocket connections returning a 403 error?
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:
location ~ /api/v[0-9]+/(users/)?websocket$ {
proxy_pass http://backend;
(...)
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
}
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.
"EnableUserAccessTokens": false,
"AllowCorsFrom": "domain.com domain.com:443 im.domain.com",
"SessionLengthWebInDays": 30,
For other troubleshooting tips for WebSocket errors, see potential solutions here.
How do I setup an NGINX proxy with the Mattermost Docker installation?
Find the name of the Mattermost network and connect it to the NGINX proxy.
docker network ls
Grep the name of your Mattermost network like "mymattermost_default".
docker network connect mymattermost_default nginx-proxy
Restart the Mattermost Docker containers.
docker-compose stop app
docker-compose start app
Tip
You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.
Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.
environment:
set same as db credentials and dbname
MM_USERNAME=mmuser
MM_PASSWORD=mmuser-password
MM_DBNAME=mattermost
VIRTUAL_HOST=mymattermost.tld
expose:
"80"
"443"
Why does NGINX fail when installing GitLab CE with Mattermost on Azure?
You may need to update the callback URLs for the Application entry of Mattermost inside your GitLab instance.
Log in to your GitLab instance as the admin.
Go to Admin > Applications.
Select Edit on GitLab-Mattermost.
Update the Callback URLs to your new domain/URL.
Save the changes.
Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration file.
Configuring NGINX with SSL and HTTP/2
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.
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 Forward80To443 config.json setting set to true to complete the Let’s Encrypt certification.
To configure NGINX as a proxy with SSL and HTTP/2
See the Let’s Encrypt/Certbot documentation for additional assistance.
Log in to the server that hosts NGINX and open a terminal window.
Open the your Mattermost nginx.conf file as root in a text editor, then update the {ip} address in the upstream backend to point towards Mattermost (such as 127.0.0.1:8065), and update the server_name to be your domain for Mattermost.
Note
On Ubuntu this file is located at /etc/nginx/sites-available/. If you don’t have this file, run sudo touch /etc/nginx/sites-available/mattermost.
On CentOS/RHEL this file is located at /etc/nginx/conf.d/. If you don’t have this file, run sudo touch /etc/nginx/conf.d/mattermost.
Note that the IP address included in the examples in this documentation may not match your network configuration.
If you’re running NGINX on the same machine as Mattermost, and NGINX resolves localhost to more than one IP address (IPv4 or IPv6), we recommend using 127.0.0.1 instead of localhost.
upstream backend {
server {ip}:8065;
keepalive 32;
}
On RHEL 7+: sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf
Run sudo nginx -t to ensure your configuration is done properly. If you get an error, look into the NGINX config and make the needed changes to the file under /etc/nginx/sites-available/mattermost.
Restart NGINX.
On Ubuntu 18.04+, RHEL 7+:
sudo systemctl start nginx
Verify that you can see Mattermost through the proxy.
If everything is working, you will see the HTML for the Mattermost signup page. You will see invalid certificate when accessing through the IP or localhost. Use the full FQDN domain to verify if the SSL certificate has pinned properly and is valid.
Install and update Snap.
sudo snap install core; sudo snap refresh core
Install the Certbot package.
sudo snap install --classic certbot
Add a symbolic link to ensure Certbot can run.
sudo ln -s /snap/bin/certbot /usr/bin/certbot
Run the Let’s Encrypt installer dry-run to ensure your DNS is configured properly.
sudo certbot certonly --dry-run
This will prompt you to enter your email, accept the TOS, share your email, and select the domain you’re activating certbot for. This will validate that your DNS points to this server properly and you are able to successfully generate a certificate. If this finishes successfully, proceed to step 12.
Run the Let’s Encrypt installer.
sudo certbot
This will run certbot and will automatically edit your NGINX config file for the site(s) selected.
Ensure your SSL is configured properly by running:
Finally, we suggest editing your config file again to increase your SSL security settings above the default Let’s Encrypt. This is the same file from Step 2 above. Edit it to look like the below:
upstream backend {
server {ip}:8065;
keepalive 32;
}
If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included.
NGINX Configuration FAQ
Why are Websocket connections returning a 403 error?
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:
location ~ /api/v[0-9]+/(users/)?websocket$ {
proxy_pass http://backend;
(...)
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
}
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.
"EnableUserAccessTokens": false,
"AllowCorsFrom": "domain.com domain.com:443 im.domain.com",
"SessionLengthWebInDays": 30,
For other troubleshooting tips for WebSocket errors, see potential solutions here.
How do I setup an NGINX proxy with the Mattermost Docker installation?
Find the name of the Mattermost network and connect it to the NGINX proxy.
docker network ls
Grep the name of your Mattermost network like "mymattermost_default".
docker network connect mymattermost_default nginx-proxy
Restart the Mattermost Docker containers.
docker-compose stop app
docker-compose start app
Tip
You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.
Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.
environment:
set same as db credentials and dbname
MM_USERNAME=mmuser
MM_PASSWORD=mmuser-password
MM_DBNAME=mattermost
VIRTUAL_HOST=mymattermost.tld
expose:
"80"
"443"
Why does NGINX fail when installing Gitlab CE with Mattermost on Azure?
You may need to update the Callback URLs for the Application entry of Mattermost inside your GitLab instance.
Log in to your GitLab instance as the admin.
Go to Admin > Applications.
Select Edit on GitLab-Mattermost.
Update the callback URLs to your new domain/URL.
Save the changes.
Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration file.
Why does Certbot fail the http-01 challenge?
Requesting a certificate for yourdomain.com
Performing the following challenges:
http-01 challenge for yourdomain.com
Waiting for verification...
Challenge failed for domain yourdomain.com
http-01 challenge for yourdomain.com
Cleaning up challenges
Some challenges have failed.
If you see the above errors this is typically because certbot was not able to access port 80. This can be due to a firewall or other DNS configuration. Ensure that your A/AAAA records are pointing to this server and your server_name within the NGINX config does not have a redirect.
Note
If you’re using Cloudflare you’ll need to disable force traffic to https.
Certbot rate limiting
If you’re running certbot as stand-alone you’ll see this error:
Error: Could not issue a Let's Encrypt SSL/TLS certificate for example.com.
One of the Let's Encrypt rate limits has been exceeded for example.com.
See the related Knowledge Base article for details.
Details
Invalid response from https://acme-v02.api.letsencrypt.org/acme/new-order.
Details:
Type: urn:ietf:params:acme:error:rateLimited
Status: 429
Detail: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/
If you’re running Let’s Encrypt within Mattermost you’ll see this error:
{"level":"error","ts":1609092001.752515,"caller":"http/server.go:3088","msg":"http: TLS handshake error from ip:port: 429 urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/","source":"httpserver"}
This means that you’ve attempted to generate a cert too many times. You can find more information here.
About Mattermost Deploy Mattermost Get Started Install Guides Server Installation Software and Hardware Requirements Local Docker Setup Mattermost Omnibus Ubuntu 20.04 LTS Kubernetes Debian Buster RHEL 8 CentOS, Oracle Linux, and Scientific Linux Desktop/Mobile App Installation Deployment Guide Upgrade Mattermost Scale Mattermost Troubleshooting Guides Changelogs Other Resources Mattermost Administration Channels Playbooks Boards Mattermost for Developers Get Help With Mattermost Community Chat Docs » Deploy Mattermost » Installing Mattermost on RHEL 8 Search Edit Installing Mattermost on RHEL 8
You can also use these instructions to install Mattermost on CentOS 8 or Oracle Linux 8. With the exception of the operating system that you install, the process is identical.
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.
Note
If you have any problems installing Mattermost, see the troubleshooting guide, or join the Mattermost user community for troubleshooting help.
For help with inviting users to your system, see inviting team members and other getting started information.
To submit an improvement or correction to this page, click Edit in the top-right corner of the page.
Install and configure the components in the following order. Note that you need only one database, either MySQL or PostgreSQL.
Installing Red Hat Enterprise Linux 8
Installing MySQL Database Server
Installing PostgreSQL Database
Installing Mattermost Server
Configuring Mattermost Server
Configuring TLS on Mattermost Server
Installing NGINX Server
Configuring NGINX as a proxy for Mattermost Server
NGINX Configuration FAQ
Why are Websocket connections returning a 403 error?
How do I setup an NGINX proxy with the Mattermost Docker installation?
Why does NGINX fail when installing GitLab CE with Mattermost on Azure?
Configuring NGINX with SSL and HTTP/2
NGINX Configuration FAQ
Installing Red Hat Enterprise Linux 8 Install the 64-bit version of RHEL 8 on each machine that hosts one or more of the components.
To install RHEL 8 Server:
To install RHEL 8, see the RedHat Installation Instructions.
After the system is installed, make sure that it’s up to date with the most recent security patches. Open a terminal window and issue the following commands:
sudo yum update
sudo yum upgrade
Now that the system is up to date, you can start installing the components that make up a Mattermost system.
Note
Ensure that the mailcap package is installed as it includes the mime.types file which is needed for the Mobile App to work correctly.
Installing MySQL Database Server Install and set up the database for use by the Mattermost server. You can install either MySQL or PostgreSQL.
To install MySQL on RHEL 8
Log in to the server that will host the database, and open a terminal window.
Install MySQL.
Note
If you have additional questions about the process reference the MySQL docs here that matches your system. If your RHEL is a fresh install, you’ll need to add the MySQL Yum repository. You can also use the MySQL repo - https://repo.mysql.com/.
Download the latest release package using wget:
wget https://dev.mysql.com/get/mysql80-community-release-el8-1.noarch.rpm
Once downloaded, install it: sudo yum localinstall platform-and-version-specific-package-name.rpm. This will be the rpm package you installed in step 2. Now run a sudo yum update, this could take some time.
Next disable the system MySQL:
sudo yum module disable mysql
and then install MySQL.
sudo yum install mysql-community-server
Start the MySQL server.
sudo systemctl start mysqld.service
Note
The first time that you start MySQL, the superuser account 'root'@'localhost' is created with a password. Run the command below to get this password. sudo grep 'temporary password' /var/log/mysqld.log. Also the first time that you start MySQL, the validate_password plugin is installed. The plugin forces passwords to contain at least one upper case letter, one lower case letter, one digit, and one special character, and that the total password length is at least 8 characters.
Change the root password. Log in with the the command below. Use the password found in sudo grep 'temporary password' /var/log/mysqld.log.
mysql -u root -p
Change the password. At the prompt, type the following command. Be sure to replace Password42! with the password that you want to use:
mysql> ALTER USER 'root'@'localhost' IDENTIFIED BY 'Password42!';
Set MySQL to start automatically when the machine starts.
sudo systemctl enable mysqld
Create the Mattermost user mmuser.
mysql> create user 'mmuser'@'%' identified by 'mmuser-password';
Note
Use a password that’s 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> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';
Create the Mattermost database.
mysql> create database mattermost;
Grant access privileges to the user mmuser.
mysql> grant all privileges on mattermost.* to 'mmuser'@'%';
Note
This query grants the MySQL user we just created all privileges on the database for convenience. If you need more security you can use this query to grant the user only the privileges necessary to run Mattermost.
mysql> GRANT ALTER, CREATE, DELETE, DROP, INDEX, INSERT, SELECT, UPDATE, REFERENCES ON mattermost.* TO 'mmuser'@'%';
Log out of MySQL.
mysql> exit
With the database installed and the initial setup complete, you can now install the Mattermost server.
Installing PostgreSQL Database Log in to the server that will host the database, and open a terminal window.
Install PostgreSQL.
sudo yum install postgresql-server postgresql-contrib
Confirm this version is PostgreSQL version 10 or higher. You can do this by running psql -V. If this isn’t version 10 or higher you can reference the PostgreSQL documentation here to install an updated version of PostgreSQL.
Initialize the database.
sudo postgresql-setup initdb
Set PostgreSQL to start on boot.
sudo systemctl enable postgresql
Start the PostgreSQL server.
sudo systemctl start postgresql
Switch to the postgres Linux user account that was created during the installation.
sudo -iu postgres
Start the PostgreSQL interactive terminal.
psql
Create the Mattermost database.
postgres=# CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0;
Create the Mattermost user mmuser.
postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser-password';
Note
Use a password that is more secure than ‘mmuser-password’.
Grant the user access to the Mattermost database.
postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
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/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.
Open /var/lib/pgsql/data/postgresql.conf as root in a text editor.
Find the following line:
listen_addresses = 'localhost'
Uncomment the line and change localhost to *:
listen_addresses = '*'
Restart PostgreSQL for the change to take effect:
sudo systemctl restart postgresql
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 /var/lib/pgsql/data/pg_hba.conf as root in a text editor.
Find the following lines:
local all all peer
host all all ::1/128 ident
Change peer and ident to trust:
local all all trust
host all all ::1/128 trust
If the Mattermost server and the database are on different machines:
Open /var/lib/pgsql/data/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.
host all all {mattermost-server-IP}/32 md5
Reload PostgreSQL:
sudo systemctl reload postgresql
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:
psql --host={postgres-server-IP} --dbname=mattermost --username=mmuser --password
Note
You might have to install the PostgreSQL client software to use the command.
The PostgreSQL interactive terminal starts. To exit the PostgreSQL interactive terminal, type \q and press Enter.
With the database installed and the initial setup complete, you can now install the Mattermost server.
Installing Mattermost Server Install Mattermost Server on a 64-bit machine.
Assume that the IP address of this server is 10.10.10.2.
To install Mattermost Server on RHEL 8
Log in to the server that will host Mattermost Server and open a terminal window.
Download the latest version of the Mattermost Server. In the following command, replace X.X.X with the version that you want to download:
wget https://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz
Extract the Mattermost Server files.
tar -xvzf *.gz
Move the extracted file to the /opt directory.
sudo mv mattermost /opt
Create the storage directory for files.
sudo mkdir /opt/mattermost/data
Note
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.
sudo useradd --system --user-group mattermost
sudo chown -R mattermost:mattermost /opt/mattermost
sudo chmod -R g+w /opt/mattermost
sudo restorecon -R /opt/mattermost
Set up the database driver in the file /opt/mattermost/config/config.json. Open the file as root 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 and with the appropriate values:
"postgres://mmuser:mmuser-password>@<host-name-or-IP:5432/mattermost?sslmode=disable&connect_timeout=10".
If you are using MySQL:
Set "DriverName" to "mysql"
Set "DataSource" to the following value, replacing and with the appropriate values. Also make sure that the database name is mattermost instead of mattermost_test:
"mmuser:mmuser-password>@tcp(<host-name-or-IP:3306)/mattermost?charset=utf8mb4,utf8&writeTimeout=30s"
Note
For a same-machine installation, replace above with localhost or 127.0.0.1.
Also set "SiteURL" to the full base URL of the site (e.g. "https://mattermost.example.com").
Test the Mattermost server to make sure everything works.
Change to the mattermost directory:
cd /opt/mattermost
Start the Mattermost server as the user mattermost:
sudo -u mattermost ./bin/mattermost
When the server starts, it shows some log information and the text Server is listening on :8065. You can stop the server by pressing CTRL+C in the terminal window.
Set up Mattermost to use the systemd init daemon which handles supervision of the Mattermost process.
Create the Mattermost configuration file:
sudo touch /etc/systemd/system/mattermost.service
Open the configuration file in a text editor, and copy the following lines into the file:
[Unit] Description=Mattermost After=syslog.target network.target postgresql.service
[Service] Type=notify WorkingDirectory=/opt/mattermost User=mattermost ExecStart=/opt/mattermost/bin/mattermost PIDFile=/var/spool/mattermost/pid/master.pid TimeoutStartSec=3600 KillMode=mixed LimitNOFILE=49152
[Install] WantedBy=multi-user.target Note
If you are using MySQL, replace postgresql.service with mysqld.service in the [unit] section.
Set the service file permissions.
sudo chmod 644 /etc/systemd/system/mattermost.service
Reload the systemd services.
sudo systemctl daemon-reload
Set Mattermost to start on boot.
sudo systemctl enable mattermost
Start the Mattermost server.
sudo systemctl start mattermost
Verify that Mattermost is running.
curl http://localhost:8065
You should see the HTML that’s returned by the Mattermost server.
Now that Mattermost is installed and running, it’s time to create the admin user and configure Mattermost for use.
Configuring Mattermost Server Create the System Admin user and set up Mattermost for general use.
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.
To open the System Console, select the Product menu in the top-left corner of the navigation panel, then select System Console.
Set the Site URL:
Open System Console > Environment > Web Server.
In the Site URL field, set the URL that users point their browsers at. For example, https://mattermost.example.com. If you’re using HTTPS, make sure that you set up TLS, either on Mattermost server or on a proxy.
Set up email notifications.
In Site Configuration > Notifications 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 System Console > Environment > SMTP 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
Select Save
Select Test Connection.
Open System Console > Environment > File Storage to set up the file and image storage location.
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.
Note
Files and images that users attach to their messages are not stored in the database. Instead, they’re stored in a location that you specify, such as the local file system or in Amazon S3.
Make sure that the location has enough free space. The amount of storage required depends on the number of users and the number and size of files that users attach to messages.
Select Save to apply the configuration.
Review and configure any other settings that may be applicable.
Restart Mattermost.
sudo systemctl restart mattermost
Configuring TLS on Mattermost Server You have two options if you want users to connect with HTTPS:
Set up TLS on Mattermost Server.
Install a proxy such as NGINX and set up TLS on the proxy.
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.
sudo setcap cap_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 Forward80To443 config.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.
Restart the Mattermost server for these changes to take effect.
Note
Password-protected certificates are not supported.
Using TLS on NGINX (as a proxy)
Note
Do not set up TLS on Mattermost before before doing so for NGINX. It breaks the connection as the TLS prevents it from successfully communicating with the Mattermost server.
NGINX will act as a forward proxy to encrypt the traffic between the client and Mattermost server. After installing the SSL certificate, the incoming traffic will be handled via NGINX on port 443 exposed to the internet, proxy to the Mattermost server running on port 80.
(Optional) Upstream encryption between NGINX to Mattermost server is allowed.
Follow NGINX’s guide on setting up SSL Termination for TCP Upstream Servers.
Other helpful resources:
NGINX’s SSL blog
NGINX’s SSL guide
Installing NGINX Server In a production setting, use a proxy server for greater security and performance of Mattermost.
The main benefits of using a proxy are as follows:
SSL termination
HTTP to HTTPS redirect
Port mapping :80 to :8065
Standard request logs
To install NGINX on RHEL 7 or 8:
Log in to the server that will host the proxy, and open a terminal window.
Create the file /etc/yum.repos.d/nginx.repo.
sudo touch /etc/yum.repos.d/nginx.repo
If you are on RHEL 8 you can skip to Step 4. Install NGINX.
Open the file as root in a text editor and add the following contents, where {version} is 7 for RHEL 7:
[nginx] name=nginx repo baseurl=https://nginx.org/packages/rhel/{version}/$basearch/ gpgcheck=0 enabled=1 Install NGINX.
sudo yum install nginx.x86_64
After the installation is complete, start NGINX. On RHEL 6:
sudo service nginx start
On RHEL 7 and RHEL 8:
sudo systemctl start nginx
Optional Set NGINX to start at system boot.
On RHEL 6:
sudo chkconfig nginx on
On RHEL 7 and RHEL 8:
sudo systemctl enable nginx
Verify that NGINX is running.
curl http://localhost
If NGINX is running, you see the following output:
<!DOCTYPE html>
Thank you for using nginx.
What to do next
Map a fully qualified domain name (FQDN) such as mattermost.example.com to point to the NGINX server.
Configure NGINX to proxy connections from the Internet to the Mattermost Server.
Configuring NGINX as a proxy for Mattermost Server 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.
sudo touch /etc/nginx/sites-available/mattermost
On RHEL 7 and 8: sudo touch /etc/nginx/conf.d/mattermost
Open the file /etc/nginx/sites-available/mattermost as root user 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 and 8, open the file /etc/nginx/conf.d/mattermost.
SSL and HTTP/2 with server push are enabled in the provided configuration example.
Note
If you’re going to use Let’s Encrypt to manage your SSL certificate, stop here at step 3 here and see the NGINX HTTP/2 & SSL product documentation for details.
You’ll need valid SSL certificates in order for NGINX to pin the certificates properly. Additionally, your browser must have permissions to accept the certificate as a valid CA-signed certificate.
Note that the IP address included in the examples in this documentation may not match your network configuration.
If you’re running NGINX on the same machine as Mattermost, and NGINX resolves localhost to more than one IP address (IPv4 or IPv6), we recommend using 127.0.0.1 instead of localhost.
upstream backend { server 10.10.10.2:8065; keepalive 32; }
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
server { listen 80 default_server; server_name mattermost.example.com; return 301 https://$server_name$request_uri; }
server { listen 443 ssl http2; server_name mattermost.example.com;
http2_push_preload on; # Enable HTTP/2 Server Push
ssl on; ssl_certificate /etc/letsencrypt/live/{domain-name}/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/{domain-name}/privkey.pem; ssl_session_timeout 1d;
Enable TLS versions (TLSv1.3 is required upcoming HTTP/3 QUIC).
ssl_protocols TLSv1.2 TLSv1.3;
Enable TLSv1.3's 0-RTT. Use $ssl_early_data when reverse proxying to
prevent replay attacks.
#
@see: https://nginx.org/en/docs/http/ngx_http_ssl_module.html#ssl_early_data
ssl_early_data on;
ssl_ciphers 'ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256'; ssl_prefer_server_ciphers on; ssl_session_cache shared:SSL:50m;
HSTS (ngx_http_headers_module is required) (15768000 seconds = six months)
add_header Strict-Transport-Security max-age=15768000;
OCSP Stapling ---
fetch OCSP records from URL in ssl_certificate and cache them
ssl_stapling on; ssl_stapling_verify on;
add_header X-Early-Data $tls1_3_early_data;
location ~ /api/v[0-9]+/(users/)?websocket$ { proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; client_max_body_size 50M; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; client_body_timeout 60; send_timeout 300; lingering_timeout 5; proxy_connect_timeout 90; proxy_send_timeout 300; proxy_read_timeout 90s; proxy_http_version 1.1; proxy_pass http://backend; }
location / { client_max_body_size 50M; proxy_set_header Connection ""; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Frame-Options SAMEORIGIN; proxy_buffers 256 16k; proxy_buffer_size 16k; proxy_read_timeout 600s; proxy_cache mattermost_cache; proxy_cache_revalidate on; proxy_cache_min_uses 2; proxy_cache_use_stale timeout; proxy_cache_lock on; proxy_http_version 1.1; proxy_pass http://backend; } }
This block is useful for debugging TLS v1.3. Please feel free to remove this
and use the
$ssl_early_datavariable exposed by NGINX directly should youwish to do so.
map $ssl_early_data $tls1_3_early_data { "~." $ssl_early_data; default ""; } Remove the existing default sites-enabled file.
sudo rm /etc/nginx/sites-enabled/default
On RHEL 7 and 8: sudo rm /etc/nginx/conf.d/default
Enable the mattermost configuration.
sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost
On RHEL 7 and 8: sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf
Restart NGINX.
sudo systemctl restart nginx
Verify that you can see Mattermost through the proxy.
curl https://localhost
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.
NGINX Configuration FAQ Why are Websocket connections returning a 403 error? 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:
location ~ /api/v[0-9]+/(users/)?websocket$ { proxy_pass http://backend; (...) proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; } 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.
"EnableUserAccessTokens": false, "AllowCorsFrom": "domain.com domain.com:443 im.domain.com", "SessionLengthWebInDays": 30, For other troubleshooting tips for WebSocket errors, see potential solutions here.
How do I setup an NGINX proxy with the Mattermost Docker installation? Find the name of the Mattermost network and connect it to the NGINX proxy.
docker network ls
Grep the name of your Mattermost network like "mymattermost_default".
docker network connect mymattermost_default nginx-proxy Restart the Mattermost Docker containers.
docker-compose stop app docker-compose start app Tip
You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.
Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.
environment:
set same as db credentials and dbname
Log in to your GitLab instance as the admin.
Go to Admin > Applications.
Select Edit on GitLab-Mattermost.
Update the Callback URLs to your new domain/URL.
Save the changes.
Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration file.
Configuring NGINX with SSL and HTTP/2 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.
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 Forward80To443 config.json setting set to true to complete the Let’s Encrypt certification.
To configure NGINX as a proxy with SSL and HTTP/2
See the Let’s Encrypt/Certbot documentation for additional assistance.
Log in to the server that hosts NGINX and open a terminal window.
Open the your Mattermost nginx.conf file as root in a text editor, then update the {ip} address in the upstream backend to point towards Mattermost (such as 127.0.0.1:8065), and update the server_name to be your domain for Mattermost.
Note
On Ubuntu this file is located at /etc/nginx/sites-available/. If you don’t have this file, run sudo touch /etc/nginx/sites-available/mattermost.
On CentOS/RHEL this file is located at /etc/nginx/conf.d/. If you don’t have this file, run sudo touch /etc/nginx/conf.d/mattermost.
Note that the IP address included in the examples in this documentation may not match your network configuration.
If you’re running NGINX on the same machine as Mattermost, and NGINX resolves localhost to more than one IP address (IPv4 or IPv6), we recommend using 127.0.0.1 instead of localhost.
upstream backend { server {ip}:8065; keepalive 32; }
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
server { listen 80 default_server; server_name mattermost.example.com;
} Remove the existing default sites-enabled file.
sudo rm /etc/nginx/sites-enabled/default
On RHEL 7+: sudo rm /etc/nginx/conf.d/default
Enable the Mattermost configuration.
sudo ln -s /etc/nginx/sites-available/mattermost /etc/nginx/sites-enabled/mattermost
On RHEL 7+: sudo ln -s /etc/nginx/conf.d/mattermost /etc/nginx/conf.d/default.conf
Run sudo nginx -t to ensure your configuration is done properly. If you get an error, look into the NGINX config and make the needed changes to the file under /etc/nginx/sites-available/mattermost.
Restart NGINX.
On Ubuntu 18.04+, RHEL 7+:
sudo systemctl start nginx
Verify that you can see Mattermost through the proxy.
curl http://localhost
If everything is working, you will see the HTML for the Mattermost signup page. You will see invalid certificate when accessing through the IP or localhost. Use the full FQDN domain to verify if the SSL certificate has pinned properly and is valid.
Install and update Snap.
sudo snap install core; sudo snap refresh core
Install the Certbot package.
sudo snap install --classic certbot
Add a symbolic link to ensure Certbot can run.
sudo ln -s /snap/bin/certbot /usr/bin/certbot
Run the Let’s Encrypt installer dry-run to ensure your DNS is configured properly.
sudo certbot certonly --dry-run
This will prompt you to enter your email, accept the TOS, share your email, and select the domain you’re activating certbot for. This will validate that your DNS points to this server properly and you are able to successfully generate a certificate. If this finishes successfully, proceed to step 12.
Run the Let’s Encrypt installer.
sudo certbot
This will run certbot and will automatically edit your NGINX config file for the site(s) selected.
Ensure your SSL is configured properly by running:
curl https://{your domain here}
Finally, we suggest editing your config file again to increase your SSL security settings above the default Let’s Encrypt. This is the same file from Step 2 above. Edit it to look like the below:
upstream backend { server {ip}:8065; keepalive 32; }
proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mattermost_cache:10m max_size=3g inactive=120m use_temp_path=off;
server { server_name mattermost.example.com;
}
server { if ($host = mattermost.example.com) { return 301 https://$host$request_uri; } # managed by Certbot
} Check that your SSL certificate is set up correctly.
Test the SSL certificate by visiting a site such as https://www.ssllabs.com/ssltest/index.html.
If there’s an error about the missing chain or certificate path, there is likely an intermediate certificate missing that needs to be included.
NGINX Configuration FAQ Why are Websocket connections returning a 403 error?
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:
location ~ /api/v[0-9]+/(users/)?websocket$ { proxy_pass http://backend; (...) proxy_set_header Host $host; proxy_set_header X-Forwarded-For $remote_addr; } 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.
"EnableUserAccessTokens": false, "AllowCorsFrom": "domain.com domain.com:443 im.domain.com", "SessionLengthWebInDays": 30, For other troubleshooting tips for WebSocket errors, see potential solutions here.
How do I setup an NGINX proxy with the Mattermost Docker installation?
Find the name of the Mattermost network and connect it to the NGINX proxy.
docker network ls
Grep the name of your Mattermost network like "mymattermost_default".
docker network connect mymattermost_default nginx-proxy Restart the Mattermost Docker containers.
docker-compose stop app docker-compose start app Tip
You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.
Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.
environment:
set same as db credentials and dbname
You may need to update the Callback URLs for the Application entry of Mattermost inside your GitLab instance.
Log in to your GitLab instance as the admin.
Go to Admin > Applications.
Select Edit on GitLab-Mattermost.
Update the callback URLs to your new domain/URL.
Save the changes.
Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration file.
Why does Certbot fail the http-01 challenge?
Requesting a certificate for yourdomain.com Performing the following challenges: http-01 challenge for yourdomain.com Waiting for verification... Challenge failed for domain yourdomain.com http-01 challenge for yourdomain.com Cleaning up challenges Some challenges have failed. If you see the above errors this is typically because certbot was not able to access port 80. This can be due to a firewall or other DNS configuration. Ensure that your A/AAAA records are pointing to this server and your server_name within the NGINX config does not have a redirect.
Note
If you’re using Cloudflare you’ll need to disable force traffic to https.
Certbot rate limiting
If you’re running certbot as stand-alone you’ll see this error:
Error: Could not issue a Let's Encrypt SSL/TLS certificate for example.com. One of the Let's Encrypt rate limits has been exceeded for example.com. See the related Knowledge Base article for details. Details Invalid response from https://acme-v02.api.letsencrypt.org/acme/new-order. Details: Type: urn:ietf:params:acme:error:rateLimited Status: 429 Detail: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/ If you’re running Let’s Encrypt within Mattermost you’ll see this error:
{"level":"error","ts":1609092001.752515,"caller":"http/server.go:3088","msg":"http: TLS handshake error from ip:port: 429 urn:ietf:params:acme:error:rateLimited: Error creating new order :: too many failed authorizations recently: see https://letsencrypt.org/docs/rate-limits/","source":"httpserver"} This means that you’ve attempted to generate a cert too many times. You can find more information here.
Next Previous © Copyright 2015-2021 Mattermost.
Built with Sphinx using a theme provided by Read the Docs. Was this page helpful?
😀 Yes
😐 Somewhat
🙁 No
× We're listening! Share your product documentation feedback with us using the feedback option at the bottom of any page.