Install a database

To run a Mattermost server, you need a database: either MySQL or PostgreSQL. See the database software requirements documentation for details on version support.

Tip

You can use sockets for setting up the database. See the using sockets for database documentation for details.

Install and set up a MySQL database for use by the Mattermost server.

Log into the server that will host the database, and open a terminal window.
Install MySQL.
Run sudo mysql_secure_installation and follow the instructions.
Log in to MySQL as root by running sudo mysql.
Create the Mattermost user mmuser by running mysql> create user 'mmuser'@'%' identified by 'mmuser-password';.

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

The % means that mmuser can connect from any machine on the network. However, it’s more secure to use the IP address of the machine that hosts Mattermost. For example, if you install Mattermost on the machine with IP address 10.10.10.2, then use the following command: mysql> create user 'mmuser'@'10.10.10.2' identified by 'mmuser-password';

Create the Mattermost database by running mysql> create database mattermost;.
Grant access privileges to the user mmuser by running 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, use the following 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 by running mysql> exit. Once the database is installed and the initial setup is complete, you can install the Mattermost server.

Install and set up a PostgreSQL database for use by the Mattermost server. These instructions assume that the IP address of this server is 10.10.10.1.

Log in to the server that will host the database, and install PostgreSQL. See the PostgreSQL documentation for details. When the installation is complete, the PostgreSQL server is running, and a Linux user account called postgres has been created.
Access PostgreSQL with one of the following options:

sudo --login --user postgres then psql OR

sudo -u postgres psql

Create the Mattermost database by running postgres=# CREATE DATABASE mattermost;.
Create the Mattermost user mmuser by running postgres=# CREATE USER mmuser WITH PASSWORD 'mmuser-password';.

Use a password that’s more secure than mmuser-password.

Grant the user access to the Mattermost database by running postgres=# GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;.
Exit the PostgreSQL interactive terminal by running postgres=# \q.
Log out of the postgres account by running exit.
(Optional) If you use separate servers for your database and the Mattermost server, you may allow PostgreSQL to listen on all assigned IP addresses by opening /etc/postgresql/{version}/main/postgresql.conf as root in a text editor, and replacing {version} with the version of PostgreSQL that’s currently running. As a best practice, ensure that only the Mattermost server is able to connect to the PostgreSQL port using a firewall.

Find the following line: #listen_addresses = 'localhost'

Uncomment the line and change localhost to *: listen_addresses = '*'

Restart PostgreSQL for the change to take effect by running 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:
1. Open /etc/postgresql/{version}/main/pg_hba.conf as root in a text editor.
2. Find the following lines:
local all all peer

host all all ::1/128 ident
1. 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:
1. Open /etc/postgresql/{version}/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: host all all {mattermost-server-IP}/32 md5.
Reload PostgreSQL by running 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 on Windows or Linux, or ↵ on Mac.

When the PostgreSQL database is installed, and the initial setup complete, you can install the Mattermost server.

Encountering issues with your MySQL database installation? See the MySQL installation troubleshooting documentation for details.