Migrate Mattermost from GitLab Omnibus to a standalone installation

Five prerequisites in the documented procedure gate the work, and two of them are decisions to make early. The first is root or sudo access to the GitLab Omnibus server. The migration stops the bundled Mattermost, exports its data and reads the existing configuration, so the account needs enough privilege to do all three on that host. The platform team usually owns this access, and the security team should approve any temporary elevation. Confirm early which Mattermost version the Omnibus package runs. GitLab has announced that Omnibus will support Mattermost only up to 10.11 ESR, and Mattermost lists that release as end of life on 2026-08-15, so both the target version and the migration date depend on the answer.

A new standalone PostgreSQL server must be provisioned and reachable from the target Mattermost host before the downtime window opens. The database team usually owns this build, including the network path, TLS settings, authentication method and backup job. Building it inside the window adds risk to the period when users are offline. The PostgreSQL major version is the first decision. Choose a version that the target Mattermost release supports and that is still inside PostgreSQL's support period. According to the PostgreSQL versioning policy, version 14 is supported until November 12, 2026, 15 until November 11, 2027, 16 until November 9, 2028, 17 until November 8, 2029 and 18 until November 14, 2030. Ask the database team to record the end date in the change ticket, because a version that ends support soon after go-live creates a second upgrade project.

Disk space must cover the database dump, the file storage copy and the restored data on the destination. The export writes to the source host, so the Omnibus server needs free space for the dump while it runs. The new server needs room for the restored database and its write-ahead logs. The platform and storage teams usually size this. Measure the current database size and the file storage directory on the source, then add the headroom the change board requires. Base the figure on those measurements, since the size of a dump depends on the installation's history and file volume. Confirm free space on both hosts, and confirm that the filesystem will not fill during a long restore.

A maintenance window with downtime is needed because Mattermost must stop accepting writes while the export runs. Otherwise the database dump and the file copy will not describe the same point in time. The change board and business owners usually agree the window. Its length should come from a rehearsal on a copy of the data, timed end to end, including the restore, the application install and the verification steps. Plan the rehearsal against the target release. Mattermost ships server versions in binary form on the 16th of each month. Version 11.7 is an Extended Support Release, released on 2026-05-15 and supported until 2027-05-15. Version 12.0 was released on 2026-10-16 and supports until 2027-01-15. Confirm with the vendor and your change board whether a monthly release or the ESR fits your support plan.

A full backup of the database and file storage is the rollback path, so take it and test it before the window opens. The backup owner, usually the platform team with security oversight, should confirm that the backup restores into a scratch environment, which proves more than a completed job log. Include the Omnibus configuration files, since the new server needs the encryption keys referenced in the Mattermost configuration to read existing data. Keep the Omnibus installation intact until the new server passes its checks. Record who can authorize a rollback and how long backups are retained. Ask the security team to confirm encryption at rest, access controls on the backup location and the retention period that policy requires.

The documented procedure requires downtime, so the maintenance window has to be agreed with the business before anyone sets a date. Users cannot keep posting while the database is dumped, moved and restored, and the Mattermost administrators and the business owners who depend on the workspace need to accept that outage in writing. Size the window from rehearsal results, not from estimates. Run the full sequence against a copy of the Omnibus data on the standalone target, time each stage separately (dump, transfer, restore, configuration changes and validation), and plan around the slowest run you observed. Record each run so the change board can see where the time went. If the rehearsal shows that the dump needs more disk space than planned, fix that before the window is booked, because a failed dump during cutover uses up the window you agreed.

Take a full backup of both the database and file storage immediately before the cutover, after users have been stopped from writing. The database holds channels, posts, users and settings. File storage holds uploaded attachments that the database only references, so a database backup alone cannot restore a working workspace. Capture the Mattermost configuration file as well, along with the secrets it contains, such as encryption keys and integration settings, and store that material securely alongside the backup. Ask your GitLab administrators to confirm in the GitLab backup and restore documentation for your version which components the backup covers, what it leaves out and whether it includes the Mattermost data you need. Then confirm that the Mattermost procedure for your version lists the same items. Any gap between the two lists is a gap in your recovery plan, so resolve it before the window.

A backup that has not been restored is an assumption. Restore the backup to a separate server built the way the target standalone installation is built, using the same PostgreSQL major version and the same Mattermost version that the cutover will use. Check that the server starts, that test users can sign in, that channel and message counts match the source, that a sample of attachments opens and that search returns expected results. Keep the restore server away from the production network path, or disable outbound email, webhooks and integrations first, so the copy cannot notify users or change data in connected systems. Store checksums and file listings with the backup so the restore can be compared with what was taken, and record who signed off the test.

Decide the rollback plan before the cutover starts. Define the validation checks that the restored standalone instance must pass, and name the person who makes the go or no-go decision if one of them fails. If the restored instance fails, the rollback is to keep the original Omnibus Mattermost stopped but intact, point users back to it and restart it. Do not remove or alter the Omnibus data until the new instance has run long enough for your team to be satisfied, and agree that period in advance. Plan for messages written to the new instance before a rollback: decide whether they will be kept, exported or lost, because returning to the old database without a plan for them creates a split history. Test this rollback path during the rehearsal too, not only the forward path.

PostgreSQL recovery concepts apply to this move in two ways. A logical dump is a snapshot taken at one moment, so it recovers the data as it was when the dump ran. It does not let you return to an arbitrary point in time. Point-in-time recovery depends on a base backup plus archived write-ahead log, as described in the PostgreSQL continuous archiving documentation. Confirm whether the source PostgreSQL bundled with Omnibus archives its log, and whether your standalone server will, because that decides how far back you can restore after cutover. Set backup retention for the period after the move based on your recovery objectives and the records rules your organization follows. Keep at least the pre-cutover backup for as long as the rollback window and any review require, and test a restore from the retained set before you rely on it.