Mattermost Mobile v2: building the React Native client for self-hosted chat

What the Mattermost mobile app is for, and who ends up installing it

Mattermost Mobile v2 is the client, not the server. The repository holds the iOS and Android applications built in React Native, and they talk to a Mattermost server that someone else operates. That split decides who the project is for. If your organisation already runs Mattermost, this is the app your users install to read channels, get push notifications and join calls from a phone. If you do not run a server, the app has nothing to point at.

The README states Mattermost is an open source Slack alternative used by thousands of companies in 21 languages. The mobile repository is one piece of that stack. It is published under Apache-2.0, and package.json marks the package as private, which tells you the intended distribution path is the App Store and Google Play rather than npm. The README points readers to the App Store, the Google Play Store, or the build-your-own instructions on the developer site.

Version compatibility is the first thing to check. The README lists a minimum server version of the current ESR version, 11.7.0+, supported iOS versions of 18.0+, and supported Android versions of 11.0+. Those are hard floors, not suggestions. A phone stuck on iOS 17 will not run this client regardless of how healthy the server is.

React Native, WatermelonDB and the split between app and server

The dependency list in package.json shows the shape of the client. React Native supplies the UI layer, and @nozbe/watermelondb 0.28.1-0 is the local database, which is how the app keeps message history readable when the network drops. @mattermost/react-native-network-client 1.11.2 handles the HTTP and websocket layer, and @msgpack/msgpack 3.1.3 is used for the binary encoding that keeps payloads small on mobile connections. Calls are split across @mattermost/calls and a local native module, @mattermost/calls-native, which lives under libraries/.

Several dependencies are file: references into the libraries/ directory rather than registry packages: @mattermost/calls-native, @mattermost/hardware-keyboard, @mattermost/rnshare, @mattermost/rnutils and @mattermost/secure-pdf-viewer. That is a deliberate layout. Native code that only this app needs is versioned next to the JavaScript that calls it, instead of being published separately. It also means a plain npm install is not enough to reproduce a build; the native projects under android/ and ios/ have to be compiled too.

The data flow is conventional for a chat client. The app authenticates against the server, syncs channels and posts into WatermelonDB, and renders from the local store. Push notifications do not travel through the app at all. They go from the server to a push proxy, then to APNs or FCM, which is why the README warns that self-compiled apps require you to deploy your own Mattermost Push Notification Service.

Installing Mattermost Mobile and pointing it at a server

Most users should not build anything. The README gives two download routes: the App Store page at mattermost.com/mattermost-ios-app/ and the Google Play page at mattermost.com/mattermost-android-app/. Install from there, open the app, and enter the URL of your Mattermost server when prompted.

If you want the beta channel, the README lists a Google Play testing link for com.mattermost.rnbeta and a TestFlight link for iOS. Beta builds arrive periodically and the app notifies you when an update is available. Leaving the programme is done from the same Google Play page or from the Mattermost Beta page in TestFlight.

Building from source starts with the toolchain pinned in the repository. The engines field requires Node ^22.11.0 or ^24.15.0 and npm ^10 or ^11, and .nvmrc and .node-version are both present at the top level, so version managers will pick the right runtime automatically.

nvm use
npm ci

The README does not reproduce the full build steps. It links to developers.mattermost.com/contribute/mobile/build-your-own/ for that, and the repository carries android/, ios/, fastlane/ and Gemfile for the native and release sides. Treat the developer site as the source of truth for the build, not this article.

One configuration point is worth stating plainly. If you self-compile, the README says you also need to deploy your own Mattermost Push Notification Service, pointing at the mattermost-push-proxy releases. Without it, a self-built app will receive no notifications.

Where the client breaks: certificates, websockets and self-compiled builds

The troubleshooting section of the README is unusually honest about the failure modes, and they are all server-side.

The first is the message "Cannot connect to the server. Please check your server URL and internet connection." The README attributes this to SSL certificate configuration, and recommends testing the certificate with a service such as ssllabs.com. A missing intermediate certificate in the chain is the usual cause. The README also states that the apps cannot connect to servers with self-signed certificates and suggests Let's Encrypt instead. For a small self-hosted deployment that has been running on a self-signed cert for years, this client simply will not work until the certificate is replaced.

The second is a "Connecting..." bar that never clears. The README says a healthy app shows a grey bar that clears or changes to "Connected" after reconnecting. If it persists while the internet connection is fine, the README asks you to check with your server administrator whether NGINX or another reverse proxy is in front of the server, and whether it is configured to support the websocket connection for APIv4 endpoints. This is a proxy configuration problem, not an app bug, and no amount of reinstalling the client will fix it.

The third is the push proxy requirement for self-compiled builds, described above. It is the single biggest reason to prefer the store builds. Running the official app means Mattermost operates the push path for you; building your own means you own that service.

Mattermost web compared with the native mobile client

The most direct alternative is the Mattermost web app in a mobile browser. It needs no install, works on any device that renders the web client, and is updated when the server is updated. The trade-off is everything the native client exists to provide: push notifications through APNs and FCM, a local WatermelonDB store that keeps history readable offline, native camera and file access, and the calls modules that ship as native code under libraries/.

A browser tab also cannot be pinned to a home screen with the same notification behaviour, and it depends on the server being reachable from that browser at that moment. The native client keeps a local copy and syncs when it can.

The other alternative people reach for is a different chat product entirely, which is a migration decision rather than a client decision. Within the Mattermost stack, the meaningful choice is store build versus self-compiled build, and the README makes that choice easy: self-compiling moves the push infrastructure onto you.

Releases, contribution cost and the Apache-2.0 licence

The README states the project plans monthly releases, and the release history matches that cadence: 2.44.0 on 2026-09-16, 2.43.1 on 2026-08-24, and 2.43.0 on 2026-08-13. The last push to the repository was on 2026-09-24, and the repository is not archived. package.json carries version 2.45.0, ahead of the most recent tagged release, which is normal for a main branch between releases.

For an operator, the upgrade cost is low. The store builds update themselves, and the app is a client: upgrading it does not touch your server. The constraint is the other direction. Your server must stay at or above the ESR version the README names, currently 11.7.0+, or the client may refuse to connect. Server upgrades are the expensive part, not app upgrades.

For a contributor, the cost is higher than the JavaScript suggests. The repository uses Buck configuration (.buckconfig), Detox for end-to-end tests under detox/, Jest, ESLint and Husky hooks, and it carries patches/ for patched dependencies. Native modules under libraries/ mean Xcode and Android tooling are part of the loop. The README points contributors at issues marked [Help Wanted] and at the Native Mobile Apps channel on the community server.

The licence is Apache-2.0, stated both in the README's repository metadata and in package.json. That permits commercial and closed-source use with the usual attribution and notice obligations; LICENSE.txt and NOTICE.txt are both at the top level. This is a description of the licence text, not legal advice, and any redistribution plan should be reviewed against those two files.

Editorial conclusion

Adopt the store builds if you run a Mattermost server at the current ESR version and want the official client on iOS 18.0+ or Android 11.0+. Do not self-compile unless you are prepared to run the Mattermost Push Notification Service, because the README states that self-compiled apps require your own push proxy. Before rolling it out, verify your server version against the ESR requirement and confirm your TLS chain with an SSL test, since the app cannot connect to servers with self-signed certificates.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mattermost/mattermost-mobile on GitHub
3. Project website
4. README
5. Releases