Deployment and Update FAQ

Rocket.Chat supports the following deployment methods:

• Air-gapped deployment with Docker to use Rocket.Chat in an isolated environment.

• Cloud-hosted workspace with tiers of various hosting services.

• Self-managed workspaces where you can deploy Rocket.Chat yourself using Docker, Kubernetes, Snaps, or other methods like Ubuntu and DigitalOcean.

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

• Docker: Update Rocket.Chat on Docker

• Kubernetes: Update Rocket.Chat on Kubernetes

• Other methods (such as Ubuntu, DigitalOcean): Additional Deployment Methods

Additional resources:

• Guidelines for Updating Rocket.Chat

• System Requirements

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.

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. The supported MongoDB versions are displayed under the Engine versions section for each release.

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:

• Supported MongoDB Versions

• Guidelines for Updating Rocket.Chat

• MongoDB Configuration

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:

• Go to https://www.rocket.chat/download-apps.

• Download the matching edition for your OS.

• Install the app.

On CentOS deployments (and other SELinux-enabled systems like RHEL or Rocky Linux), SELinux can block Nginx from connecting to Rocket.Chat’s backend. This is a common occurrence with Nginx because, by default, it runs under the httpd_t SELinux domain, which does not allow outbound network connections unless explicitly permitted. Our default Traefik configuration runs inside containers under different SELinux policies, so it’s less likely to be affected.

Even if your firewall and proxy configuration are correct, this restriction can still cause issues when Nginx is used as a reverse proxy for Rocket.Chat.

Symptoms

• Browser shows 502 Bad Gateway or similar errors.

• Nginx error log contains:

  connect() failed (13: Permission denied) while connecting to upstream

Solution

1. Enable the SELinux boolean to allow Nginx network connections:

   setsebool -P httpd_can_network_connect 1

2. Check current status:

   getsebool httpd_can_network_connect

If you see httpd_can_network_connect --> on , then SELinux already allows Nginx outbound connections.