team/docs/main/deployment-guide/server/preparations.mdx

---
title: "Prepare your Mattermost Server environment"
sidebar_label: "Preparations"
---
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](/deployment-guide/software-hardware-requirements) - Ensure your system meets the minimum requirements for Mattermost deployment.
- [Set up an NGINX proxy](/deployment-guide/server/setup-nginx-proxy) - Configure NGINX as a reverse proxy for enhanced security and performance.
- [Set up TLS](/deployment-guide/server/setup-tls) - Enable secure communication with SSL/TLS encryption.
- [Use an image proxy](/deployment-guide/server/image-proxy) - Configure image proxy for enhanced privacy and security.

## Database preparation

PostgreSQL v14+ is required for Mattermost server installations. [MySQL database support](/deployment-guide/server/prepare-mattermost-mysql-database) is being deprecated starting with Mattermost v11. See the [PostgreSQL migration](/deployment-guide/postgres-migration) documentation for guidance on migrating from MySQL to PostgreSQL.

1.  Create an PostgreSQL server instance. See the [PostgreSQL documentation](https://www.postgresql.org/download/) 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:

        ``` sh
        sudo -u postgres psql
        ```

    2.  Create the database:

        ``` sql
        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:

        ``` sql
        CREATE USER mmuser WITH PASSWORD 'mmuser-password';
        ```

    4.  Grant database access to the user:

        ``` sql
        GRANT ALL PRIVILEGES ON DATABASE mattermost to mmuser;
        ```

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

        ``` text
        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:

<Tabs>
<TabItem value="ubuntu-debian" label="Ubuntu/Debian">

Edit `/etc/postgresql/&#123;version&#125;/main/postgresql.conf`:

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

</TabItem>
<TabItem value="rhel-centos" label="RHEL/CentOS">

Edit `/var/lib/pgsql/&#123;version&#125;/data/postgresql.conf`:

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

</TabItem>
</Tabs>


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

        Add the following line, replacing `&#123;mattermost-server-IP&#125;`:

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

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

<Tabs>
<TabItem value="ubuntu-debian" label="Ubuntu/Debian">

``` sh
sudo systemctl restart postgresql
```

</TabItem>
<TabItem value="rhel-centos" label="RHEL/CentOS">

``` sh
sudo systemctl restart postgresql
```

</TabItem>
</Tabs>


<Important>

If you are upgrading a major version of PostgreSQL, see [Upgrade PostgreSQL](/administration-guide/upgrade/upgrading-postgres) for the full upgrade procedure and post-upgrade steps.

</Important>

Once you've completed the database preparation, return to the [Linux deployment](/deployment-guide/server/deploy-linux) 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:

    ``` sh
    sudo mkdir -p /opt/mattermost/data
    ```

2.  Set appropriate permissions:

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

### (Optional) Use an image proxy

Using an [image proxy](/deployment-guide/server/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:

<table style={{width: '98%'}}>
<colgroup>
<col style={{width: '26%'}} />
<col style={{width: '17%'}} />
<col style={{width: '15%'}} />
<col style={{width: '5%'}} />
<col style={{width: '5%'}} />
<col style={{width: '27%'}} />
</colgroup>
<thead>
<tr>
<th>Service Name</th>
<th>Config Setting</th>
<th>Port (default)</th>
<th>Protocol</th>
<th>Direction</th>
<th>Info</th>
</tr>
</thead>
<tbody>
<tr>
<td>HTTP/Websocket</td>
<td>ServiceSettings.ListenAddress</td>
<td>8065/80/443 (TLS)</td>
<td>TCP</td>
<td>Inbound</td>
<td rowspan="2">External (no proxy) / Internal (with proxy) Usually this requires port 80 and 443 when running HTTPS.</td>
</tr>
<tr>
<td></td>
<td></td>
<td></td>
<td></td>
<td></td>
</tr>
<tr>
<td>Cluster</td>
<td>ClusterSettings.GossipPort</td>
<td>8074</td>
<td>TCP/UDP</td>
<td>Inbound</td>
<td>Internal</td>
</tr>
<tr>
<td>Metrics</td>
<td>MetricsSettings.ListenAddress</td>
<td>8067</td>
<td>TCP</td>
<td>Inbound</td>
<td>External (no proxy) / Internal (with proxy)</td>
</tr>
<tr>
<td>Database</td>
<td>SqlSettings.DataSource</td>
<td>5432 (PostgreSQL) / 3306 (MySQL)</td>
<td>TCP</td>
<td>Outbound</td>
<td>Usually internal (recommended)</td>
</tr>
<tr>
<td>LDAP</td>
<td>LdapSettings.LdapPort</td>
<td>389</td>
<td>TCP/UDP</td>
<td>Outbound</td>
<td></td>
</tr>
<tr>
<td>S3 Storage</td>
<td>FileSettings.AmazonS3Endpoint</td>
<td>443 (TLS)</td>
<td>TCP</td>
<td>Outbound</td>
<td></td>
</tr>
<tr>
<td>SMTP</td>
<td>EmailSettings.SMTPPort</td>
<td>10025</td>
<td>TCP/UDP</td>
<td>Outbound</td>
<td></td>
</tr>
<tr>
<td>Push Notifications</td>
<td>EmailSettings.PushNotificationServer</td>
<td>443 (TLS)</td>
<td>TCP</td>
<td>Outbound</td>
<td></td>
</tr>
</tbody>
</table>

<Note>

- 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

</Note>

### 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:

    ``` text
    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:

    ``` text
    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`)

<Note>

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

Example systemd Service Configuration

``` ini
[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
```

</Note>

## 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](/deployment-guide/software-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](/deployment-guide/server/deploy-kubernetes)
- [Deploy on Linux](/deployment-guide/server/deploy-linux)
- [Deploy with Containers](/deployment-guide/server/deploy-containers)