Self-Hosted Team Collaboration App, A replacement for Slack

Requirements

Software

Client Software

Desktop Apps

• Windows: Windows 7, 8.1, and 10
• Mac: MacOS 10.12+
• Linux: Ubuntu LTS releases 18.04 or later

Though not officially supported, the Linux desktop app also runs on RHEL/CentOS 7+.

PC Web

• Chrome: v77+
• Firefox: v68+
• Safari: v12+
• Edge: v44+

Mobile Apps

• iOS: iPhone 5s devices and later with iOS 11+
• Android: Android devices with Android 7+

Mobile Web

• iOS: iOS 11+ with Safari 12+ or Chrome 77+
• Android: Android 7+ with Chrome 77+

Email Client

• Desktop clients: Outlook 2010+, Apple Mail version 7+, Thunderbird 38.2+
• Web based clients: Office 365, Outlook, Gmail, Yahoo, AOL
• Mobile clients: iOS Mail App (iOS 7+), Gmail Mobile App (Android, iOS)

Server Software

Mattermost Server Operating System

• Ubuntu 18.04, Debian Buster, CentOS 6+, CentOS 7+, RedHat Enterprise Linux 7+, Oracle Linux 6+, Oracle Linux 7+.
• Using the Mattermost Docker image on a Docker-compatible operating system (Linux-based OS) is still recommended.

While community support exists for Fedora, FreeBSD, and Arch Linux, Mattermost does not currently include production support for these platforms.

Database Software

• MySQL 5.6, 5.7, 8 (see note below on MySQL 8 support)
• PostgreSQL 9.4+
• Amazon Aurora MySQL 5.6+

Deployments requiring searching in Chinese, Japanese, and Korean languages require MySQL 5.7.6+ and the configuration of ngram Full-Text parser. For searching two characters, you will also need to set ft_min_word_len and innodb_ft_min_token_size to 2 and restart MySQL. See CJK discussion for details.

Search limitations on PostgreSQL:

• Email addresses do not return results.
• Hashtags or recent mentions of usernames containing a dash do not return search results.
• Terms containing a dash return incorrect results as dashes are ignored in the search query.
• If any of the above is an issue, you can either enable the Elasticsearch (E20) feature or install MySQL instead.

Search limitations on MySQL:

• Hashtags or recent mentions of usernames containing a dot do not return search results.

MySQL 8 Support:

In MySQL 8.0.4, the default authentication plugin was changed from mysql_native_password to caching_sha2_password (https://mysqlserverteam.com/mysql-8-0-4-new-default-authentication-plugin-caching_sha2_password/). If you are using MySQL 8.0.4+, you will need to enable mysql_native_password by adding the following entry in your MySQL configuration file:``

[mysqld]
default-authentication-plugin=mysql_native_password

Hardware

Usage of CPU, RAM, and storage space can vary significantly based on user behavior. These hardware recommendations are based on traditional deployments and may grow or shrink depending on how active your users are.

Moreover, memory requirements can be driven by peak file sharing activity. Recommendation is based on default 50 MB maximum file size, which can be adjusted from the System Console. Changing this number may change memory requirements.

For deployments larger than 2,000 users, it is recommended to use the Mattermost open source load testing framework to simulate usage of your system at full scale: https://github.com/mattermost/mattermost-load-test.

Hardware Requirements for Team Deployments

Most small to medium Mattermost team deployments can be supported on a single server with the following specifications based on registered users:

• 1 - 1,000 users - 1 vCPU/cores, 2 GB RAM
• 1,000 - 2,000 users - 2 vCPUs/cores, 4 GB RAM

Hardware Requirements for Enterprise Deployments (Multi-Server)

Scale Requirements

For Enterprise Edition deployments with a multi-server setup, see our scaling guide.

It is highly recommended that pilots are run before enterprise-wide deployments in order to estimate full scale usage based on your specific organizational needs. You can use the Mattermost open source load testing framework to simulate usage of your system: https://github.com/mattermost/mattermost-load-test.

Mattermost’s performance monitoring tools can be used for detailed performance measurements and to inspect the running system to ensure sizing and installation is correct.

System Requirements

For Enterprise Edition deployments with a multi-server setup, we highly recommend the following systems to support your Mattermost deployment:

• Prometheus to track system health of your Mattermost deployment, through performance monitoring feature available in Enterprise Edition E20.
• Grafana to visualize the system health metrics collected by Prometheus with the performance monitoring feature. Grafana 5.0.0 and later is recommended.
• Elasticsearch to support highly efficient database searches in a cluster environment. Elasticsearch 5.0 and later is supported. Learn more here.
• MinIO or AWS S3. Mattermost is compatible with object storage systems which implement the S3 API. Other S3-compatible systems may work, but are not officially supported. Learn more about file storage configuration options in our documentation.

Alternate Storage Calculations

As an alternative to recommended storage sizing above, you can forecast your own storage usage. Begin with a Mattermost server approximately 600 MB to 800 MB in size including operating system and database, then add the multiplied product of:

• Estimated storage per user per month (see below), multipled by 12 months in a year
• Estimated mean average number of users in a year
• A 1-2x safety factor

Estimated storage per user per month

File usage per user varies significantly across industries. The below benchmarks are recommended:

• Low usage teams (1-5 MB/user/month)
  • Primarily use text messages and links to communicate. Examples would include software development teams that heavily use web-based document creation and management tools, and therefore rarely upload files to the server.
• Medium usage teams (5-25 MB/user/month)
  • Use a mix of text messages as well as shared documents and images to communicate. Examples might include business teams that may commonly drag and drop screenshots, PDFs and Microsoft Office documents into Mattermost for sharing and review.
• High usage teams (25-100 MB/user/month)
  • Heaviest utlization comes from teams uploading a high number of large files into Mattermost on a regular basis. Examples include creative teams who share and store artwork and media with tags and commentary in a pipeline production process.

Example: A 30-person team with medium usage (5-25 MB/user/month) with a safety factor of 2x would require between 3.5 GB (30 users * 5 MB * 12 months * 2x safety factor) and 17.6 GB (30 users * 25 MB * 12 months * 2x safety factor) of free space in the next year.

Features

Following are the key features of Mattermost

• Communicate seamlessly
  • Organized conversations in teams and channels
  • Fully searchable message history
  • 1-on-1 and group messaging
  • Voice, video, and screen sharing
  • File, image, and link sharing
  • Emoji and rich Markdown formatting
  • Multi-language support
• Focus on what’s most important
  • Custom desktop, email, and mobile notifications
  • Do not disturb mode
  • Favorite channels
  • Keyword mention alerts
• Accelerate workflows with integrated tools
  • DevOps integration set
  • Incoming and outgoing webhooks
  • Custom slash commands
  • Plugins and extensions
  • Bots and developer toolkit
  • Robust API library
  • OAuth 2.0 applications
• Administer with full control over your data
  • eDiscovery and compliance reporting
  • Data retention policies
  • Custom terms of service
  • AD/LDAP authentication and group sync
  • Enforced multi-factor authentication
  • SAML 2.0 single sign-on
  • Command line and database management tools
  • Performance and system monitoring

Installation Instructions

Ubuntu Installation

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

• 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 mattermost*.gz

• Move the extracted file to the /opt directory.

sudo mv mattermost /opt

• Create the storage directory for files.

sudo mkdir /opt/mattermost/data

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

  sudo useradd --system --user-group mattermost
 

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

  sudo chown -R mattermost:mattermost /opt/mattermost
 

• Give write permissions to the mattermost group:

  sudo chmod -R g+w /opt/mattermost
 

• Set up the database driver in the file /opt/mattermost/config/config.json
• 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.
• Setup Mattermost to use systemd for starting and stopping.
  • Create a systemd unit file:

  sudo touch /lib/systemd/system/mattermost.service
 

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

  [Unit]
  Description=Mattermost
  After=network.target
  After=postgresql.service
  BindsTo=postgresql.service
  
  [Service]
  Type=notify
  ExecStart=/opt/mattermost/bin/mattermost
  TimeoutStartSec=3600
  Restart=always
  RestartSec=10
  WorkingDirectory=/opt/mattermost
  User=mattermost
  Group=mattermost
  LimitNOFILE=49152
  
  [Install]
  WantedBy=postgresql.service
 

• Make systemd load the new unit.

  sudo systemctl daemon-reload
 

• Check to make sure that the unit was loaded.

  sudo systemctl status mattermost.service
 

• Start the service.

  sudo systemctl start mattermost.service
 

• Verify that Mattermost is running.

  curl http://localhost:806
 

• Set Mattermost to start on machine start up.

  sudo systemctl enable mattermost.service
 

Docker Installation

Deploy Mattermost using a multi-node configuration with Docker Compose. Experience with Docker Compose is recommended.

For a single-node preview of Mattermost (without email) see Local Machine Setup using Docker.

If you have any problems installing, see the troubleshooting guide. To submit an improvement or correction, click Edit at the top of this page.

Install Docker Compose using the online guide. You have to download the latest release from the Docker Compose Github page and put the binary on your /usr/local/bin folder. Usually, you can use the following command, replacing $dockerComposeVersion with the Docker Compose version to install:

sudo curl -L "https://github.com/docker/compose/releases/download/$dockerComposeVersion/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

Deploy the Mattermost Docker setup by running:

sudo apt-get install git
git clone https://github.com/mattermost/mattermost-docker.git
cd mattermost-docker
docker-compose build
mkdir -pv ./volumes/app/mattermost/{data,logs,config,plugins,client-plugins}
sudo chown -R 2000:2000 ./volumes/app/mattermost/
docker-compose up -d

The docker-compose network that is created defaults to 172.18.0.0/16. If you need to change the default network this link provides guidelines on how to do that. If the network is already set up with the default, you need to run the following command to remove it. Then, run the command again to regenerate the default network to include the new network setting.

docker network rm mattermost-server_mm-test

To verify the current Docker network use the following command to list it

docker network ls [OPTIONS]