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

  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

(Optional) Use an image proxy#

Using an image proxy means that all requests for images made by Mattermost clients will go through the proxy instead of contacting third-party servers directly. This helps protect user privacy by preventing third-party servers from tracking who views an image. This also prevents the use of tracking pixels (invisible images that do the same thing without the user even seeing an image).

Certain proxy servers also provide a layer of caching which can make loading images faster and more reliable. This caching also helps preserve posts by protecting them from dead images.

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: