Deploy with Kubernetes

Prev Next

This guide shows you how to deploy Rocket.Chat on Kubernetes with Helm. The official Rocket.Chat Helm chart creates a workspace designed for scalability, resilience, and high availability.

The deployment separates Rocket.Chat from its database. You can manage your database layer independently of the application layer. It follows this approach:

  1. Provision an external MongoDB database. This guide covers deploying a database using the MongoDB Kubernetes operator. If you already have an external MongoDB instance or use a managed service like Atlas, skip to step 5.

  2. After your external MongoDB is ready, configure the monitoring stack. This enables observability in your workspace and ensures you can monitor your deployment effectively.

  3. Once the database and monitoring stack are healthy, proceed to deploy Rocket.Chat and connect it to your external MongoDB instance.

If you currently use the bundled setup with the internal MongoDB chart, refer to Moving from Bitnami to Official MongoDB Chart on the Rocket.Chat forum for migration guidance.

In this guide, you'll learn how to:

Prerequisites

This guide assumes you have a basic understanding of Kubernetes and Helm. Before you begin, verify you have the following server requirements and Kubernetes resources.

Server requirements

  1. Your domain name must point to your server’s external IP address.

  2. You need a live Kubernetes cluster with kubectl v1.21 or higher configured.

  3. Helm version 3 must be installed on your server.

  4. Check that your firewall allows HTTPS traffic.

Kubernetes resource requirements

Make sure the following Kubernetes resources are ready in your cluster before moving on with deployment.

The examples that follow are intended as a guide. Adjust your implementation as needed based on your environment and Kubernetes setup before advancing to subsequent steps.

  1. Storage Class: A StorageClass is required to provision Persistent Volumes (PVs). If your cluster doesn't have one, you'll need to create it. Run this command to check your storage class:

    kubectl get storageclass

    Copy the name of your StorageClass, you’ll need it to configure the database in subsequent steps.

    The Rocket.Chat Helm chart requires your Kubernetes cluster to support dynamic persistent volume (PV) provisioning. Local Kubernetes distributions such as Kind, K3s, and Minikube often ship without a storage provisioner enabled. In such cases, you can either connect to an external MongoDB instance or install a compatible local storage provisioner.

  2. Ingress Controller: An Ingress Controller is essential for routing external traffic to your Rocket.Chat services. This guide uses Traefik as an example.

    1. Add the official Traefik Helm repository:

      helm repo add traefik https://traefik.github.io/charts
      helm repo update
    2. Install Traefik:

      helm install traefik traefik/traefik \
        --namespace traefik \
        --create-namespace
    3. Confirm that the service has an external IP address by running:

      kubectl get svc -n traefik
  3. TLS certificate manager: If you don't have a valid TLS certificate, install cert-manager to automate certificate management via Let's Encrypt.

    1. Install cert-manager by running:

      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
    2. Confirm the resources are created:

      kubectl get all -n cert-manager
  4. ClusterIssuer: cert-manager requires a ClusterIssuer to automatically issue TLS certificates across the cluster. This guide uses Let’s Encrypt.

    1. Create a clusterissuer.yaml file and save the following content:

      apiVersion: cert-manager.io/v1
      kind: ClusterIssuer
      metadata:
        labels:
          app.kubernetes.io/instance: use1-cert-manager
        name: production-cert-issuer  # Set your preferred name
      spec:
        acme:
          server: https://acme-v02.api.letsencrypt.org/directory
          email: user01@mycompany.com   # Replace with your email
          privateKeySecretRef:
            name: cert-manager-secret-production # Set your preferred name
          solvers:
          - http01:
              ingress:
                class: traefik

      Replace user01@mycompany.com with your email address and set privateKeySecretRef.name to your preferred name.

    2. Create the resource:

      kubectl apply -f clusterissuer.yaml
    3. Verify the ClusterIssuer was deployed and the secret was created successfully:

      kubectl get clusterissuer
      kubectl get secret -n cert-manager

Step 1: Add the Helm chart repositories

Add the official Rocket.Chat and MongoDB Helm repositories:

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

Helm confirms that each repository was added.

Step 2: Install the MongoDB Kubernetes operator

With the required Kubernetes resources in place, the next step is to install the MongoDB Kubernetes operator to manage MongoDB lifecycle tasks like provisioning, scaling, and health checks.

  1. Create a namespace:

    kubectl create namespace rocketchat

    This guide uses "rocketchat" as the namespace. You can change the namespace, but ensure you use the chosen name in subsequent steps.

  2. Install the MongoDB operator:

    helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \
      -n rocketchat

    Do not install CRDs separately. The operator chart manages them automatically.

  3. Wait for the MongoDB operator to be ready:

    kubectl rollout status deployment/mongodb-kubernetes-operator \
      -n rocketchat \
      --timeout=300s

Step 3: Configure database secrets and replica set

Once the MongoDB operator is running, define the MongoDB resources to provision a replica set and configure authentication for Rocket.Chat.

  1. Create mongodb-secrets.yaml with the following MongoDB secrets for database administrators, application user, and the monitoring endpoints:

    ---
    apiVersion: v1
    kind: Secret
    metadata:
      namespace: rocketchat
      name:  mongodb-admin-password
    type: Opaque
    stringData:
      password: <your-secure-admin-password>
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      namespace: rocketchat
      name: mongodb-rocketchat-password
    type:  Opaque
    stringData:
      password: <your-secure-rocketchat-password>
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      namespace: rocketchat
      name: metrics-endpoint-password
    type:  Opaque
    stringData:
      password: <your-secure-prometheus-password>
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      namespace: rocketchat
      name: admin-scram-credentials
    type:  Opaque
    stringData: 
      username: admin
      password: <your-secure-admin-password>
    ---
    apiVersion: v1
    kind: Secret
    metadata:
      namespace: rocketchat
      name: rocketchat-scram-credentials
    type: Opaque
    stringData:
      username: rocketchat
      password: <your-secure-rocketchat-password>

    Replace these placeholder passwords with secure values: <your-secure-admin-password>, <your-secure-rocketchat-password>, <your-secure-prometheus-password> .

  2. Apply the secrets:

    kubectl apply -f mongodb-secrets.yaml
  3. Create mongodb-community.yaml file. Choose between a single node or multiple node ReplicaSet for MongoDB as needed:

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata: 
  name: mongodb
  namespace: rocketchat
spec:
  members:  1 
  type: ReplicaSet
  version: "8.0.0"
  security:
    authentication: 
      modes:  ["SCRAM"]
    tls:
      enabled: false
  users:
  - name:  admin
    db:  admin
    passwordSecretRef: 
      name: mongodb-admin-password
    scramCredentialsSecretName: admin-scram-credentials
    roles:
    - name: root
      db: admin
  - name: rocketchat
    db: rocketchat
    passwordSecretRef:
      name:  mongodb-rocketchat-password
    scramCredentialsSecretName: rocketchat-scram-credentials
    roles:
    - name: readWrite
      db: rocketchat
  prometheus:
    username:  prometheus-username
    passwordSecretRef:
      name: metrics-endpoint-password
  statefulSet:
    spec:
      volumeClaimTemplates:
      - metadata:
          name: data-volume
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: <your-storage-class>
          resources:
            requests:
              storage: 50Gi
      template:
        spec:
          containers:
          - name: mongod
            resources:
              limits:
                cpu:  1500m
                memory:  1Gi       #Configure the limits memory as required
              requests:
                cpu: 500m
                memory: 1Gi        #Configure the requests memory as required
  • Replace <your-storage-class> with your actual StorageClass name.

apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata: 
  name: mongodb
  namespace: rocketchat
spec:
  members:  3    #Set your desired number of replicaSet
  type: ReplicaSet
  version: "8.0.0"
  security:
    authentication: 
      modes:  ["SCRAM"]
    tls:
      enabled: false
  users:
  - name:  admin
    db:  admin
    passwordSecretRef: 
      name: mongodb-admin-password
    scramCredentialsSecretName: admin-scram-credentials
    roles:
    - name: root
      db: admin
  - name: rocketchat
    db: rocketchat
    passwordSecretRef:
      name:  mongodb-rocketchat-password
    scramCredentialsSecretName: rocketchat-scram-credentials
    roles:
    - name: readWrite
      db: rocketchat
  prometheus:
    username:  prometheus-username
    passwordSecretRef:
      name: metrics-endpoint-password
  statefulSet:
    spec:
      volumeClaimTemplates:
      - metadata:
          name: data-volume
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: <your-storage-class>
          resources:
            requests:
              storage: 50Gi
      template:
        spec:
          containers:
          - name: mongod
            resources:
              limits:
                cpu:  1500m
                memory:  6Gi       #Configure the limits memory as required
              requests:
                cpu: 500m
                memory: 3Gi        #Configure the requests memory as required
  • Replace <your-storage-class> with your actual StorageClass name.

  • Update the value of spec.members to the desired number of replica set members. Replace the existing number as needed.

  • Update the value of limits.memory  and requests.memory as required for your workspace.

  1. Apply the MongoDB resource:

    kubectl apply -f mongodb-community.yaml

Step 4: Verify the MongoDB deployment

After you deploy MongoDB, confirm that the database is healthy and reachable before you deploy Rocket.Chat.

  1. Wait for the MongoDB pods to become ready:

    kubectl wait --for=condition=ready pod -l app=mongodb-svc \
      -n rocketchat \
      --timeout=300s
  2. Confirm the pod status:

    kubectl get pods -n rocketchat | grep mongodb
  3. Verify the MongoDB service endpoints:

    kubectl get endpoints mongodb-svc -n rocketchat

You should see the MongoDB pod’s IP address listed. If no endpoints appear, the service selector may not match the pod labels correctly. Consult the Kubernetes Deployment FAQ for troubleshooting guidance.

Validate MongoDB health

Choose the setup that matches how you created  mongodb-community.yaml earlier to deploy MongoDB:

Run a ping against the admin database to confirm MongoDB is responding:

kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh admin --eval "db.adminCommand('ping')"

Expected output: { ok: 1 }. If you see an error, do not proceed until MongoDB is healthy.

  1. Verify that the primary database is healthy:

    kubectl exec -it mongodb-0 -n rocketchat -- \
      mongosh admin --eval "db.adminCommand('ping')"

    Expected output: { ok: 1 }. If you see an error, do not proceed until MongoDB is healthy.

  2. Check the status of all replica set members to confirm they are in sync:

    kubectl exec -it mongodb-0 -n rocketchat -- mongosh admin \
      -u admin \
      -p $(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d) \
      --eval "rs.status()"

Build the MongoDB connection string

Rocket.Chat requires a specific URI format to connect to the database.

  1. Extract the rocketchat user password and generate the MongoDB connection string:

    MONGO_PASSWORD=$(kubectl get secret mongodb-rocketchat-password \
      -n rocketchat -o jsonpath='{.data.password}' | base64 -d)
    echo "MongoDB URI:"
    echo "mongodb://rocketchat:${MONGO_PASSWORD}@mongodb-0.mongodb-svc.rocketchat.svc.cluster.local:27017/rocketchat?authSource=rocketchat&replicaSet=mongodb"

    The generated connection string will be in the following format:

    mongodb://rocketchat:testrc123@mongodb-0.mongodb-svc.rocketchat.svc.cluster.local:27017/rocketchat?authSource=rocketchat&replicaSet=mongodb
  2. Save the generated MongoDB connection string. You’ll need it later to connect Rocket.Chat to your database.

If you deployed a multi-node ReplicaSet for MongoDB, update the connection string to include all replica set members as comma-separated hosts before the database path. The number of hosts should match the number of members you configured in spec.members.

Step 5: Deploy the monitoring stack

The Rocket.Chat monitoring Helm chart deploys Prometheus to collect metrics, Loki to aggregate logs, and Grafana to display metrics and logs in dashboards.

  1. Create a file named values-monitoring.yaml and add the following configuration:

    ingress:
      enabled: true
      ingressClassName: "traefik" # Specify the installed ingress controller in the K8s cluster
      tls: true
      grafana:
        enabled: true
        host: "domain.xyz"
        path: "/grafana"
    1. Replace domain.xyz with your actual domain name.

    2. Set ingressClassName to match the ingress controller deployed in your Kubernetes cluster.

  2. Install the monitoring stack:

    helm install monitoring -f values-monitoring.yaml rocketchat/monitoring -n rocketchat

    Helm returns the release details with STATUS: deployed.

Step 6: Configure Rocket.Chat

With database and monitoring stack running, the next step is to define how Rocket.Chat should run in your cluster. These configuration values control image versions, ingress, TLS, and service behavior.

  1. Create a values.yaml file to define your deployment configurations. This file specifies how Helm should configure your Rocket.Chat workspace.

    Below is an example configuration to use for your values.yaml file:

    image:
      pullPolicy: IfNotPresent
      repository: registry.rocket.chat/rocketchat/rocket.chat
      tag: <release> # Set the Rocket.Chat release
    
    mongodb:
      enabled: false
    
    externalMongodbUrl: "<enter-external-mongodb-uri>"
    
    microservices:
      enabled: true
    replicaCount: 1
    
    host: <domain.xyz>
    
    ingress:
      enabled: true
      ingressClassName: traefik
      annotations:
        cert-manager.io/cluster-issuer: production-cert-issuer
      tls:
        - secretName: rckube
          hosts:
            - <domain.xyz>
    nats:
      cluster:
        name: rocketchat-nats-cluster
    1. Replace <release> with the Rocket.Chat version you want to deploy.

    2. Connect the external MongoDB by replacing <enter-external-mongodb-uri> with the connection string you saved in step 4.

    3. Update <domain.xyz> with your actual domain name.

    4. Set the ingressClassName to the ingress controller you are using.

    5. If you’ve configured a certificate manager and ClusterIssuer for TLS, specify your ClusterIssuer name and a secretName for TLS. If you already have a valid certificate or do not wish to use TLS, the annotations and tls values can be omitted.

    6. To set other options, see Configure your deployment.

This configuration enables microservices with a single replica, which suits Community workspaces. To scale your workspace with multiple replicas, see Scaling Rocket.Chat with Microservices.

Step 7: Deploy Rocket.Chat

After finalizing the configuration, launch the Rocket.Chat deployment.

  1. Install Rocket.Chat with the configurations you defined in values.yaml:

    helm install rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

    Helm returns the release details with STATUS: deployed.

  2. Wait for Rocket.Chat to be ready:

    kubectl rollout status deployment/rocketchat-rocketchat \
      -n rocketchat \
      --timeout=300s
  3. Verify that the pods for your deployment are running:

    kubectl get pods -n rocketchat

    Each pod shows Running in the STATUS column. The pods listed depend on your configuration.

  4. Check the Rocket.Chat logs to confirm that it started:

    kubectl logs deployment/rocketchat-rocketchat -n rocketchat | grep -A 15 "SERVER RUNNING"

    The output shows a SERVER RUNNING block that lists the Rocket.Chat version, the MongoDB version, and the site URL.

If you encounter any issues with your deployment, refer to the Kubernetes Deployment FAQ.

Step 8: Access your Rocket.Chat workspace

After a few minutes, your Rocket.Chat workspace will be accessible at the configured domain (for example, https://domain.xyz).

Follow the on-screen prompts to complete the initial setup and configuration of your workspace. During this process, your workspace and email will be registered to the Rocket.Chat Cloud portal, where you can manage your subscriptions.

Access monitoring dashboard

A Grafana dashboard will also be available at the path you configured (for example, https://domain.xyz/grafana). Log in with the following default credentials:

  • User: admin

  • Password: admin

You’ll be prompted to set a new password after your first login.

For more details on how to monitor your workspace metrics and logs, refer to the Monitor Workspace Logs and Metrics guide.

Step 9: Configure file storage

By default, Rocket.Chat uses GridFS for file uploads. While easy to set up, GridFS increases database load and does not scale well for production. For higher performance and scalability, use a dedicated object storage service such as Amazon S3, Google Cloud Storage (GCS), or MinIO. Refer to the File Uploads guide for detailed instructions on configuring your preferred file storage solution.

Next steps

To continue setting up your workspace, see these guides:

  • User Guides: Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users.

  • Workspace Administration: Administrators and owners can set and manage various configurations.

  • Marketplace: Explore the available apps to enhance your workspace.


Configure your deployment

The Rocket.Chat Helm chart reads its settings from your values.yaml file. To change a setting, add or update the parameter in values.yaml, then apply the change:

helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

Helm replaces the Rocket.Chat pods one at a time with a rolling update.

Helm chart parameters

The following tables list the parameters you are most likely to set. Defaults come from the chart's values.yaml file. A default of Not set means the key is absent or commented out in that file.

Image, host, and replicas

Parameter

Description

Default

image.repository

Image repository.

registry.rocket.chat/rocketchat/rocket.chat

image.tag

Rocket.Chat release to deploy. Set this to pin your workspace to a specific release.

Not set

image.pullPolicy

Image pull policy.

IfNotPresent

host

Hostname for Rocket.Chat. The ingress also uses this value when it is enabled.

Not set

replicaCount

Number of Rocket.Chat replicas to run.

1

minAvailable

Minimum number or percentage of pods that must stay scheduled.

1

podDisruptionBudget.enabled

Creates a PodDisruptionBudget for the Rocket.Chat deployment.

true

Database

Parameter

Description

Default

mongodb.enabled

Deploys the bundled MongoDB chart. Set to false when you connect to an external MongoDB, as this guide does.

true

externalMongodbUrl

Connection string for an externally provisioned MongoDB.

Not set

existingMongodbSecret

Name of an existing secret that contains the MongoDB connection string.

""

Microservices

Parameter

Description

Default

microservices.enabled

Runs Rocket.Chat as microservices.

true

microservices.presence.replicas

Replicas for the presence service.

1

microservices.ddpStreamer.replicas

Replicas for the DDP streamer service.

1

microservices.account.replicas

Replicas for the account service.

1

microservices.authorization.replicas

Replicas for the authorization service.

1

nats.cluster.replicas

Replicas for the NATS cluster that the microservices use to communicate.

2

Ingress and service

Parameter

Description

Default

ingress.enabled

Creates an ingress when set to true.

false

ingress.ingressClassName

Ingress class of the ingress controller in your cluster.

Not set

ingress.pathType

Path type for the ingress resource.

Prefix

ingress.annotations

Annotations for the ingress, such as the cert-manager ClusterIssuer.

{}

ingress.path

Path of the ingress.

/

ingress.tls

List of IngressTLS items.

[]

service.type

Kubernetes service type.

ClusterIP

service.port

Service port.

80

service.nodePort

Node port to use when service.type is NodePort.

Not set

service.annotations

Annotations for the Rocket.Chat service.

{}

service.labels

Additional labels for the Rocket.Chat service.

{}

Scheduling and resources

Parameter

Description

Default

resources

Pod resource requests and limits.

Not set

podAntiAffinity

Controls whether Rocket.Chat replicas can run on the same node. soft prefers separate nodes without guaranteeing it. hard requires separate nodes. An empty value disables anti-affinity.

""

podAntiAffinityTopologyKey

Topology key used when anti-affinity is enabled, for example topology.kubernetes.io/zone.

kubernetes.io/hostname

affinity

Custom affinity rules for the Rocket.Chat pods.

{}

podLabels

Additional labels for the Rocket.Chat pods.

{}

podAnnotations

Additional annotations for the Rocket.Chat pods.

{}

Storage

Parameter

Description

Default

persistence.enabled

Stores Rocket.Chat data on a persistent volume claim (PVC). You don't need this when you use the default GridFS file storage.

false

persistence.storageClass

Storage class of the PVC.

Not set

persistence.accessMode

Access mode of the PVC.

ReadWriteOnce

persistence.size

Size of the PVC.

8Gi

persistence.existingClaim

Name of an existing PVC to use.

Not set

extraVolumes

Extra volumes, for example to add certificates or other files.

[]

extraVolumeMounts

Mount paths for extraVolumes inside the container.

[]

Security

Parameter

Description

Default

securityContext.runAsUser

User ID the pod runs as. See Upgrade to Helm chart 7.0.0.

65533

securityContext.fsGroup

File system group for the pod.

65533

serviceAccount.create

Creates a ServiceAccount.

true

serviceAccount.name

Name of the ServiceAccount. If empty and serviceAccount.create is true, the chart generates a name.

""

Health checks

Parameter

Description

Default

livenessProbe.enabled

Turns the liveness probe on or off.

true

livenessProbe.initialDelaySeconds

Delay before the first liveness probe.

60

livenessProbe.periodSeconds

Interval between liveness probes.

15

livenessProbe.timeoutSeconds

Seconds before a liveness probe times out.

5

livenessProbe.failureThreshold

Consecutive failures before the probe fails.

3

livenessProbe.successThreshold

Consecutive successes before the probe succeeds.

1

readinessProbe.enabled

Turns the readiness probe on or off.

true

readinessProbe.initialDelaySeconds

Delay before the first readiness probe.

10

readinessProbe.periodSeconds

Interval between readiness probes.

15

readinessProbe.timeoutSeconds

Seconds before a readiness probe times out.

5

readinessProbe.failureThreshold

Consecutive failures before the probe fails.

3

readinessProbe.successThreshold

Consecutive successes before the probe succeeds.

1

Metrics

Parameter

Description

Default

prometheusScraping.enabled

Exposes the /metrics endpoint for Prometheus.

true

prometheusScraping.port

Port for Rocket.Chat metrics.

9100

prometheusScraping.msPort

Port for microservices metrics.

9458

serviceMonitor.enabled

Creates ServiceMonitor resources for the Prometheus Operator. Requires prometheusScraping.enabled.

false

serviceMonitor.intervals

Scrape intervals.

[30s]

serviceMonitor.ports

Port names that expose metrics.

[metrics]

Email, license, and registration

Parameter

Description

Default

smtp.enabled

Sends email through SMTP.

false

smtp.username

SMTP account username.

""

smtp.password

SMTP account password.

""

smtp.host

SMTP server hostname.

""

smtp.port

SMTP server port.

587

license

Contents of your license file, if you have one.

Not set

registrationToken

Registration token for Rocket.Chat Cloud.

Not set

For every available parameter, see the chart's values.yaml file on GitHub.

Set environment variables

Environment variables control how your workspace is deployed and configured. To set an environment variable on Kubernetes:

  1. Open your values.yaml file:

    nano values.yaml
  2. Add an extraEnv section and set the environment variable. For example, to override the SMTP Host setting, add:

    extraEnv:
     - name: OVERWRITE_SETTING_SMTP_Host
       value: "my.smtp.server.com"
  3. Upgrade your deployment to apply the new changes:

    helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

For a full list of available environment variables, refer to Deployment Environment Variables.

Scale your deployment

To run more than one replica of Rocket.Chat or of individual services, see Scaling Rocket.Chat with Microservices.

Scale MongoDB replicas

The MongoDB Kubernetes operator manages the replica set. To add or remove members, patch the MongoDBCommunity resource and the operator applies the change:

  1. Update the number of MongoDB members in the ReplicaSet with this command:

    kubectl patch mongodbcommunity mongodb -n rocketchat \
      --type='json' -p='[{"op": "replace", "path": "/spec/members", "value": <replica-set-number>}]'

    Replace <replica-set-number> with the number of replica set members you want.

  2. To verify, check the running pods for additional mongodb pods:

    kubectl get pods -n rocketchat

Update your deployment

Update Rocket.Chat

Before you proceed, consult the general guidelines for updating Rocket.Chat.

To update your workspace to a new Rocket.Chat release:

  1. Update the image.tag field in the values.yaml file to the desired release:

    image:
      tag: <release>

    Replace <release> with your chosen Rocket.Chat release number. For available versions, see Rocket.Chat release notes.

  2. After you update the image, run this command to apply changes:

    helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

    The helm upgrade command above does not pin a chart version, so it installs the latest Rocket.Chat Helm chart. Updating your app version may therefore also move you to a newer chart version automatically, which can include breaking changes. See Understand Helm chart versions.

  3. After a few minutes, return to your workspace subscription to verify the updated Rocket.Chat version.

If you are upgrading to Helm chart 7.0.0 and you have persistence.enabled: true, additional steps are required. Refer to Upgrade to Helm chart 7.0.0 for more details.

Update MongoDB

Before you change the MongoDB version, confirm the following:

  1. Check the release notes to verify that your target MongoDB version is supported by your current Rocket.Chat release.

  2. Ensure that the MongoDB image for the target version is available on Quay.io under mongodb-community-server. Look for an image tagged <target-version>-ubi8.

  3. Avoid skipping major versions. For example, to move from 4.4 to 6.0, you must upgrade to 5.0 first, ensure it is stable, and then proceed to 6.0.

  4. Confirm the database featureCompatibilityVersion aligns with the current major version. If you are running MongoDB 5.0 but your fCV is still set to 4.4, an upgrade to 6.0 will fail.

    To check your current featureCompatibilityVersion:

    kubectl exec -it mongodb-0 -n rocketchat -- \
      mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" --eval "db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1})"

To upgrade or downgrade MongoDB:

  1. Set the new MongoDB version:

    kubectl patch mongodbcommunity mongodb -n rocketchat \
      --type='json' -p='[{"op":  "replace", "path": "/spec/version", "value":"<mongodb-version>"}]'

    Replace <mongodb-version> with your target MongoDB version number.

  2. Check the pods and wait for MongoDB to start running again:

    kubectl get pods -n rocketchat
  3. Confirm the MongoDB version that is running:

    kubectl exec -it mongodb-0 -n rocketchat -- \
      mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" \
      --eval "db.version()"

Understand Helm chart versions

A Helm deployment of Rocket.Chat has two independently versioned components:

These versions change independently. A new Rocket.Chat release does not always mean a new chart version, and a chart update may ship without a corresponding application release. When you run helm upgrade, Helm automatically pulls the latest chart version available in the repository unless it is pinned to a specific version. New chart releases can include updates to deployment templates, configuration options, and default values. In major chart releases, these changes may require you to update your existing values.yaml file before updating your deployment.

To stay on a specific chart version, add --version to the command:

helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat --version <chart-version>

To list the available chart versions, run helm search repo rocketchat/rocketchat --versions.

Upgrade to Helm chart 7.0.0

Helm chart 7.0.0 changes the default user and group that Rocket.Chat runs as. The chart now uses UID 65533 instead of 999 to match the UID baked into the Rocket.Chat image at build time. This change also resolves the EACCES error that causes Apps Engine to fail in Rocket.Chat 8.5.0 and later.

If your deployment does not use persistent storage (persistence.enabled: false), no additional steps are required. Update your workspace following the usual steps.

If your deployment uses persistent storage (persistence.enabled: true), the existing volume data is likely owned by UID 999. After updating, the pod runs as UID 65533 and cannot access that data, which causes the pod to fail to start or apps to fail with permission errors.

To prevent this, update the ownership of the existing volume data to UID 65533:

  1. Identify the persistent volume claim (PVC) used by Rocket.Chat:

    kubectl get pvc -n rocketchat
  2. Scale down the Rocket.Chat deployment so no pod is actively using the volume:

    kubectl scale deployment rocketchat-rocketchat --replicas=0 -n rocketchat
  3. Run a temporary pod to update the volume ownership. Replace <pvc-name> with the PVC name from step 1:

    kubectl run chown-migration -n rocketchat --rm -it --restart=Never \
      --overrides='{"spec":{"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"<pvc-name>"}}],"containers":[{"name":"chown","image":"busybox","command":["chown","-R","65533:65533","/data"],"volumeMounts":[{"name":"data","mountPath":"/data"}]}]}}' \
      --image=busybox
  4. With ownership corrected, update the deployment:

    helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

Reverting to UID 999 is only safe on Rocket.Chat versions before 8.5.0. From 8.5.0 onward, Apps Engine requires write access to paths owned by UID 65533. On those versions, running the container as UID 999 stops apps from starting. On Rocket.Chat 8.5.0 or later, migrate the volume instead of overriding the UID.


Manage your deployment

Check status and logs

Use these commands to inspect your deployment:

  1. To check the pods in your deployment:

    kubectl get pods -n rocketchat
  2. To view the logs for a specific Rocket.Chat pod:

    kubectl logs -n rocketchat <pod-name>
  3. To stream real-time logs from a running Rocket.Chat pod:

    kubectl logs -n rocketchat -f <pod-name>

    This helps in tracking ongoing events and debugging issues as they occur.

  4. To check MongoDB replica set status:

    kubectl exec -it mongodb-0 -n rocketchat -- \
      mongosh admin --eval "rs.status()"
  5. Get the service details for the deployment:

    kubectl get svc -n rocketchat
  6. To check the current MongoDB version that is running:

    kubectl exec -it mongodb-0 -n rocketchat -- \
      mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" \
      --eval "db.version()"

If you encounter further issues with your deployment, refer to the Kubernetes Deployment FAQ.

Uninstall Rocket.Chat

To uninstall the Rocket.Chat release, run:

helm uninstall rocketchat -n rocketchat

This command removes only the Rocket.Chat release. The monitoring stack, the MongoDB operator, and the MongoDB resource remain in the rocketchat namespace. To remove them as well, run:

helm uninstall monitoring -n rocketchat
kubectl delete mongodbcommunity mongodb -n rocketchat
helm uninstall mongodb-kubernetes-operator -n rocketchat

Persistent volume claims created for MongoDB are not deleted automatically. Deleting them with kubectl delete pvc permanently removes your workspace data.