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, or Podman.

• Launchpad (CLI) that provides a quick, comprehensive solution for deploying Rocket.Chat with Kubernetes.

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

• Docker: Update Rocket.Chat on Docker

• Kubernetes: Update Rocket.Chat on Kubernetes

• Podman: Update Rocket.Chat on Podman

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 fingerprint system 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 ensures that cloud features (such as license validation and push notifications) are associated with a single workspace.

Why would the Unique ID trigger a warning?

f a database is copied (for example, during cloning, migration, or scaling), the Unique ID is copied as well. This can unintentionally result in multiple deployments sharing the same ID.

To detect this, Rocket.Chat uses a fingerprint based on:

• The Site URL

• 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 represents a new deployment.

What should I do?

If this is an expected configuration change:

(for example, you updated the Site URL or changed database settings)

• It is safe to confirm the update.

• The workspace fingerprint will be validated again.

• The Cloud ID will remain the same.

If you changed the Site URL, this does not automatically update your Enterprise license. If your workspace uses an Enterprise license, it may still be tied to the previous URL. This can result in a “URL validation failed” error after confirming the update. In this case, you will need to contact your Customer Success Manager (CSM) to update or reprovision your license.

If this is a new deployment:

(for example, a cloned or duplicated instance)

• Confirm it as a new workspace.

Rocket.Chat will then:

• Generate a new Unique ID

• Reset all cloud connections

• Clear the cloud workspace link

• Reset the cloud license

Confirming a new workspace when it is not actually new can lead to issues with statistics, cloud services, and licensing. Make sure you choose the correct option 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. 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.

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

Refer to the following documents for further information:

• Supported MongoDB Versions

• Guidelines for Updating Rocket.Chat

• MongoDB Configuration

Some users may find that clicking Install Update doesn't seem to do anything. If a minute passes with no progress, you'll need to update manually:

1. Visit rocket.chat/download-apps

2. Download the version that matches your operating system

3. Run the installer to complete the update.

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.