Guidelines for Updating Rocket.Chat

Prev Next

Updating your Rocket.Chat workspace is a straightforward process when you follow the necessary preparation steps. This guide walks you through the essential actions to ensure a smooth and successful Rocket.Chat update.

To update your desktop and mobile apps, refer to Install Desktop & Mobile App.

1. Plan your update

Planning is the most critical step in a successful update. Skipping this phase is the fastest way to introduce downtime or compatibility issues.

  • Check release notes: Each new version of Rocket.Chat comes with features, bug fixes, and security improvements. Review the release notes for your target version and identify any breaking changes that may impact your users.

  • Select a supported target version: Make sure the version you are updating to is actively supported. See the Version Durability documentation for support timelines.

  • Avoid skipping versions: Always update Rocket.Chat sequentially, especially across major versions. For example, to update from 1.x.x to 4.x.x, you must first upgrade to 2.x.x, then 3.x.x, and finally 4.x.x. Skipping versions can cause severe compatibility issues.

2. Back up your data

Always create a full backup of your Rocket.Chat instance before starting an update. This should include both your database and any custom configurations. A backup ensures you can restore your workspace if something goes wrong during the update. Refer to the MongoDB Backup and Restore guide for detailed instructions.

3. Review and update MongoDB

Each Rocket.Chat release is compatible with specific MongoDB version(s). Before updating Rocket.Chat, confirm that your existing MongoDB version is compatible with the targeted new release.

To verify your MongoDB version compatibility:

  1. See the Engine versions section in the GitHub release notes for the required MongoDB version of your release.

  2. You can also find detailed information on the supported MongoDB versions for each release in the MongoDB support requirements guide .

If your current MongoDB version is unsupported, you have to update it before updating Rocket.Chat.

To upgrade your MongoDB version:

Choose the deployment method below and follow the corresponding guide.

  1. Docker: See the Update MongoDB on Docker guide.

  2. Kubernetes: Visit the Update MongoDB on Kubernetes guide.

  3. Podman: Refer to Update MongoDB on Podman.

If you are updating your workspace from an older version (such as 1.x.x with MMAP), refer to the following flowchart and demo for a detailed walkthrough on moving to the latest supported MongoDB release.

4. Update Rocket.Chat

Once you've completed your preparations, you can proceed with the update. The steps to update Rocket.Chat vary and depend entirely on how your workspace is deployed. Select and follow the guide that matches your deployment method:

Once the update is complete, verify workspace functionality, review logs for warnings or migration messages, and confirm that users can access key features as expected.