Upgrade Mattermost v10 to v11 LTS

Why update now

Mattermost publishes ESR (Extended Support Release) versions with an extended lifetime, then declares their end of life on a pre-announced date. ESR v10.11 reached end of life on August 15, 2026. From that date, no security patches are backported to that branch: vulnerabilities discovered after the EOL date remain open on instances that do not migrate.

A team messaging platform receives attachments, credentials shared in DMs, sometimes API keys left in messages. An unpatched instance exposes this data to any unapplied fix. v11 is the current LTS — it is the only version that will receive patches for the coming months.

What v11 LTS brings over ESR v10.x

Active security patches — the branch receives security fixes published by the Mattermost team throughout its support cycle.
Performance improvements — optimized PostgreSQL queries and reduced memory consumption under heavy load.
Reworked video call interface — improved quality and stability for channel calls.
Updated plugins — official plugins (Calls, Boards, Playbooks) have v11-compatible versions published in the plugin manager.
Database migration fixes — migrations accumulated since v10 are applied cleanly, improving long-term schema integrity.
Extended support — the v11 LTS benefits from a prolonged support window, avoiding another migration in the near future.

Prerequisites before you start

Check the following points before launching the procedure.

Docker Compose v2 — the command must respond to docker compose version (with a space, not a hyphen). If you still have docker-compose v1, migrate to Compose v2 first: official Mattermost v11 images assume this format.

Root or sudo access on the VPS — the following commands act on Docker volumes and configuration files.

Available disk space — check with df -h that the volume hosting your Docker volumes has at least 3 GB free for dumps and temporary images.

Sufficient RAM — Mattermost v11 runs comfortably with 2 GB of RAM for fewer than 50 active users. Check with free -m before the update.

Current version noted — before any operation, note the installed version: docker exec <mattermost-container> mattermost version. This is step 1 of the procedure.

Step-by-step update procedure

Note the current version

Before changing anything, record the current version:

docker exec mattermost mattermost version

Note the number (for example v10.11.2). This reference lets you compare after the update and confirm that the migration took place.

Back up the PostgreSQL database

This is the most critical step. Run a pg_dump from the PostgreSQL container:

docker exec <pg-container> pg_dump -U mattermost mattermost > backup_mattermost_$(date +%Y%m%d).sql

Replace <pg-container> with your container's actual name (visible with docker ps). Verify that the created .sql file is not empty (ls -lh backup_mattermost_*.sql). Without this backup, any failed DB migration is irreversible.

Back up Docker volumes

Also back up the Mattermost volumes (configuration, data, plugins):

tar czf mattermost_volumes_$(date +%Y%m%d).tar.gz /opt/mattermost/config /opt/mattermost/data /opt/mattermost/plugins /opt/mattermost/logs

Adapt the path to your installation (/opt/mattermost is the standard directory for the official mattermost-docker repository). Move the archive off the VPS to external storage before continuing.

Note the active plugins

From System Console → Plugins → Plugin Management, list all enabled plugins with their version. Write them down: after the update, you will need to check compatibility for each one.

Alternatively, via the API:

curl -s -H "Authorization: Bearer <your-token>" https://chat.yourdomain.com/api/v4/plugins | python3 -m json.tool | grep -E '"id"|"version"|"active"'

Stop Mattermost and PostgreSQL

Stop the stack cleanly before pulling new images:

docker compose down

Verify that no Mattermost container is still running: docker ps | grep mattermost.

Pull the new images

From the directory containing your docker-compose.yml:

docker compose pull

This command downloads the new images for all declared services (mattermost and postgres). If your docker-compose.yml pins an explicit version (mattermost/mattermost-team-edition:v10.x.x), update it to v11 or latest (then pin the exact digest for reproducibility).

Restart the stack

Bring all services back up:

docker compose up -d

Mattermost starts, detects that the database is at a v10 schema and automatically launches migrations. This step can take from 30 seconds to a few minutes depending on your database size.

Verify database migrations

Follow the logs immediately after startup:

docker compose logs mattermost | grep -i migrat

Expected lines look like Running migration X.Y or Migrating database from version X. If you see failed to run migrations or error running migration, stop (docker compose down) and restore from the dump before going further.

To follow in real time: docker compose logs -f mattermost — wait for the Server is listening on message.

Verify the new version

Confirm that the update is effective:

docker exec mattermost mattermost version

The output must show a v11.x.x number. Log in to the web interface and navigate to System Console → About → Mattermost Server to cross-check.

Test critical functionality

Before signing off on the update, manually test the following:

- Log in with a user account
- Send and receive a message in a public channel
- Send a direct message
- Upload an attachment
- Check the message history predating the update
- Verify that inbound webhooks work if you have configured any

Full history must remain accessible: that is the first point to check.

Verify plugins

In System Console → Plugins → Plugin Management, compare the list against the notes from step 4. For each enabled plugin:

1. Check that it still shows as active.
2. If a plugin is disabled with an incompatibility message, check its repository for a v11-compatible version.
3. Update from the plugin manager if a new version is available.

Official Mattermost plugins (Calls, Boards, Playbooks, Jira, GitHub) are updated alongside the server and available directly in the built-in marketplace — just verify they are at their latest available version.

Clean up old Docker images

Once the update is validated in production, free the space occupied by old images:

docker image prune -f

This command removes all images not referenced by an active container. It can reclaim several gigabytes if you have kept multiple Mattermost image versions.

Always test the update outside production first

If you administer a production instance with many users, reproduce the operation in a test environment first. Restore a copy of your PostgreSQL dump onto a test VPS, run the full procedure, and check the result. This reveals plugin incompatibilities and potential migration errors before they affect your users.

Plugin compatibility after the update

v11 introduced changes to the plugin API. The majority of official and active community plugins are compatible, but incompatibilities may appear with older, unmaintained plugins.

How to check compatibility: go to System Console → Plugins → Plugin Management. An incompatible plugin shows an error status and a message specifying the minimum required version.

If a plugin is incompatible:

1. Check the plugin's GitHub repository to see if a v11-compatible version has been published.
2. If yes, download the .tar.gz and install it from System Console → Plugins → Upload Plugin.
3. If not, assess whether the plugin is critical. If it is, report it to the maintainers and keep a copy of v10 (your dump) in the meantime.

Official Mattermost plugins (Calls, Boards, Playbooks, Jira, GitHub) are updated at the same time as the server and available directly in the built-in marketplace — just check that they are at their latest available version.

Troubleshooting: common errors

failed to run migrations in the logs
The database migration failed. Common causes: the PostgreSQL container was not started before Mattermost (startup order issue in Compose), or permissions on the database are incorrect. Stop with docker compose down, verify that postgres starts before mattermost (depends_on clause in docker-compose.yml), then restart. If the error persists, restore the dump and examine the full logs with docker compose logs mattermost 2>&1 | grep -i error.

Plugin marked as incompatible immediately after the update
The plugin is bound to a deprecated API. Disable it from the console (System Console → Plugins → Plugin Management → Disable) so Mattermost remains functional, then update the plugin separately.

SIGTERM during migration (container stopped mid-work)
If the Mattermost container restarts during migration (Docker timeout, SIGTERM), the database may end up in an intermediate state. Sign: mattermost version shows a hybrid number or logs show missing column errors. Restore from the PostgreSQL dump and restart, ensuring MATTERMOST_UPGRADE_TIMEOUT is set to a sufficient value (at least 600 seconds for large databases).

Connection issue after restart
If the interface responds but users cannot log in, verify that MM_SERVICESETTINGS_SITEURL in docker-compose.yml is https:// and matches exactly the URL you are using. A hostname or protocol change during the update invalidates existing session tokens.

database schema version mismatch error
Mattermost detects a gap between the binary version and the database schema. This occurs if you had pinned a v10 image and a partial previous attempt left the schema in a partially-v11 state. Restore the full v10 dump, then restart the procedure from step 5.

After the update: best practices

Once v11 is validated in production, a few settings keep the instance in a controlled state.

Pin the image version in docker-compose.yml — replace latest with the precise tag (mattermost/mattermost-team-edition:v11.x.x). This prevents a future docker compose pull from silently pulling a newer version without your decision.

Schedule PostgreSQL backups — a cron that runs pg_dump every 24 hours and retains the last 7 dumps is the minimum for a production instance.

Monitor the Mattermost security channel — subscribe to https://mattermost.com/security-updates/ to receive CVE announcements. The next EOL for the v11 LTS will be announced several months in advance.

For further reading, see the initial installation guide in the article [Host Mattermost on your own VPS](/blog/heberger-mattermost) and the case for leaving Slack in [Migrate from Slack to Mattermost or Rocket.Chat on VPS](/blog/migration-slack-mattermost-rocketchat-vps).