Prepare your Mattermost Server environment

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

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

Before installing Mattermost Server, review the following preparation requirements:

• Review software and hardware requirements - Ensure your system meets the minimum requirements for Mattermost deployment.
• Set up an NGINX proxy - Configure NGINX as a reverse proxy for enhanced security and performance.
• Set up TLS - Enable secure communication with SSL/TLS encryption.
• Use an image proxy - Configure image proxy for enhanced privacy and security.

Database preparation

PostgreSQL v14+ 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.

1. Create an PostgreSQL server instance. 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.

2. Create the Mattermost database and user:

   1. Access PostgreSQL by running:

      shCopy

      sudo -u postgres psql
      

   2. Create the database:

      sqlCopy

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

   If this steps fails with an error message like invalid LC_COLLATE locale name: "en_US.UTF-8", you need to generate the locale first using locale-gen en_US.UTF-8.

   3. Create the Mattermost user with a secure password:

      sqlCopy

      CREATE USER mmuser WITH PASSWORD 'mmuser-password';
      

   4. Grant database access to the user:

      sqlCopy

      GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
      

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

      textCopy

      ALTER DATABASE mattermost OWNER TO mmuser;
      -- Connect to the mattermost database so the schema grants below apply to the right schema
      \c mattermost
      ALTER SCHEMA public 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:

    ``` text
    listen_addresses = '*'
    ```

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

    ``` text
    listen_addresses = '*'
    ```

2.  Configure client authentication by editing `pg_hba.conf`:

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

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

4. Restart the PostgreSQL service to apply the configuration changes:

sudo systemctl restart postgresql

sudo systemctl restart postgresql

If you are upgrading a major version of PostgreSQL, see Upgrade PostgreSQL for the full upgrade procedure and post-upgrade steps.

Once you've completed the database preparation, return to the Linux deployment documentation to continue with your Mattermost server installation.

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)
• Network file storage
• Local file storage

S3-compatible object storage (Recommended)

For production environments, we recommend using S3-compatible object storage such as:

• Amazon S3
• Digital Ocean Spaces
• Other S3-compatible services

When using S3 storage, you'll need:

1. A bucket created specifically for Mattermost
2. Access credentials (Access Key and Secret Key)
3. Appropriate bucket policies configured
4. The following information for configuration:
   • Bucket name
   • Region (if applicable)
   • Access Key
   • Secret Key
   • Endpoint URL (for non-AWS S3 services)

Network file storage

For production environments that cannot use S3-compatible object storage, we recommend using a Network Addressable Storage (NAS) solution with Network File System (NFS).

You'll need to prepare an NFS server with a dedicated share for Mattermost (e.g. <code>/mnt/mattermost_data</code>) and mount it on all servers that will be running Mattermost.

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:

   shCopy

   sudo mkdir -p /opt/mattermost/data
   

2. Set appropriate permissions:

   shCopy

   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

The following table outlines the network ports and protocols required for Mattermost server:

• All outbound ports may vary based on your specific configuration
• Mattermost can be configured to use an outbound proxy for any HTTP/HTTPS traffic (see below)
• Calls service may require additional ports

Outbound proxy configuration

If your deployment requires using an outbound proxy, you can configure Mattermost using environment variables:

1. Configure the proxy settings in your service configuration:

   textCopy

   Environment=HTTP_PROXY=http://proxy.example.com:3128
   Environment=HTTPS_PROXY=https://proxy.example.com:3128
   Environment=NO_PROXY=localhost,127.0.0.1,.internal.example.com
   

2. For authenticated proxies, include credentials in the URL:

   textCopy

   Environment=HTTP_PROXY=http://username:[email protected]:3128
   Environment=HTTPS_PROXY=https://username:[email protected]:3128
   

3. The NO_PROXY variable can include:

   • IP addresses (e.g., 1.2.3.4)
   • CIDR ranges (e.g., 1.2.3.4/8)
   • Domain names (e.g., example.com)
   • Subdomains (e.g., .example.com)

When using an HTTPS proxy, ensure your Mattermost server has the proxy's root certificate configured to avoid connection issues.

Example systemd Service Configuration

[Unit]
Description=Mattermost
After=network.target
After=postgresql.service
BindsTo=postgresql.service

[Service]
Type=notify
ExecStart=/opt/mattermost/bin/mattermost
TimeoutStartSec=3600
KillMode=mixed
Restart=always
RestartSec=10
WorkingDirectory=/opt/mattermost
User=mattermost
Group=mattermost
LimitNOFILE=49152

# Configure proxy settings if needed
#Environment=HTTP_PROXY=http://proxy.example.com:3128
#Environment=HTTPS_PROXY=https://proxy.example.com:3128
#Environment=NO_PROXY=localhost,127.0.0.1,.internal.example.com

# Recommended security options
ProtectSystem=full
PrivateTmp=true
NoNewPrivileges=true

[Install]
WantedBy=postgresql.service

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 v14+
• 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:

• Deploy with Kubernetes
• Deploy on Linux
• Deploy with Containers