Deployment and Update FAQ

Prev Next

How do I deploy Rocket.Chat with Docker on Apple Silicon Mac (M-series)?

The Rocket.Chat Docker image (version 6.7.0 and later) is designed for the amd64 architecture, which is incompatible with the arm64 architecture used by Apple silicon Macs. Attempting to deploy the Docker image on an M-series Mac can result in compatibility issues.

You will likely to get this error after starting the Rocket.Chat container:

The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8) and no specific platform was requested

Follow the steps below to resolve it:

  1. Ensure you have Rosetta 2 on your Mac; this allows the M-series Macs to run Intel-based applications. Confirm this by running:

    arch -x86_64 uname -m

    If Rosetta 2 is installed, this command will output “x86_64.” If not, macOS will prompt you to install Rosetta 2.

  2. Open Docker Desktop, navigate to Settings > General and enable Rosetta for Docker Desktop. This allows Docker to emulate x86_64/amd64 architecture.

  3. In the compose.yml file, add “platform: linux/amd64” to the rocketchat service.

  4. Next, add “EXPERIMENTAL_DOCKER_DESKTOP_FORCE_QEMU: 1” to the mongodb service environment. This forces the service to use the correct emulation settings.

  5. Now, run docker compose up -d

Your Rocket.Chat instance should now be accessible via http://localhost:3000 or your ROOT_URL.

How do I deploy Rocket.Chat with AWS for Apple Silicon Mac (M-series)?

To do this:

  • In the AWS EC2 launch wizard, go to the “Application and OS Images (Amazon Machine Image)” section.

  • Choose an ARM-compatible OS, such as Ubuntu for ARM64.

  • Proceed with the rest of your deployment steps as usual.

Note: Not all AMIs or EC2 instance types support ARM architecture, so be sure to select compatible options.

Updating Rocket.Chat

How do I update a Rocket.Chat deployment?

For a deployment-specific update instructions, see the following resources:

Additional resources:

Why am I seeing a message about a “Unique ID change detected”?

This message appears when Rocket.Chat detects changes that may indicate a new deployment or a significant workspace configuration update. To prevent issues caused by cloned or duplicated deployments, Rocket.Chat uses a system called a fingerprint to verify the identity of each workspace.

What is the Unique ID?

The Unique ID is a hash that uniquely identifies a Rocket.Chat server. It is generated automatically the first time the server starts. This ID helps ensure that cloud features (e.g., license validation, push notifications) are only associated with a single workspace.

Why would the Unique ID trigger a warning?

If a database is copied, for example, to clone, migrate, or scale a deployment, the Unique ID is copied too. This can unintentionally cause two deployments to share the same ID.

To detect and prevent this, Rocket.Chat uses a fingerprint, which is based on:

  • The Site URL setting

  • The database connection string

If either of these values changes, the fingerprint becomes invalid, and admins are asked to confirm whether the change was expected or part of a new deployment.

What should I do?

If this is an expected configuration change (e.g., you updated the site URL or changed database settings):

  • It's safe to confirm the update.

  • The fingerprint will be validated again.

  • Nothing else will change.

If this is actually a new deployment (e.g., a cloned or duplicated instance):

  • You should confirm it as a new workspace.

In this case, Rocket.Chat will:

  • Generate a new Unique ID

  • Reset all cloud connections

  • Clear the cloud workspace link

  • Reset the cloud license

Note: Confirming a new workspace when it’s not actually new can lead to issues with statistics, cloud services, and licensing. Be sure before confirming.

Updating MongoDB

Why do I see a MongoDB deprecated warning immediately after an update?

This warning appears when your MongoDB is not compatible with your current Rocket.Chat version. To resolve this, upgrade MongoDB to a version supported by the Rocket.Chat release you're targeting.

Are there any recommendations for updating MongoDB?

Updating MongoDB safely is essential to avoid data loss or compatibility issues. Here’s what we recommend:

  1. Back up your database: Before doing anything else, create a complete backup of your MongoDB data.

  2. Check compatibility: Identify which MongoDB versions are supported by the Rocket.Chat version you’re upgrading to.

  3. Follow official guidance: We recommend using the official MongoDB documentation to guide your upgrade process.

  4. Plan for major version jumps: Upgrades between major versions (like 2.x → 3.x or 3.x → 4.x) often involve additional steps or migration requirements. Be sure to read the release notes and plan accordingly.

Refer to the following documents for further information:

Updating desktop app

Why can't I update my desktop app to version 2.17.0 or above?

In some cases, for version 2.17.0 and above, you may need help with updating your app. If you click on the Install Update button and nothing happens for one minute, then you need to follow the steps below: