Mattermost is team chat on your own server, in the style of Slack. Channels, threads, direct messages, file sharing and search, with desktop and phone apps that everyone on the team can use.
On this page
Good to know before you install
Separate accounts; no single sign-on (a paid Mattermost feature). Phone push notifications, usage diagnostics and the security-update check are off, so nothing is sent to Mattermost; the mobile apps still connect but get no alerts while closed. Each can be turned on in this app's Privacy settings.
At a glance#
- What it is
- Team Chat Communication
- Where it opens
- Web Interface
On its own port at
http://your-server:port, ormattermost.your-domainonce you have a domain - Updates
- Automatic A backup is taken first, and it rolls back if the update fails
- Backups
- Included Part of the daily backup when that's switched on
- Copies
- As many as you like Run several copies, each with its own data
What it's good for#
If your club, business or project lives in a group chat that's got out of hand, Mattermost gives it some shape. Conversations go in channels, replies go in threads so the main channel stays readable, and everything is searchable later. Files you share stay on your server. The Team Edition that LibrePortal installs is free, with no limit on how many people use it.
Mattermost, Rocket.Chat, Matrix or Stoat?
Rocket.Chat is Mattermost's closest neighbour in the catalogue, another team chat; try both and keep the one your team likes. Matrix suits you if you want end-to-end encryption and to talk to people on other servers. Stoat is more like Discord, for friends rather than work.
Signing in#
A new Mattermost makes whoever signs up first its System Admin, which would hand your server to the first stranger who found the page. So LibrePortal signs up first. As soon as Mattermost answers, it makes the admin account itself, checks that it can log in with it, and only then opens the app up. Until that's done, Mattermost is reachable from the server itself and nowhere else (why).
The account's email is admin@mattermost.invalid and its username is admin. The password is in the Login Details shown when the install finishes; press Welcome on the app's page to see them again. Mattermost accepts either the email or the username on its sign-in page.
The first time you sign in, Mattermost walks you through creating your first team, which is the space your channels live in.
If the install couldn't make the account
If something went wrong (Mattermost didn't answer within three minutes, say), the install says so and leaves the app reachable from the server only, so nobody else can sign up first. The simplest fix is to uninstall it and install it again. Only restart it to open it up once you know the admin account exists.
The email is a placeholder
.invalid is a name reserved for addresses that can never exist, so nobody else can receive mail meant for your admin. You can change it to your own address in your Mattermost profile, but the Reset User Password tool only keeps LibrePortal's copy of the password up to date for the account it made, found by that email. If you change it, note your new password yourself.
Adding your team#
After the first account, Mattermost only lets people join by invitation. There are two ways to add someone.
The simplest is from inside Mattermost: as an admin, invite people to your team, and share the invite link with them. They choose their own username and password when they follow it.
Or create the account for them from LibrePortal's Tools tab:
- Open Mattermost's page in LibrePortal and go to Tools.
- Run Create User Account with their email address. Leave the username empty and it's made from the email; leave the password empty and one is generated. Tick Make system admin only for people who should run the server with you.
- Send them the address and their password, and ask them to change it once they're in.
The other tools find people by email: Reset User Password (leave it empty to generate one), Set Admin Status, List Users and Deactivate User Account. Deactivating locks someone out but keeps everything they wrote, and you can switch them back on from Mattermost's System Console.
Use the tools when someone forgets their password. Mattermost has no mail server to send reset links with here.
Desktop and phone apps#
Mattermost has desktop apps for Windows, macOS and Linux, and phone apps for Android and iPhone. When an app asks for a server, give it the address you open Mattermost at in the browser: https://mattermost.example.com with a domain, or http://192.168.1.50: and the port number on your home network.
Away from home, the apps need to reach the server too. With a domain that just works. Without one, keep Mattermost private and use the LibrePortal VPN on the phone.
Notifications on a phone reach it through a push service run by Mattermost itself, not straight from your server.
To check: check whether push notifications to the phone apps work out of the box on LibrePortal's Team Edition (push-test.mattermost.com), and where in the System Console they're switched on
Good to know#
- Leave Authelia off. The page below says Mattermost can sit behind Authelia's sign-in. It can, but the desktop and phone apps can't get past it, so only turn it on if everyone uses the web page.
- Updates are automatic within the Mattermost version LibrePortal pins, and LibrePortal checks that Mattermost answers with the new version before calling it done. A backup is taken first.
- Backups include the database and every file people have shared. Mattermost's image is an unusual one with no
tarinside it, which quietly broke its backups before 0.4.8: every Mattermost snapshot was incomplete, and so every Mattermost update stopped for want of a good one. That's fixed, by reading Mattermost's files through a small helper instead. If you ran Mattermost on an older version, take a fresh Backup now before you rely on a snapshot, because the older ones may be incomplete. - Installs made before 0.4.7 are caught up on the admin: if an older Mattermost still has no accounts at all, LibrePortal makes the admin the next time it starts after the update, and its password appears in the Login Details. The Tools tab is another matter. It talks to Mattermost through its "local mode", which only installs from 0.4.7 have switched on, so on an older install the user tools fail. Press Update Configuration on the Config tab once: it sets Mattermost up again from LibrePortal's current version of it, with local mode on, and keeps your messages and accounts. It then checks the login on the Login Details card before opening Mattermost up again; if that isn't the admin's current password, Mattermost stays reachable from the server only until you restart it.
Addresses and ports#
Mattermost has one port. LibrePortal picks a free port number for each when you install, so yours will differ from anyone else's. The Config tab's Network section shows them, and the app's Open button uses the right one. "Anyone" means it's reachable from wherever your server is reachable; you can make it private later.
| What it is | Who can reach it | With a domain |
|---|---|---|
| Web Interface | Anyone | mattermost.your-domain |
Settings#
In its config file#
Mattermost's own settings aren't on the Config tab yet. They live in the app's config file, described here so you know they exist. How to change them.
| Setting | What it does | Starts as |
|---|---|---|
NameCFG_MATTERMOST_DISPLAY_NAME |
What this app is called on your dashboards. Leave empty to use its usual name | Empty |
Show on the LibrePortal DashboardCFG_MATTERMOST_SHOW_ON_DASHBOARD |
Whether this app gets a shortcut on the front page of the LibrePortal WebUI, separate from any Dashy dashboard Choices: true, false |
true |
Usage DiagnosticsCFG_MATTERMOST_TELEMETRY |
Whether Mattermost may send usage diagnostics to Mattermost Choices: true, false |
false |
Security Update CheckCFG_MATTERMOST_UPDATE_CHECK |
Whether Mattermost may ask Mattermost's servers about security fixes Choices: true, false |
false |
Phone Notifications RelayCFG_MATTERMOST_PUSH_RELAY |
Whether phone notifications may pass through Mattermost's push server, which sees when a message arrives Choices: true, false |
false |
Detailed logsCFG_MATTERMOST_VERBOSE_LOGS |
Whether Mattermost writes its normal, chattier logs, including who connected, instead of only warnings and errors. Choices: true, false |
false |
Debug logging for 24 hoursCFG_MATTERMOST_DEBUG_LOGS |
Turn on to see everything Mattermost is doing while you look for a problem; it turns itself off after 24 hours. Choices: true, false |
false |
Tools#
Mattermost's Tools tab has 5 buttons for jobs you'd otherwise need a terminal for. Each one runs as a task, so you can watch it on the Tasks page and read what it did. More about Tools.
Add a Mattermost user. Tick "Make system admin" for full rights.
Every account on this server.
Set a new password for an existing user.
Promote or demote a system administrator.
Revoke access without deleting content. Reversible from the System Console.
Works with#
These are the other apps Mattermost knows how to work with. Once it's installed, its page shows the same list with whether each one is connected. How this works.
- Email: Sends invitations, password resets and missed-message emails through your mail server, from an account of its own. LibrePortal sets this up by itself when both are installed.
- Grafana: Shows dashboards for the apps that have one. works with every app
- Prometheus: Collects metrics from the apps that can export them. works with every app
- Uptime Kuma: Watches your apps and shows when one goes down. works with every app
Privacy and security#
All clear Mattermost is team chat on your server. LibrePortal turns off its diagnostics, security-alert check and phone-notification relay to Mattermost.
What leaves this server#
- Link previews fetch the pages people paste
- Phone notifications work only if you set up your own push server
What LibrePortal turns off#
- Detailed logs and per-request access logging (switchable in Config)
- Diagnostics and usage reports (switchable in Config)
- Security-alert check (switchable in Config)
- Phone notification relay through Mattermost's test server (switchable in Config)
Licence: Compiled Team Edition: MIT (MIT-COMPILED-LICENSE); source: AGPL-3.0 with Apache-2.0 parts; Enterprise code is proprietary and not in this image. Audited: 21 October 2026. See the privacy of every app and the Promise.
Sources#
Under the hood#
- It runs these images:
mattermost/mattermost-team-edition:11.9.2@sha256:a0208e95ff9065086117fabdc65299786f0eb072bc27942cf8a15245b3937d4d,postgres:15.19-alpine@sha256:54e0dd8e8cddcdbb9156c2486eed5a43eccb7214d7c6828097d41ce049fb3984. - It can sit behind Authelia's sign-in once Authelia is installed.
- Its own project and documentation: github.com/mattermost/mattermost
Ports, settings, tools and connections on this page are read from LibrePortal v0.10.97's app catalogue each time the guide is built.
