How to Set Up Mattermost on Linux

Introduction: Why Mattermost Belongs on a Linux Server

Mattermost is a self-hosted collaboration platform built for teams that want control over their messaging, workflows, integrations, and data. Think of it as the “we keep the keys” alternative to cloud-only team chat tools. It is popular with engineering teams, DevOps groups, security-conscious organizations, and businesses that prefer their conversations not to live in someone else’s attic.

Setting up Mattermost on Linux is not difficult, but it does require a careful sequence: prepare the server, install PostgreSQL, download Mattermost, configure the database connection, run it as a system service, place NGINX in front of it, secure it with HTTPS, and then tune the application for real users. Skip one step and your browser may reward you with the classic “it almost works” experiencelogin loads, channels appear, and then WebSockets decide to take a coffee break.

This guide focuses on a production-style Linux installation using PostgreSQL, NGINX, and systemd. The examples use Ubuntu-style commands where appropriate, but the same logic applies to Debian, RHEL, AlmaLinux, Rocky Linux, and most 64-bit Linux servers. Replace package commands as needed for your distribution.

Editorial note: Mattermost releases, Linux package names, and database requirements can change over time. Before publishing or using these commands in production, verify the latest Mattermost version and your Linux distribution’s supported packages.

What You Need Before Installing Mattermost

Before you begin, start with a clean Linux server. A small team can run comfortably on a modest virtual machine, but production deployments deserve breathing room. For a lightweight installation, plan for at least one CPU core, 2 GB of RAM, and reliable disk storage. For active teams, file uploads, plugins, search, and integrations will demand more.

Recommended starting checklist

• A 64-bit Linux server
• A non-root user with sudo privileges
• A domain or subdomain, such as chat.example.com
• PostgreSQL 14 or newer
• NGINX for reverse proxying
• TLS certificates for HTTPS
• Basic firewall rules
• SMTP details for email notifications and password resets

You can technically run Mattermost by opening port 8065 and calling it a day. You can also technically eat soup with a fork. For a proper setup, use NGINX on ports 80 and 443, keep Mattermost listening locally, and let systemd supervise the service.

Step 1: Update Linux and Install Dependencies

Start by updating the operating system. On Ubuntu or Debian, run:

On RHEL-based systems, use dnf instead:

If you are using a cloud server, also confirm that your provider’s firewall allows inbound traffic on ports 80 and 443. You may temporarily allow 8065 during testing, but for production it is usually better to keep Mattermost behind NGINX.

Step 2: Install and Prepare PostgreSQL

Mattermost uses PostgreSQL as its database backend. PostgreSQL stores users, teams, channels, messages, permissions, configuration data, and plenty of other things you absolutely do not want to lose. Treat the database like the crown jewels, not like a temporary downloads folder.

Enable and start PostgreSQL:

Now create a database and database user for Mattermost:

Inside the PostgreSQL shell, run:

Use a strong password and store it securely. Do not use password123, unless your security strategy is “hope nobody checks.”

Step 3: Download Mattermost for Linux

Download the latest Mattermost Linux server release from the official Mattermost release channel. The version number changes, so replace VERSION with the current stable release number.

Extract the archive and move it into /opt:

Create a data directory for uploads, images, files, and other local storage:

For larger deployments, consider using dedicated object storage instead of local disk storage. Local storage is simple, but it becomes less convenient when you scale to multiple application servers or need more advanced backup workflows.

Step 4: Create a Dedicated Mattermost User

Mattermost should not run as root. Create a dedicated system user:

This keeps the application isolated and reduces risk if something goes wrong. Running web services as root is like giving a raccoon admin access to your kitchen. It might be fine for a minute, but nobody is sleeping peacefully.

Step 5: Configure Mattermost

The main configuration file lives at:

Open it with your preferred editor:

Find the SQL settings and configure PostgreSQL. The exact formatting may vary by version, but the important values are the driver name and data source:

For a local database on the same server, sslmode=disable is common. If PostgreSQL is on a separate server, use encrypted database connections and restrict access with firewall rules.

Next, set the public site URL. Look for ServiceSettings and configure:

The SiteURL value is important. It affects links, redirects, email notifications, WebSocket behavior, and general happiness. Use the final HTTPS address your users will visit.

Step 6: Test Mattermost Manually

Before creating a service file, run Mattermost manually to catch obvious configuration issues:

If the server starts successfully, you should see log output showing that Mattermost is listening on port 8065. Open another terminal and test locally:

If you get a response, stop the manual process with Ctrl+C. If it fails, check the database password, PostgreSQL service status, file permissions, and the formatting of config.json.

Step 7: Create a systemd Service

Now make Mattermost run as a proper Linux service. Create a systemd unit file:

Add the following:

Reload systemd and start Mattermost:

Check the service:

For logs, use:

This log command will become your best friend during setup. It will tell you whether Mattermost is starting correctly, connecting to PostgreSQL, loading configuration, or dramatically fainting over a typo.

Step 8: Configure NGINX as a Reverse Proxy

NGINX handles public traffic and forwards requests to Mattermost on port 8065. Create an NGINX site file:

Add this basic configuration, replacing chat.example.com with your domain:

Enable the site:

The Upgrade and Connection headers matter because Mattermost uses WebSockets for real-time updates. Without them, messages may appear late, notifications may behave strangely, and your users may start blaming “the server,” which is rude but sometimes accurate.

Step 9: Add HTTPS with Let’s Encrypt

For production, HTTPS is not optional. Install Certbot:

Request and install a certificate:

Certbot can automatically update the NGINX configuration and create a renewal timer. Test renewal with:

After HTTPS is working, confirm that SiteURL in Mattermost uses https://, then restart Mattermost:

Step 10: Configure the Firewall

If you use UFW on Ubuntu, allow web traffic and SSH:

Avoid exposing port 8065 publicly unless you have a specific reason. NGINX should be the public entry point, while Mattermost listens behind it. This keeps your setup cleaner and easier to secure.

Step 11: Complete the First Login and Admin Setup

Visit your Mattermost domain in a browser:

Create the first user. In most Mattermost installations, the first account becomes the system administrator. Once inside, open the System Console and review these settings:

• Site URL: Confirm the HTTPS domain is correct.
• Email: Configure SMTP so users can receive invitations and password resets.
• File storage: Decide between local storage and object storage.
• Authentication: Configure email login, LDAP, SAML, OpenID Connect, or other options as needed.
• Notifications: Review email and push notification behavior.
• Plugins: Enable only what your team actually needs.

Do not ignore email setup. A Mattermost server without working SMTP is like a hotel with rooms but no front desk. People can enter if everything goes perfectly, but the moment someone forgets a password, the lobby gets awkward.

Step 12: Secure Your Mattermost Installation

A working Mattermost installation is good. A secure Mattermost installation is better. Start with the basics:

Use strong administrator accounts

Require strong passwords and limit administrator privileges. Do not give every enthusiastic team lead system admin access. “I like buttons” is not a valid access control policy.

Keep Linux updated

Apply security updates regularly. At minimum, update the operating system, PostgreSQL, NGINX, and Mattermost according to your maintenance schedule.

Back up the database and files

A basic Mattermost backup must include the PostgreSQL database and file storage directory. If you use local storage, back up /opt/mattermost/data. If you use object storage, back up the bucket or ensure retention policies are configured.

Restrict direct database access

PostgreSQL should not be open to the world. If the database is local, keep it bound locally. If it is remote, restrict access by IP address and require secure connections.

Monitor logs

Review Mattermost logs, NGINX logs, PostgreSQL logs, and system logs. A small error today can become tomorrow’s “why is everyone messaging me at breakfast?” incident.

Common Mattermost Installation Problems

Problem: Mattermost will not start

Check the service logs:

Common causes include incorrect PostgreSQL credentials, broken JSON syntax in config.json, missing file permissions, or an unsupported database version.

Problem: The browser loads, but real-time messages fail

This is often a WebSocket proxy issue. Confirm that your NGINX configuration includes:

Problem: File uploads fail

Check permissions on /opt/mattermost/data, NGINX upload limits, and Mattermost file settings. In NGINX, increase client_max_body_size if your team uploads larger files.

Problem: Email invitations do not send

Configure SMTP in the System Console. Verify host, port, username, password, sender address, and TLS settings. Many cloud providers block outbound email ports by default, so check provider rules too.

Problem: Login redirects to the wrong URL

Review SiteURL. It should match the public HTTPS address exactly. A wrong Site URL can cause broken redirects, bad links, and general browser confusion.

How to Update Mattermost on Linux

Updating Mattermost should be planned, not improvised five minutes before lunch. The safe process looks like this:

1. Read the release notes.
2. Back up PostgreSQL.
3. Back up Mattermost files and configuration.
4. Stop Mattermost.
5. Replace the application files with the new release.
6. Preserve the config, data, logs, and plugin-related directories as required.
7. Start Mattermost and watch the logs.
8. Test login, channels, file uploads, notifications, and integrations.

Example backup command for PostgreSQL:

Example service restart:

For production environments, test upgrades on a staging server first. Your future self will appreciate this. Your current self may complain, but that person also thought one server snapshot was “probably enough.”

Production Tips for a Better Mattermost Setup

Use a real domain from the beginning

Changing the domain later is possible, but it can create confusion with links, integrations, mobile apps, and user bookmarks. Start with the final subdomain when you can.

Separate services as you grow

For small teams, one server can run Mattermost, PostgreSQL, and NGINX. As usage grows, consider moving PostgreSQL to a dedicated database server or managed database service. Heavy file usage may also justify object storage.

Configure SMTP early

Email matters for invitations, password resets, notifications, and account recovery. Test it before inviting users.

Document your installation

Keep notes on versions, paths, database credentials storage, firewall rules, NGINX configuration, backup locations, and upgrade steps. Documentation is boring until something breaks. Then it becomes heroic.

Limit plugins

Plugins can be powerful, but each one adds maintenance and security considerations. Install what your team uses, remove what it does not, and keep plugins updated.

Real-World Experience: Lessons from Setting Up Mattermost on Linux

The most important lesson from setting up Mattermost on Linux is that the installation itself is usually not the hard part. The hard part is making smart decisions before users arrive. A clean Mattermost deployment feels simple: people log in, create channels, upload files, search conversations, receive notifications, and forget the server exists. That is the dream. The server should be useful, quiet, and about as dramatic as a toaster.

In practice, most setup headaches come from four areas: DNS, HTTPS, database credentials, and reverse proxy configuration. DNS needs to point to the correct server before Certbot can issue certificates. HTTPS must match the same domain used in SiteURL. PostgreSQL credentials must be entered exactly, including the database name and password. NGINX must pass WebSocket headers properly, or Mattermost may load while real-time communication behaves like it is sending messages by carrier pigeon.

Another useful experience is to avoid testing only from the server itself. A local curl test confirms that Mattermost is listening, but it does not prove that users can reach the site through DNS, HTTPS, and NGINX. Test from your laptop, phone, and a network outside your server environment. If mobile apps matter to your team, test those too. Mobile login issues are often related to incorrect public URLs, certificates, or proxy headers.

Backups deserve special attention. Many administrators back up the Mattermost directory and forget that the real conversation history lives in PostgreSQL. Others back up the database and forget file uploads. A reliable backup plan includes both. A better plan includes restore testing. A backup you have never restored is not a backup; it is a hopeful artifact.

It is also wise to configure monitoring from day one. You do not need a massive observability platform for a small team, but you should at least monitor disk space, memory, CPU load, service status, certificate expiration, and backup success. Disk space is especially important because file uploads and logs can grow quietly. Servers rarely announce, “Excuse me, I am about to fill the disk and ruin everyone’s morning.” They simply do it.

For teams moving from another chat tool, spend time designing channel structure. Create a few obvious channels such as town-square, engineering, support, announcements, and random. Do not create 80 channels on day one. Empty channels make a new workspace feel like an abandoned shopping mall. Let the structure grow with the team.

Finally, keep the setup boring. Use stable releases, standard Linux paths, predictable service names, clear firewall rules, and documented upgrade steps. Creative server administration is fun until someone else has to maintain it. A Mattermost server should be easy to understand six months later, even if you have consumed exactly zero coffee and the production alert arrived during dinner.

Conclusion

Setting up Mattermost on Linux is a practical project for teams that want self-hosted communication, stronger control over data, and flexible integration options. The core path is straightforward: prepare Linux, install PostgreSQL, download Mattermost, configure the database and Site URL, run the server with systemd, secure it behind NGINX, enable HTTPS, and finish the setup in the System Console.

The best Mattermost installations are not just “working.” They are secure, backed up, monitored, documented, and easy to upgrade. Take the extra time to configure SMTP, firewall rules, TLS, file storage, and backup routines properly. Your team may never notice those details, which is exactly the point. Good infrastructure is like good plumbing: nobody applauds it when it works, but everyone becomes a critic when it does not.