Mattermost v12 upgrade

Three platform floors decide the order of work before any Mattermost server binary changes: the PostgreSQL version, the glibc version on the operating system, and the search backend. Mattermost v12.0 requires PostgreSQL 15 or later, and PostgreSQL 14 and earlier must be upgraded before the server. The operating system comes next because v12.0 binaries require glibc 2.34 or later. A host that cannot provide that glibc version cannot run the binary at all, so an OS problem blocks the server change just as firmly as a database problem does. The database and operating system work therefore comes first, the search backend is planned alongside it, and the server upgrade follows last.

Start with an inventory of every node that runs the application and of the database host. On the database, connect with psql and run SELECT version(); or psql --version to confirm the major version, noting that the server version matters more than the client tool. On each application node, run ldd --version and read the glibc version from the first line, then run cat /etc/os-release to record the OS family and release. Record these values per host in a table, because clustered deployments often have nodes that were built at different times. If you run the server in containers, confirm with the official notes whether your image base changes which glibc the binary uses, since the host check alone may not answer that question.

If any node reports RHEL 7 or RHEL 8, that node cannot run v12.0. Mattermost v12.0 drops both releases, and v11.11 was the last release that supports them. Staying on v11.11 is a valid interim position, but v11.11 support ends on 2026-12-15, so it is a bridge with a deadline rather than a long-term target. The practical path is to plan replacement nodes on an operating system release that provides the required glibc version, build them, and move the application onto them before the v12.0 change. Ask your vendor or your Mattermost contact to confirm which OS releases meet the floor, because that list is maintained in the official notes and should be checked against your own build standard.

Mattermost v12.0 no longer supports OpenSearch 1.x as a search backend, so any deployment that depends on OpenSearch 1.x needs a decision before the server change. First, confirm the search backend name and exact version in use, including whether any search replicas or indexes depend on it. Then choose between upgrading OpenSearch to a version the official notes list as compatible or replacing the backend, and schedule that work as its own change with its own test and rollback plan. Do not assume that a newer OpenSearch release is automatically accepted. Confirm the exact compatible versions in the official upgrade notes for v12.0, and treat that document as the authority for any version number in this plan.

Mattermost v12.0 includes a database migration that widens the message column so the maximum message length rises from 16,383 to 262,144 characters. For most teams the first question is what this does to database size. Longer allowed messages do not fill the table on their own, because only messages users actually post at greater length consume the extra space. The migration itself changes the column definition on a table that holds your full chat history, so its effect on storage, locking and run time depends on how PostgreSQL handles that change for your specific column type and version. Confirm the exact column change and any table rewrite behavior in the v12.0 upgrade notes before you estimate anything for your environment.

The migration runs against the production database as part of the upgrade, so downtime is set by how long it takes on your data. Duration depends on table size, the number of stored messages, the disk throughput and memory of the database server, and whether other load competes for locks during the change. No duration is given here, so measure it. Restore a recent production backup to a staging server with comparable data volume, including your largest channels and your biggest posts table. Run the full upgrade path on that copy, record elapsed time for each step, and repeat the run so you see the spread of results, including a slower run, rather than relying on one timing.

Set checks before and after the migration so you can tell a slow run from a failed one. Before the upgrade, record the size of the posts table and its indexes, row counts, and confirm that a backup is verified by restoring it at least once. After the migration, compare table and index sizes with that baseline, confirm that no indexes were left invalid, and run a set of known searches to check that results match. If you use an external search backend, confirm that its index still agrees with the database for the channels you sampled. Finally, pull a sample of messages that were close to the old 16,383 character limit and confirm they display, edit and export correctly in the web, desktop and mobile clients.

The remaining decision is whether to schedule a maintenance window. Add the measured staging duration to the time needed for the backup, the upgrade steps and the post-upgrade checks, then compare that total with when your users are active across time zones. Ask Mattermost and your implementation partner to confirm whether the migration blocks reads and writes for its full duration, and whether a high availability cluster can be upgraded one node at a time. If the migration must run in a single pass, announce the window with a defined rollback point and name the person who can decide to restore the backup if checks fail. Record the decision, its reasons and the measured timings in the change ticket so the record matches what happened.

Plan plugin work before you schedule the server upgrade. From v12.0, the Mattermost web and desktop apps are built on React 19, and web app plugins that have not been rebuilt for v12.0 may have their activation suppressed. A plugin can still appear as installed in the admin console while it stops running for users, so the features it adds to the web app may disappear after cutover. Confirm the exact behavior with the plugin's source or vendor for the versions you run, and test every plugin in staging against v12.0 before the production window.

Build a plugin inventory first. For each installed plugin, record its name and version, its source (Mattermost-built, community or in-house), its build status against v12.0, and the named owner who can rebuild or replace it. Include plugins that are currently disabled, because re-enabling them after the upgrade can expose the same React 19 issues. Ask each owner whether a v12.0 build exists and when it was last tested. Community plugins often depend on the maintainer's response, while in-house plugins need a developer with source access and a working build pipeline. Mark each plugin as ready, rebuild required or retire before the staging test window opens.

The built-in Slack import API and CLI were removed in v12.0, so any workflow that depended on them must be redesigned before cutover. Review runbooks, scripts and scheduled jobs that called the import endpoint or ran the import command, and assign an owner to each one. Automation that still references the removed commands will fail at its first run, and the failure may surface late in a migration window with little time to recover. Decide early whether the Slack history move belongs to this upgrade or to a separate project, because the answer changes the sequencing, the staging data set and the approvals you need.

Mattermost documents the Slack migration path in three stages: export the workspace from Slack, convert the export with the mmetl tool into a bulk import JSONL file plus attachments, then upload and process the result with mmctl. Use this path as the basis for the redesigned workflow, and run it end to end against a copy of the v12.0 target before you schedule the production run. Confirm with the Mattermost documentation which mmetl and mmctl versions match your server, how attachments are handled at your expected volume, and how user matching will work for your accounts. Those details decide how much staging time the migration needs.

Integrations are not part of the Slack export and cannot be migrated through this path. Inventory the Slack apps, bots, webhooks and slash commands that teams use, and record which channels and teams depend on each one. Each item needs a named owner and either a reconfigured Mattermost equivalent or a documented retirement. Agree on a cutover message so users know which automations stop and when. Treat the gap as a sponsor decision: a low-use bot may be acceptable to drop, while an integration that routes on-call alerts needs a tested replacement before the Slack source is retired.