Prepare your Mattermost Server environment#

This guide outlines the key preparation steps required before installing the Mattermost Server, focusing on setting up the database and file storage systems.

Database preparation#

Mattermost requires a PostgreSQL database (version 13 or higher). While MySQL was previously supported, PostgreSQL is now the recommended and preferred database.

Important

  • PostgreSQL v13+ is required for Mattermost server installations. MySQL database support is being deprecated starting with Mattermost v11. See the PostgreSQL migration documentation for guidance on migrating from MySQL to PostgreSQL.

  • Learn how to use sockets to set up the database.

  1. Create an PostgreSQL server instance:

    sudo apt update
sudo apt install postgresql

    sudo apt update
sudo apt install postgresql

    sudo apt update
sudo apt install postgresql

    sudo dnf install postgresql-server
sudo postgresql-setup --initdb

  2. Create the Mattermost database and user:

    1. Access PostgreSQL by running:

      sudo -u postgres psql

    2. Create the database:

      CREATE DATABASE mattermost WITH ENCODING 'UTF8' LC_COLLATE='en_US.UTF-8' LC_CTYPE='en_US.UTF-8' TEMPLATE=template0;

    3. Create the Mattermost user with a secure password:

      CREATE USER mmuser WITH PASSWORD 'mmuser-password';

    4. Grant database access to the user:

      GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;

    5. If using PostgreSQL v15.x or later, additional grants are required:

      ALTER DATABASE mattermost OWNER TO mmuser;
GRANT USAGE, CREATE ON SCHEMA PUBLIC TO mmuser;

  3. Configure PostgreSQL for remote connections (if database is on a separate server):

    1. Edit postgresql.conf to allow remote connections:

      Edit /etc/postgresql/{version}/main/postgresql.conf:

      listen_addresses = '*'

      Edit /var/lib/pgsql/{version}/data/postgresql.conf:

      listen_addresses = '*'

    2. Configure client authentication by editing pg_hba.conf:

      Add the following line, replacing {mattermost-server-IP}:

      host all all {mattermost-server-IP}/32 md5

Important

If you are upgrading a major version of Postgres, ensure that ANALYZE VERBOSE is run on the database post upgrade. This is required to re-populate the pg_statistics table used to generate optimal query plans. Database performance may suffer if this step is skipped.

File storage preparation#

Mattermost requires a file storage system for storing user files, images, and attachments. You have several options, including:

  • S3-compatibile object storage (recommended)

  • local file storage

Local file storage#

For simple deployments, you can use local file storage. However, we don’t recommend this for production environments or multi-node deployments.

  1. Create a directory for file storage:

    sudo mkdir -p /opt/mattermost/data

  2. Set appropriate permissions:

    sudo chown -R mattermost:mattermost /opt/mattermost/data

Network preparation#

Ensure the following ports are available:

  • Application ports: 80/443 (TCP) for HTTP/HTTPS

  • Database port: 5432 (TCP) for PostgreSQL

  • SMTP port: 10025 (TCP/UDP) for outbound email

System requirements#

Ensure your system meets these minimum requirements:

  • Operating System: 64-bit Linux distribution

  • Hardware: 1 vCPU/core with 2GB RAM (supports up to 1,000 users)

  • Storage: Minimum 10GB available space

  • Database: PostgreSQL v13+

  • Network: Reliable internet connection with sufficient bandwidth

See the software and hardware requirements documentation for additional requirements.

Next steps#

Once you’ve completed these preparation steps, you can proceed with installing the Mattermost server. Choose your preferred installation method: