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

---
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.