• To create the Docker custom image, go to the project directory “nginx-image” and run the “docker build” command as below. Docker build -t nginx-image. The command will download the base-image Ubuntu 20.04 and create a new custom image with the name “nginx-image.
  • Installing Mattermost on Ubuntu 20.04 LTS¶. Install a production-ready Mattermost system on up to three machines. A complete Mattermost installation consists of three major components: a proxy server, a database server, and the Mattermost server.
  • Sudo docker run -name docker-nginx -p 80:80 -d nginx We added the -d flag to run this container in the background. The output should simply be the new container’s ID.
  • How to Install Docker On Ubuntu 18.04 Bionic Beaver; How to install Matomo Open Source Analytics On Ubuntu 18.04 Bionic Beaver Linux; How to install Varnish cache server with Nginx on Ubuntu 18.04 Bionic Beaver Linux.

Install a production-ready Mattermost system on up to three machines.

Docker is an application that simplifies the process of managing application processes in containers. In this tutorial, you”ll install and use Docker Community Edition (CE) on Ubuntu 18.04.

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.

Install the 64-bit version of Ubuntu Server on each machine that hosts one or more of the components.

To install Ubuntu Server 20.04:

  1. To install Ubuntu Server 20.04, see the Ubuntu Installation Guide.

  2. 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:

Now that the system is up to date, you can start installing the components that make up a Mattermost system.

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

To install MySQL on Ubuntu Server 20.04:

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

  2. Install MySQL.

  1. Run sudomysql_secure_installation and follow the instructions.

  2. Log in to MySQL as root.

sudomysql

  1. Create the Mattermost user mmuser.

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

Note

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

  2. 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";

  1. Create the Mattermost database.

  1. Grant access privileges to the user mmuser.

mysql>grantallprivilegesonmattermost.*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>GRANTALTER,CREATE,DELETE,DROP,INDEX,INSERT,SELECT,UPDATEONmattermost.*TO"mmuser"@"%";

Docker

  1. 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 Ubuntu Server 20.04:

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

sudoaptinstallpostgresqlpostgresql-contrib

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

  1. Log in to the postgres account.

Docker

  1. Start the PostgreSQL interactive terminal.

sudo-upostgrespsql

  1. Create the Mattermost database.

  1. Create the Mattermost user ‘mmuser’.

postgres=#CREATEUSERmmuserWITHPASSWORD"mmuser-password";

Note

Docker Ubuntu 20.04 Nginx

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

  1. Grant the user access to the Mattermost database.

postgres=#GRANTALLPRIVILEGESONDATABASEmattermosttommuser;

  1. Exit the PostgreSQL interactive terminal.

  1. Log out of the postgres account.

exit

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

  1. Find the following line:

  1. Uncomment the line and change localhost to *:

listen_addresses="*"

  1. Restart PostgreSQL for the change to take effect:

  1. 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:

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

  2. Find the following lines:

localallallpeer

hostallall::1/128ident

  1. Change peer and ident to trust:

localallalltrust

hostallall::1/128trust

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

  1. Open /etc/postgresql/10/main/pg_hba.conf in a text editor as root user.

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

  1. Reload PostgreSQL:

sudosystemctlreloadpostgresql

  1. Verify that you can connect with the user mmuser.

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

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

  1. 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.

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 Ubuntu

  1. Log in to the server that will host Mattermost Server and open a terminal window.

  2. Download the latest version of the Mattermost Server. In the following command, replace X.X.X with the version that you want to download:

wgethttps://releases.mattermost.com/X.X.X/mattermost-X.X.X-linux-amd64.tar.gz

  1. Extract the Mattermost Server files.

  1. Move the extracted file to the /opt directory.

sudomvmattermost/opt

  1. Create the storage directory for files.

sudomkdir/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.

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

  1. Create the Mattermost user and group:

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

sudochown-Rmattermost:mattermost/opt/mattermost

  1. Give write permissions to the mattermost group:

  1. 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:

  1. Set "DriverName" to "postgres"

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

"postgres://mmuser:<mmuser-password>@<host-name-or-IP>:5432/mattermost?sslmode=disable&connect_timeout=10".

  • If you are using MySQL:

  1. Set "DriverName" to "mysql"

  2. Set "DataSource" to the following value, replacing <mmuser-password> and <host-name-or-IP> 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&readTimeout=30s&writeTimeout=30s"

  1. Also set "SiteURL" to the full base URL of the site (e.g. "https://mattermost.example.com").

  2. Test the Mattermost server to make sure everything works.

    1. Change to the mattermost directory:

    1. Start the Mattermost server as the user mattermost:

    sudo-umattermost./bin/mattermost

When the server starts, it shows some log information and the text Serverislisteningon:8065. You can stop the server by pressing CTRL+C in the terminal window.

  1. Setup Mattermost to use systemd for starting and stopping.

  1. Create a systemd unit file:

  1. Open the unit file as root in a text editor, and copy the following lines into the file:

Note

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

Ubuntu

Note

If you have installed MySQL or PostgreSQL on a dedicated server, then you need to

  • remove After=postgresql.service and BindsTo=postgresql.service or After=mysql.service and BindsTo=mysql.service lines in the [Unit] section, and

  • replace the WantedBy=postgresql.service or WantedBy=mysql.service line in the [Install] section with WantedBy=multi-user.target

or the Mattermost service will not start.

Note

Setting WantedBy to your local database service ensures that whenever the database service is started, the Mattermost server starts too. This prevents the Mattermost server from stopping to work after an automatic update of the database.

Docker Ubuntu Nginx Php Mysql

  1. Make systemd load the new unit.

  1. Check to make sure that the unit was loaded.

sudosystemctlstatusmattermost.service

You should see an output similar to the following:

  1. Start the service.

sudosystemctlstartmattermost.service

  1. Verify that Mattermost is running.

curlhttp://localhost:8065

You should see the HTML that’s returned by the Mattermost server.

  1. Set Mattermost to start on machine start up.

Now that the Mattermost server is up and running, you can do some initial configuration and setup.

Create the System Admin user and set up Mattermost for general use.

  1. 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.

  2. 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.

  3. To open the System Console, click your username at the top of the navigation panel and select System Console.

  4. 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 are using HTTPS, make sure that you set up TLS, either on Mattermost Server or on a proxy.

  1. 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, [email protected]

    • 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.

  • When the connection is confirmed as working, select Save.

  1. 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. 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.

  1. Select Save to apply the configuration.

  2. Review and configure any other settings that may be applicable.

  3. Restart Mattermost.

You have two options if you want users to connect with HTTPS:

  1. Set up TLS on Mattermost Server.

  2. 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:

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

  1. Change the Listen Address setting to :443.

  2. Change the Connection Security setting to TLS.

  3. Change the Forward port 80 to 443 setting to true.

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

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

  1. 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.

  1. Change the Use Let’s Encrypt setting to true.

  2. 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:

  1. Change the Use Let’s Encrypt setting to false.

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

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

  4. 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:

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 Ubuntu Server:

  1. Log in to the server that will host the proxy and open a terminal window.

  2. Install NGINX.

  1. After the installation is complete, verify that NGINX is running.

curlhttp://localhost

If NGINX is running, you see the following output:

Note

You can stop, start, and restart NGINX with the following commands:

What to do next

  1. Map a fully qualified domain name (FQDN) such as mattermost.example.com to point to the NGINX server.

  2. Configure NGINX to proxy connections from the internet to the 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

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

  2. Create a configuration file for Mattermost.

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

  1. 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 at step 3 here and please see the NGINX HTTP/2 & SSL full configuration guide.

Note

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.

  1. Remove the existing default sites-enabled file.

sudorm/etc/nginx/sites-enabled/default

On RHEL 7 and 8: sudorm/etc/nginx/conf.d/default

  1. Enable the mattermost configuration.

sudoln-s/etc/nginx/sites-available/mattermost/etc/nginx/sites-enabled/mattermost

On RHEL 7 and 8: sudoln-s/etc/nginx/conf.d/mattermost/etc/nginx/conf.d/default.conf

  1. Restart NGINX.

  1. Verify that you can see Mattermost through the proxy.

curlhttps://localhost

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

  1. 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.

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:

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.

For other troubleshooting tips for WebSocket errors, see potential solutions here.

How do I setup an NGINX proxy with the Mattermost Docker installation?

  1. Find the name of the Mattermost network and connect it to the NGINX proxy.

  1. Restart the Mattermost Docker containers.

Tip

You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.

  1. Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.

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.

  1. Log in to your GitLab instance as the admin.

  2. Go to Admin > Applications.

  3. Click Edit on GitLab-Mattermost.

  4. Update the Callback URLs to your new domain/URL.

  5. Save the changes.

  6. Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration 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.

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 NGINX as a proxy with SSL and HTTP/2

If you’re looking for additional Let’s Encrypt/Certbot assistance you can access their documentation here .

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

  2. Open the your Mattermost nginx.conf file as root in a text editor and update the {ip} address in the upstreambackend to point towards Mattermost (ex: 127.0.0.1:8065, and 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 sudotouch/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 sudotouch/etc/nginx/conf.d/mattermost.

  1. Remove the existing default sites-enabled file.

sudorm/etc/nginx/sites-enabled/default

  1. Enable the Mattermost configuration.

sudoln-s/etc/nginx/sites-available/mattermost/etc/nginx/sites-enabled/mattermost

On RHEL 7+: sudoln-s/etc/nginx/conf.d/mattermost/etc/nginx/conf.d/default.conf

  1. Run sudonginx-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.

  2. Restart NGINX.

  1. Verify that you can see Mattermost through the proxy.

curlhttp://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.

  1. Install and update Snap.

  1. Install the Certbot package.

sudosnapinstall--classiccertbot

  1. Add a symbolic link to ensure Certbot can run.

  1. Run the Let’s Encrypt installer dry-run to ensure your DNS is configured properly.

sudocertbotcertbot--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.

  1. Run the Let’s Encrypt installer.

sudocertbot

This will run certbot and will automatically edit your NGINX config file for the site(s) selected.

  1. Ensure your SSL is configured properly by running:

  1. 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:

  1. 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.

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:

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.

For other troubleshooting tips for WebSocket errors, see potential solutions here.

How do I setup an NGINX proxy with the Mattermost Docker installation?

  1. Find the name of the Mattermost network and connect it to the NGINX proxy.

  1. Restart the Mattermost Docker containers.

Tip

You don’t need to run the ‘web’ container, since NGINX proxy accepts incoming requests.

  1. Update your docker-compose.yml file to include a new environment variable VIRTUAL_HOST and an expose directive.

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.

  1. Log in to your GitLab instance as the admin.

  2. Go to Admin > Applications.

  3. Select Edit on GitLab-Mattermost.

  4. Update the callback URLs to your new domain/URL.

  5. Save the changes.

  6. Update the external URL for GitLab and Mattermost in the /etc/gitlab/gitlab.rb configuration file.

Why does Certbot fail the http-01 challenge?

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 forcetraffictohttps.

Certbot rate limiting

If you’re running certbot as stand-alone you’ll see this error:

If you’re running Let’s Encrypt within Mattermost you’ll see this error:

This means that you’ve attempted to generate a cert too many times. You can find more information here.