Before you proceed, kindly visit Deploy with Kubernetes guide to gain a foundational understanding of the deployment process.

Components Overview

This deployment architecture consists of several "micro" services or smaller components, each focusing on one feature of Rocket.Chat. Imagine that each component provides a service, and they are all combined to form your fully operational Rocket.Chat workspace.

The components include the following:

  • authorization (rocketchat/authorization-service): This provides authorization capabilities like role/permission validation. It differs from authentication, which primarily deals with login systems.

  • nats (docker.io/nats): A messaging system that provides a scalable and highly available message bus for microservices communication. It acts as a message distributor, i.e., you point to the distributor instead of pointing to each component in the deployment resource. This determines the service to forward the requests.

To learn more about NAT, see the official documentation.

  • stream-hub (rocketchat/stream-hub-service): A message broker that provides a scalable and fault-tolerant message stream for Rocket.Chat. It receives real-time changes or data from MongoDB and sends it to all the services. The services can act on that change at their discretion.

  • accounts (rocketchat/accounts-service): The accounts component is responsible for managing user accounts and authentication -

  • ddp-streamer (rocketchat/ddp-streamer-service): It deals with all web socket connections. All web socket connections must be forwarded directly to this service. It uses the Distributed Data Protocol (DDP).

  • presence (rocketchat/presence-service): The presence component is responsible for managing user presence status.

  • The central Rocket.Chat monolith (rocketchat/rocket.chat): Each component is disabled from this monolith, so each "service" can take over its respective functionalities.


Rocket.Chat microservices deployment looks like the diagram below. Each component is comprised of one container from a bare metal perspective.

Since each component is a container, you can pull them the same way as any docker image. Consequently, you can also deploy Rocket.Chat with all these components via docker directly or with docker-compose; however, it is not officially supported. To deploy using docker directly, you are required to set up nats. Ensure that you're using a custom network to connect each related container.

See the official documentation to learn how to start NATS on your server.

Bare minimum, each container must be started with MONGO_URL and TRANSPORTER environment variables set, pointing to the MongoDB database (using full connection string) and the nats gateway address, respectively. At the very least, each container must be started with MONGO_URL and TRANSPORTER environment variables set, pointing to the MongoDB database (using full connection string) and the NATS gateway address, respectively. All /sockjs and /websocket connections must be routed through a reverse proxy or load balancer (LB), with the remainder going to the monolith.

Again, it is essential to note that we do not support direct docker/compose microservices deployment. The only supported method currently is using Kubernetes with our official helm chart.

Microservices Deployment

Rocket.Chat's microservices architecture allows for greater scalability, flexibility, resilience, and fault tolerance in the functioning of your workspace. This makes it possible for your workspace to manage large user volumes and adapt to changing business needs. This guide shows how to deploy Rocket.Chat and archive microservices using Kubernetes and Helm, our officially supported method.


To use Helm for deploying microservices, here are certain prerequisites that need to be met:

  • A Kubernetes cluster is set up and configured.

  • A working installation of Helm 3.

  • Basic understanding of Kubernetes and Helm.

To deploy Rocket.Chat and archive microservices using Kubernetes and Helm,

  • Add the RocketChat helm repository to your system by running the following command:

helm repo add rocketchat https://rocketchat.github.io/helm-charts
  • Configure the Rocket.Chat deployment. By default, the Rocket.Chat Helm chart deploys a single monolith with a single instance. To enable microservices, edit your values.yaml file and include these commands:

  enabled: true

Each component has its section inside the values.yml file. The top level is for the monolith configuration.

presence: {}
ddpStreamer: {}
account: {}
authorization: {}
streamHub: {}

To set the desired number of replicas for any of the services, set the replicas value for the respective service.

  replicas: 2

ddp-streamer should be scaled from the beginning. Aim for one pod for every 500 concurrent users.

For monolith replicas, set the top-level replicaCount value.

replicaCount: 2

stream-hub is the only service/component that can not be scaled and is limited to one pod for each deployment.

You can find other deployment variables in Deploy with Kubernetes.

  • Set up ingress. This architecture requires an ingress controller. All WebSocket connections needs to be sent directly to the ddp-streamerservice as mentioned earlier. For example, install an nginx controller in your cluster following this guide, then edit the values.yml file and add the following values:

host: # the host to access your rocket.chat instance from, omit the protocol
  enabled: true
  ingressClassName: nginx

This adds the necessary ingress resource with all the expected paths and backends configured. The ingressClassName is essential unless you have a default class set; depending on the type of controller you're using, refer to the respective documentation.

Nginx controller is used as an example and not an official recommendation. Any ingress controller can be used, with the ingressClassName property set correctly or the IngressClass resource set to the default one for the cluster or the controller watches for Ingress resources with no specific class defined.

  • Apply the changes and install. Once you have made the necessary changes to the values file, run the following command to upgrade the deployment:

helm install rocketchat -f values.yaml rocketchat/rocketchat
  • Once deployed, you should be able to access the Rocket.Chat using the configured host. You can convert your existing monolith deployment to using microservices by making the same changes mentioned in this document and running helm upgrade with the values file and the current deployment name instead of helm install.

A complete guide on how to deploy with helm can be found in Deploy with Kubernetes. For multi-workspace deployment, please contact support.

Additionally, you can refer to this recording that explains how to deploy Rocket.Chat with microservices in a test environment.

Last updated

Rocket.Chat versions receive support for six months after release.