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