Deploy with Kubernetes

This documentation guides you through deploying Rocket.Chat on Kubernetes using the Helm package manager. The official Rocket.Chat helm chart bootstraps the deployment process by provisioning a fully featured Rocket.Chat installation. It also provides strong support for scaling Rocket.Chat to accommodate growing server capacity needs and ensure high availability.

Prerequisites

• A domain name. Ensure your domain name is pointing to your server IP address.

• A Kubernetes cluster up and running

• Helm3 must be installed

• Your firewall rules must allow HTTPS traffic

• The following Kubernetes resources must be deployed on your server:

  • Storage class

  • Ingress controller

  • Certificate controller

  • ClusterIssuer

  • Persistent volume

The Rocket.Chat chart has an optional dependency on the MongoDB chart. By default, the MongoDB chart requires persistent volume support on underlying infrastructure, which may be disabled.

Deploying Rocket.Chat with Kubernetes using Helm

Once you've confirmed that all prerequisites are met, continue with the following steps to deploy a Rocket.Chat workspace using Kubernetes:

1. Add the chart repository

Add the Rocket.Chat helm chart repository by running the following command:

helm repo add rocketchat https://rocketchat.github.io/helm-charts

If successful, it returns a response that "rocketchat" has been added to your repositories.

2. Define the deployment configurations

To install the Rocket.Chat with the chart, you can either define your configuration options in a values file or pass the configuration parameters via command line arguments.

We recommend defining the configuration parameters inside a values.yaml file with at least the non-root user's password and the root password before passing it to Helm. You must set at least the database and root password in the values file.

Kindly refer to the configuration section to learn more about the deployment configurations you can set in your values.yaml file. However, let’s create an example file to proceed with this guide:

• Create values.yaml file with the following content to define the configurations that Helm will use for your deployment:

image:
  pullPolicy: IfNotPresent
  repository: registry.rocket.chat/rocketchat/rocket.chat
  tag: <release>

mongodb:
  enabled: true  #For test purposes, a single mongodb pod is deployed, consider an external MongoDB cluster for production environments
  auth:
    passwords:
      - rocketchat
    rootPassword: rocketchatroot

microservices:
  enabled: false  #This must be set to false for a monolithic deployment
host: domain.xyz 
ingress:
  enabled: true
  ingressClassName: nginx  # State the ingress controller that is installed in the K8s cluster 
  annotations:
    cert-manager.io/cluster-issuer: production-cert-issuer # Replace with the name of your ClusterIssuer 
  tls:
    - secretName: rckube #This is the name of the secret - You can use a different name if needed 
      hosts:
        - domain.xyz #This is the domain for your Rocket.Chat server, Replace it with your own domain 

• Replace the <release> with the Rocket.Chat release tag you want to deploy.

• Update domain.xyz with your domain name

• Optionally, you can use a different secretName for tls.

• Ensure that the appropriate ingressclassName and cluster issuer are specified.

It’s important to note that microservices is disabled in this deployment. To use microservices, visit our microservices documentation for more details. Additionally, you can refer to this recording that explains how to deploy Rocket.Chat with microservices in a test environment.

3. Install Rocket.Chat

Now that you’ve defined the configurations in values.yaml, install Rocket.Chat with the following command:

helm install rocketchat -f values.yaml rocketchat/rocketchat

If your deployment is successful, you’ll get a response similar to the following:

You can now access your workspace via the URL where Rocket.Chat was deployed (your domain), and complete the setup wizard.

[Alternative] Set the configuration parameters via command line arguments

Optionally, you can use the --set flag to pass the configuration parameters to Helm.

helm install rocketchat rocketchat/rocketchat --set mongodb.auth.passwords={$(echo -n $(openssl rand -base64 32))},mongodb.auth.rootPassword=$(echo -n $(openssl rand -base64 32))

Starting from chart version 5.4.3, username, password, and database entries must be arrays of the same length due to MongoDB dependency. Rocket.Chat will use the first entries of those arrays for its own use. mongodb.auth.usernames array defaults to {rocketchat} and mongodb.auth.databases array defaults to {rocketchat}.

Updating Rocket.Chat on Kubernetes

To update your Rocket.Chat workspace, update the image tag in the values.yaml file with the release tag of your desired version and execute the following command:

helm upgrade rocketchat -f values.yaml rocketchat/rocketchat

Kindly refer to this issue for more details.

Uninstalling the chart

To uninstall/delete the rocketchat deployment:

helm delete rocketchat

Configuration

The following table lists the configurable parameters of the Rocket.Chat chart and their default values.

Specify each parameter using the --set key=value[,key=value] argument to helm install. Alternatively, you can update the YAML file that specifies the values for the parameters to be provided while installing the chart.

You can also refer to the GitHub repository to explore all the available configuration options.

Database setup

Rocket.Chat uses a MongoDB instance to presist its data. By default, the MongoDB chart is deployed, and a single MongoDB instance is created as the primary in a replicaset. Please refer to this chart for additional MongoDB configuration options. If you are using chart defaults, set the mongodb.auth.rootPassword and mongodb.auth.passwords.

Using an external database

This chart supports using an existing MongoDB instance. Use the configuration options and disable the chart's MongoDB with --set mongodb.enabled=false

Configuring additional environment variables

extraEnv: |
  - name: MONGO_OPTIONS
    value: '{"ssl": "true"}'

Specifying additional volumes

Sometimes, it's necessary to include extra sets of files by means of exposing them to the container as a mountpoint. The most common use case is the inclusion of SSL CA certificates.

extraVolumes: 
  - name: etc-certs
    hostPath:
    - path: /etc/ssl/certs
      type: Directory
extraVolumeMounts: 
  - mountPath: /etc/ssl/certs
    name: etc-certs   
    readOnly: true

Increasing server capacity and HA setup

To increase the server's capacity, you can increase the number of Rocket.Chat server instances across available computing resources in your cluster. For example,

kubectl scale --replicas=3 deployment/rocketchat

By default, the chart creates one MongoDB instance as a Primary in a replicaset. You can also scale up the capacity and availability of the MongoDB cluster independently.

See MongoDB chart for configuration information. To learn more on running Rocket.Chat in scaled configurations, visit the configure MongoDB replicaset guide.

Manage MongoDB secrets

The chart provides several ways to manage the connection for MongoDB apart from the primary mongodb.auth values. They include:

• Values passed to the chart (externalMongodbUrl, externalMongodbOplogUrl)

• An ExistingMongodbSecret containing the MongoURL and MongoOplogURL

apiVersion: v1
kind: Secret
metadata:
  name: my-secret
type: Opaque
data:
  mongo-uri: mongodb://user:password@localhost:27017/rocketchat
  mongo-oplog-uri: mongodb://user:password@localhost:27017/local?replicaSet=rs0&authSource=admin

Upgrading

To 5.4.3

Due to changes on the upstream MongoDB chart, some deprecated variables have been renamed, which changed how this chart generates its manifests. Here are the values that need updates:

• mongodb.auth.username is no longer supported and has been changed to mongodb.auth.usernames array. If you set it to something custom (defaults to rocketchat), make sure you update it to an array, and the entry is the first entry in that array, as that's what Rocket.Chat will use to connect to the database.

• mongodb.auth.password is no longer supported and has been changed to mongodb.auth.passwords array. Update your values file to make it an array, and ensure it's the first entry of that array.

• mongodb.auth.database is no longer supported and has been changed to mongodb.auth.databases. Update your values file, convert it to an array, and ensure it's the first entry of that array.

• mongodb.auth.rootUsername and mongodb.auth.rootPassword remain the same.

usernames, passwords and databases arrays must be of the same length. Rocket.Chat chart will use the first entry for its mongodb connection string in MONGO_URL and MONGO_OPLOG_URL.

The used image tag gets updated in most cases on each chart update. The same is true for the MongoDB chart we use as our dependency. Before version 5.4.3, we used the chart version 10.x.x. Starting from 5.4.3, the dependency chart version has been updated to the latest available version, 13.x.x. This chart defaults to MongoDB 6.0.x at the moment.

As a warning, this chart will not handle MongoDB upgrades and will depend on the user to ensure the supprted version is runnning.

The upgrade will fail if any of the following requirements are not met :

• Must not skip a MongoDB release. For example, 4.2.x to 5.0.x will fail.

• Current featureCompatibilityVersion must be compatible with the version the user is trying to upgrade to. For example—if the current database version and feature compatibility is 4.4 and 4.2, respectively, but the user is trying to upgrade to 5.0, it'll fail.

The chart will not check if the mongodb version is supported by the Rocket.Chat version considering deployments that might occur in an airgapped environment. You can check the release notes to confirm that.

To get the currently deployed MongoDB version, the easiest method is to get into the mongo shell and run db.version(). You are advised to pin your MongoDB dependency in the values file.

mongodb:
  image:
    tag: # find from https://hub.docker.com/r/bitnami/mongodb/tags

To learn more about the Rocket.Chat helm chart, visit the GitHub repository.

References

• Run a shell inside a container (to check mongodb version)

• MongoDB upgrade official documentation

• MongoDB helm chart options