snapshot of https://github.com/mattermost/mattermost.git (master, 2026-09-16; blobs > 131072B omitted)

docs/main/administration-guide/onboard/migrate-gitlab-omnibus.mdx

@@ -0,0 +1,131 @@
+---
+title: "Migrate from GitLab Omnibus to standalone Mattermost"
+---
+## Overview
+
+GitLab has announced the [deprecation of Mattermost from the GitLab Omnibus package](https://docs.gitlab.com/update/deprecations/#mattermost-bundled-with-linux-package) with GitLab 19.0. As part of this transition, GitLab will continue to support Mattermost **up to version 10.11 ESR** within the Omnibus installation until the final removal date.
+
+To ensure continuity and long-term support, organizations using Mattermost within GitLab Omnibus should plan to migrate to a **standalone Mattermost installation**. This approach provides ongoing access to the latest Mattermost releases, security updates, and enterprise capabilities independent of GitLab’s release cycle.
+
+Migrating to a standalone deployment also enables greater flexibility in managing infrastructure, upgrading PostgreSQL, and scaling Mattermost independently to meet performance and compliance requirements.
+
+## Prerequisites
+
+Before you begin:
+
+- Administrative (root or sudo) access to the GitLab Omnibus server.
+- A new standalone **PostgreSQL** server prepared and accessible.
+- Sufficient disk space for the Mattermost database dump.
+- A planned maintenance window, as Mattermost downtime is required.
+- A current full backup of your Mattermost instance, including database and file storage.
+
+## Migration Steps
+
+Follow the steps below to safely migrate from GitLab Omnibus to a standalone Mattermost installation.
+
+<Note>
+
+The following procedure assumes your Mattermost database name is `mattermost_production` and your PostgreSQL user is `mmuser`. Adjust as needed for your environment.
+
+</Note>
+
+### Step 1: Create a Database Dump from GitLab Omnibus
+
+Use the GitLab Omnibus PostgreSQL tools to create a dump of the Mattermost database. Run this command on the GitLab server:
+
+``` bash
+sudo gitlab-psql -- /opt/gitlab/embedded/bin/pg_dump -h /var/opt/gitlab/postgresql --no-owner mattermost_production | gzip > mattermost_dbdump_$(date --rfc-3339=date).sql.gz
+```
+
+This will create a compressed SQL dump file of your Mattermost database.
+
+### Step 2: Prepare the New PostgreSQL Server
+
+Set up your new PostgreSQL server following the official [Mattermost database preparation guidelines](/deployment-guide/server/prepare-database). This includes:
+
+- Installing the correct PostgreSQL version supported by your Mattermost server.
+- Creating a new Mattermost database and user with appropriate permissions.
+
+### Step 3: Transfer and Restore the Database Dump
+
+Transfer the database dump file to your new PostgreSQL server, then restore it:
+
+``` bash
+zcat /tmp/mattermost_dbdump.sql.gz | psql -U mmuser -d mattermost
+```
+
+Verify that the database restoration completes successfully without errors.
+
+### Step 4: Update Mattermost Configuration
+
+On your standalone Mattermost server, update the `config.json` file to point to the new PostgreSQL server. Locate the `SqlSettings.DataSource` parameter and update it as follows:
+
+``` json
+"SqlSettings": {
+    "DriverName": "postgres",
+    "DataSource": "postgres://mmuser:password@new-postgres-server:5432/mattermost?sslmode=disable&connect_timeout=10"
+}
+```
+
+Ensure that credentials, hostnames, and connection settings match your new PostgreSQL configuration.
+
+### Step 5: Migrate the Mattermost Application and Data
+
+To move Mattermost application files from the GitLab server to a new standalone server:
+
+1.  **Install the same or newer version** of Mattermost on the new server. See [Deploy the Mattermost server](/deployment-guide/server/deploy-server#deployment-options).
+
+2.  **Copy your existing configuration and data** from the GitLab Omnibus instance:
+
+    ``` bash
+    # On the GitLab server
+    sudo cp /var/opt/gitlab/mattermost/config/config.json /tmp/
+    sudo cp -r /var/opt/gitlab/mattermost/data /tmp/mattermost_data
+
+    # Transfer to new Mattermost server
+    scp /tmp/config.json mattermost@new-server:/opt/mattermost/config/
+    scp -r /tmp/mattermost_data mattermost@new-server:/opt/mattermost/data/
+    ```
+
+3.  Ensure permissions are correctly set on the new server:
+
+    ``` bash
+    sudo chown -R mattermost:mattermost /opt/mattermost
+    ```
+
+### Step 6: Start Mattermost
+
+Start the Mattermost service on your new standalone installation:
+
+``` bash
+sudo systemctl start mattermost
+```
+
+Mattermost will now connect to your standalone PostgreSQL database.
+
+### Step 7: Verify the Migration
+
+After starting Mattermost, perform the following checks:
+
+- Confirm that Mattermost starts successfully with no database connection errors.
+- Review server logs for any startup or connection issues.
+- Log into Mattermost and verify that all teams, channels, and users are present.
+- Post test messages and upload files to confirm functionality.
+- Validate user authentication and permissions.
+- Confirm that database queries are directed to the new PostgreSQL server.
+
+## Important Considerations
+
+- Always maintain a **full backup** of your Mattermost database before migration.
+- Schedule a **maintenance window** to minimize user disruption.
+- Validate performance and monitoring configurations post-migration.
+- Ensure that your new PostgreSQL server follows Mattermost’s security and tuning best practices.
+
+## Troubleshooting
+
+If you encounter errors during the migration:
+
+- Review PostgreSQL logs for permission or connection issues.
+- Verify that the Mattermost PostgreSQL user has full access to the restored database.
+- Ensure that the `config.json` file contains the correct database connection string.
+- Restart the Mattermost service and check `mattermost.log` for detailed errors.