How to Use Mattermost: The Beginner's Guide to Self-Hosted Team Chat

What Is Mattermost, Exactly?

Mattermost is an open-source team chat server that runs on your own machine: channels, threads, direct messages, file sharing, and project boards, all behind your own login on your own domain, with every message stored in your own database. Learning how to use Mattermost is mostly learning where your chat lives — nothing you type passes through a vendor's cloud, and that is the entire point. Your team's day-to-day chatting changes almost not at all; where the data sleeps changes completely.

Say the mental model once and the rest of this guide follows: Mattermost is your own Slack — teams hold channels, channels hold conversations, replies fold into threads — except every message lives on YOUR server instead of a vendor's cloud. This Mattermost tutorial takes you from an empty server to a working team chat on the current v12 line (v12.0.1, verified this week): install, first login, your first team, Town Square, channels and threads, Boards, invites, and the mobile apps. The install below uses Docker Compose, so if containers are new to you, start with our Docker beginner guide and come back — this guide assumes you know what a compose file does.

Who is it for? Small teams that want Slack-style chat without the per-seat bill or the data-residency worry: startups, open-source projects, homelabbers, and privacy-minded organizations. You need a Linux server with 1 vCPU and 2 GB of RAM — the official requirements put the 1-to-1,000-user single-server bracket at exactly that — and about an hour of your evening.

What Do You Need Before You Start?

A 64-bit Linux VPS with 1 vCPU and 2 GB of RAM, Docker installed, and optionally a domain name — that is the whole shopping list for a small-team server. The official hardware guide puts the 1-to-1,000-user bracket on one box at 1 vCPU and 2 GB RAM, and recommends splitting the app and the database onto separate hosts only when you grow past that.

If you have never rented a server, read our VPS hosting guide first — Mattermost runs on any standard Linux VPS. Port 8065 is the chat's default port; open 80 and 443 too if you want HTTPS from day one, which you should, and which gets its own section below.

How Do You Install Mattermost With Docker?

The official mattermost/docker repo is the fastest way to a running server: clone it, set your domain in the env file, and bring it up — the compose stack includes PostgreSQL, so there is no database to configure. This is the mattermost self hosted experience at its simplest: one VPS, one compose file, your own chat server. MySQL is not an option at all, and this is worth saying once: MySQL support was removed completely in v11, and the product throws a configuration error if you point it at MySQL — PostgreSQL 15 or newer is the only supported database.

git clone https://github.com/mattermost/docker && cd docker
cp env.example .env
# set DOMAIN in .env to your hostname, then:
docker compose -f docker-compose.yml -f docker-compose.nginx.yml up -d

That gives you HTTPS on your domain with an NGINX front end. Without a domain or reverse proxy, use docker compose -f docker-compose.yml -f docker-compose.without-nginx.yml up -d and open http://your-server:8065/ — port 8065 is where the app listens either way. Two containers come up from the mattermost docker compose stack (app plus PostgreSQL), with NGINX as an optional third.

Just want to try it on your laptop first? The preview image is one command and nothing to clean up afterward:

docker run --name mattermost-preview -d --publish 8065:8065 --publish 8443:8443 mattermost/mattermost-preview

Then open http://localhost:8065/ — same interface, throwaway data, gone when you stop the container.

One honest note, said once: the docs position the Docker deployment for exploring, testing, and development — it has no clustering or high-availability story. For a production rollout, the documented path is the Linux tarball with systemd, plus Nginx and PostgreSQL — and that is also the answer to "mattermost install ubuntu": the Docker commands above run on any 64-bit Ubuntu, and the tarball path is the production upgrade from them. The project itself is healthy open source — roughly 39,000 stars on mattermost/mattermost as of October 2026 — and this Docker repo is the project's own quick path, not a community hack.

How Does the First Login Work?

There are no default credentials — do not spend an hour Googling for a starter password. Open your server URL in a browser and the setup wizard asks you to create the first account; that very first account automatically becomes the System Administrator. (The old sysadmin sample credentials you will see in ancient tutorials are dev-preview-only and do not apply to a real install.)

Write the admin email and a long password down before you click through — recovering from a lost admin login is an SSH trip into the database that nobody enjoys.

What Are Teams, and How Do You Create Your First One?

Mattermost teams are collections of channels — think one company, or one community — and the official guidance is to start with fewer teams rather than one per project. Create yours from the team menu (the plus next to your team list): give it a name, pick a URL-friendly short name, and you are in.

Draw the lane line once and be done with it: Slack and Microsoft Teams are cloud services — their servers live in someone else's data center and you rent seats. Mattermost is the self-hosted lane: the same channel-style chat, but the database sits on your VPS and there are no seats to rent. Different category, not a rival; pick the lane that matches who should hold your data.

Most small organizations need exactly one team. Channels do the organizing work, and that is what the next two sections cover.

What Is Town Square, and Why Is Everyone In It?

Every new team is born with a Town Square channel, and every member is automatically added to Town Square and Off-Topic — the two channels that exist before you create anything. Say the Town Square lesson once: it is the all-hands default. Announcements, introductions, the "everyone reads this" channel. Off-Topic is the water cooler by design.

Both defaults are public and cannot be converted to private — that is deliberate, so there is always one channel every member can see. Leave Town Square as the all-hands default and do your real organizing in channels you create yourself.

How Do Channels, Threads, and Direct Messages Work?

Mattermost channels come in four types, and the whole product is just these four recombined:

Create channels from the plus next to "Channels" in the sidebar; make it private when in doubt — you can invite people later, but you cannot un-announce. Threads keep replies under the message that started them: hit Reply on any message and a side pane opens the conversation without derailing the channel (collapsed reply threads got a quality pass back in v8.0). Mentions — @username, @channel — drive notifications, and files drag straight into the message box.

What Are Boards, and Should You Turn Them On?

Boards is the kanban-style task board plugin (ex-Focalboard) that turns a channel into Trello-lite — and here is the honest state of it, said once: it has been community-maintained since September 2023, it is gone from the in-product App Marketplace, and it no longer enables itself on new installs. It still ships pre-packaged with the server — v12.0.1 bundles Boards v10.0.0 in the plugins folder — and it works on every edition. You just switch it on manually in System Console, then Plugins.

Fine for a personal kanban or a team's lightweight task list. Do not build your company's critical project tracking on a maintenance-mode plugin — for that, a dedicated tool is the saner call.

How Do You Invite People to Your Team?

Click your team name at the top of the sidebar, then Invite People — four options, and most teams only ever need the first two. Copy invite link hands out a shareable URL (admins can regenerate the code under Team Settings, then Access, then Invite Code); Invite as member sends an email, but only after an admin enables email invitations and configures SMTP.

Add existing users pulls people in from other teams on the same server; Invite as guest creates a restricted, channel-scoped account with optional magic-link login — good for contractors. Email invitations expire after 48 hours and are single-use, so resend rather than troubleshoot a dead link.

How Do You Connect the Mobile Apps?

The mattermost mobile app on iOS and Android is pre-built and free: install one, launch it, type your server's address, tap Connect, and log in with your server account — the same account, no separate mobile signup. One app can hold several servers (multi-server since v2.0), which matters if you also join a community server.

The certificate gotcha, said once: self-signed certificates are not accepted by the apps unless you install your CA on the device — in practice, mobile users need valid HTTPS. If you would rather not expose the server to the internet at all, put it behind Tailscale and connect the phone the same way; our Tailscale beginner guide covers that setup. Push notifications need MPNS/HPNS configured, and note that full message content can transit Apple or Google servers on the way — the Enterprise plan can redact that, the free edition cannot. The latest mobile release is v2.45 (October 2026), which needs server v11.7.0 or newer.

Do You Need HTTPS on a Self-Hosted Chat Server?

Yes — chat login tokens over plain HTTP on any network you do not fully control is asking for it, and the mobile apps effectively require valid HTTPS anyway. The nginx compose variant from the install section handles TLS once you set DOMAIN; if you would rather terminate HTTPS with something friendlier, our Caddy beginner guide walks through putting Caddy in front of any container with automatic certificates.

Team Edition or Enterprise: Which Do You Get?

Team Edition is the free, open-source (MIT) build: one Linux binary plus PostgreSQL, aimed at small teams and hobbyists — no SSO, roughly a 250-activated-user comfort zone. The Enterprise binary without a license key runs in a free "Entry" mode with limits (about 10,000 messages of history). Paid plans sit on top: Mattermost Professional adds SSO/LDAP and high availability; Mattermost Enterprise adds compliance and scale features.

7 Beginner Mistakes to Avoid

Every one of these has bitten a real first-time admin. Learn them from a table instead of from a broken evening:

Your First Deploy in 5 Steps

1. Clone the official Docker repo and cd into it.
2. Copy env.example to .env and set DOMAIN to your hostname.
3. Run compose with the nginx variant for HTTPS, or the without-nginx variant on port 8065.
4. Open the URL and create the first account — you are now the system admin.
5. Create your team, copy the invite link, and send it to your people.

Once it is up, keep an eye on it — our Uptime Kuma beginner guide sets up free monitoring in minutes, so you hear about downtime before your team does.

Sources

• Mattermost Documentation — Deploy Mattermost using Containers — https://docs.mattermost.com/deployment-guide/server/deploy-containers
• Mattermost Documentation — Mattermost v12 Changelog — https://docs.mattermost.com/product-overview/mattermost-v12-changelog
• Mattermost Documentation — Editions and Offerings — https://docs.mattermost.com/product-overview/editions-and-offerings
• Mattermost Documentation — Software and hardware requirements — https://docs.mattermost.com/deployment-guide/software-hardware-requirements
• Mattermost Documentation — Install Mattermost Boards — https://docs.mattermost.com/administration-guide/configure/install-boards
• Mattermost Knowledge Base — Boards Plugin in Maintenance Mode — https://support.mattermost.com/hc/en-us/articles/19614000831252-Boards-Plugin-in-Maintenance-Mode
• Mattermost Documentation — Invite people to your workspace — https://docs.mattermost.com/end-user-guide/collaborate/invite-people
• Mattermost Documentation — Mobile app changelog — https://docs.mattermost.com/product-overview/mobile-app-changelog
• Mattermost Documentation — Mobile Releases — https://docs.mattermost.com/product-overview/mattermost-mobile-releases
• Mattermost Documentation — Mobile apps FAQ — https://docs.mattermost.com/deployment-guide/mobile/mobile-faq
• Mattermost Documentation — Migration guidelines from MySQL to PostgreSQL — https://docs.mattermost.com/deployment-guide/migrate-to-postgres
• endoflife.date — Mattermost lifecycle — https://endoflife.date/mattermost
• GitHub — mattermost/mattermost — https://github.com/mattermost/mattermost
• star-history.com — mattermost/mattermost — https://www.star-history.com/mattermost/mattermost
• docrack.me — Mattermost Self-Hosted Install Guide 2026 (first-login flow) — https://docrack.me/en/mattermost-self-hosted-install-guide/
• oneuptime.com and linuxize.com Mattermost install guides (first-login flow corroboration, fetched this run)

Frequently Asked Questions

Is Mattermost really free?

Yes. Team Edition is MIT-licensed open source and free forever — install it on your own server and there is no seat count to pay. The Enterprise binary runs license-free in a limited Entry mode, and paid Professional and Enterprise plans add SSO, high availability, and compliance features.

Is Mattermost a Slack replacement?

It is the self hosted slack alternative: channels, threads, DMs, and file sharing in the same shape, but your messages live in your database on your server instead of a vendor's cloud. The mattermost vs slack question comes down to who holds your data — if you want cloud convenience and per-seat billing, Slack and Teams are the cloud lane; if you want to own your data, Mattermost is the self-hosted lane.

Can I install Mattermost on Ubuntu?

Yes. The official Docker path in this guide runs on any 64-bit Ubuntu — Docker, the clone, and compose up. For a production Ubuntu install, the documented upgrade path is the Linux tarball with systemd, Nginx, and PostgreSQL.

Does Mattermost work on mobile?

Yes — free iOS and Android apps. Type your server's address, tap Connect, and log in with your server account; one app can hold several servers. You need valid HTTPS in practice, because the apps do not accept self-signed certificates unless you install your CA on the device.

What happened to Mattermost Boards?

Boards went into community maintenance mode in September 2023 and left the in-product App Marketplace — it no longer enables itself on new installs. It still ships pre-packaged with the server (v12.0.1 bundles Boards v10.0.0) and works on every edition; enable it manually under System Console, then Plugins.