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:
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.
After your external MongoDB is ready, configure the monitoring stack. This enables observability in your workspace and ensures you can monitor your deployment effectively.
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
Your domain name must point to your server’s external IP address.
You need a live Kubernetes cluster with kubectl v1.21 or higher configured.
Helm version 3 must be installed on your server.
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.
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 storageclassCopy 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.
Ingress Controller: An Ingress Controller is essential for routing external traffic to your Rocket.Chat services. This guide uses Traefik as an example.
Add the official Traefik Helm repository:
helm repo add traefik https://traefik.github.io/charts helm repo updateInstall Traefik:
helm install traefik traefik/traefik \ --namespace traefik \ --create-namespaceConfirm that the service has an external IP address by running:
kubectl get svc -n traefik
TLS certificate manager: If you don't have a valid TLS certificate, install
cert-managerto automate certificate management via Let's Encrypt.Install cert-manager by running:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yamlConfirm the resources are created:
kubectl get all -n cert-manager
ClusterIssuer: cert-manager requires a ClusterIssuer to automatically issue TLS certificates across the cluster. This guide uses Let’s Encrypt.
Create a
clusterissuer.yamlfile 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: traefikReplace
user01@mycompany.comwith your email address and setprivateKeySecretRef.nameto your preferred name.Create the resource:
kubectl apply -f clusterissuer.yamlVerify 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 updateHelm 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.
Create a namespace:
kubectl create namespace rocketchatThis guide uses "rocketchat" as the namespace. You can change the namespace, but ensure you use the chosen name in subsequent steps.
Install the MongoDB operator:
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \ -n rocketchatDo not install CRDs separately. The operator chart manages them automatically.
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.
Create
mongodb-secrets.yamlwith 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>.Apply the secrets:
kubectl apply -f mongodb-secrets.yamlCreate
mongodb-community.yamlfile. 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 requiredReplace
<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 requiredReplace
<your-storage-class>with your actual StorageClass name.Update the value of
spec.membersto the desired number of replica set members. Replace the existing number as needed.Update the value of
limits.memoryandrequests.memoryas required for your workspace.
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.
Wait for the MongoDB pods to become ready:
kubectl wait --for=condition=ready pod -l app=mongodb-svc \ -n rocketchat \ --timeout=300sConfirm the pod status:
kubectl get pods -n rocketchat | grep mongodbVerify 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.
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.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.
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=mongodbSave 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.
Create a file named
values-monitoring.yamland 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"Replace
domain.xyzwith your actual domain name.Set
ingressClassNameto match the ingress controller deployed in your Kubernetes cluster.
Install the monitoring stack:
helm install monitoring -f values-monitoring.yaml rocketchat/monitoring -n rocketchatHelm 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.
Create a
values.yamlfile 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.yamlfile: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-clusterReplace
<release>with the Rocket.Chat version you want to deploy.Connect the external MongoDB by replacing
<enter-external-mongodb-uri>with the connection string you saved in step 4.Update
<domain.xyz>with your actual domain name.Set the
ingressClassNameto the ingress controller you are using.If you’ve configured a certificate manager and ClusterIssuer for TLS, specify your ClusterIssuer name and a
secretNamefor TLS. If you already have a valid certificate or do not wish to use TLS, theannotationsandtlsvalues can be omitted.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.
Install Rocket.Chat with the configurations you defined in
values.yaml:helm install rocketchat -f values.yaml rocketchat/rocketchat -n rocketchatHelm returns the release details with
STATUS: deployed.Wait for Rocket.Chat to be ready:
kubectl rollout status deployment/rocketchat-rocketchat \ -n rocketchat \ --timeout=300sVerify that the pods for your deployment are running:
kubectl get pods -n rocketchatEach pod shows
Runningin theSTATUScolumn. The pods listed depend on your configuration.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 RUNNINGblock 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:
adminPassword:
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 rocketchatHelm 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. |
|
| Rocket.Chat release to deploy. Set this to pin your workspace to a specific release. | Not set |
| Image pull policy. |
|
| Hostname for Rocket.Chat. The ingress also uses this value when it is enabled. | Not set |
| Number of Rocket.Chat replicas to run. |
|
| Minimum number or percentage of pods that must stay scheduled. |
|
| Creates a PodDisruptionBudget for the Rocket.Chat deployment. |
|
Database
Parameter | Description | Default |
|---|---|---|
| Deploys the bundled MongoDB chart. Set to |
|
| Connection string for an externally provisioned MongoDB. | Not set |
| Name of an existing secret that contains the MongoDB connection string. |
|
Microservices
Parameter | Description | Default |
|---|---|---|
| Runs Rocket.Chat as microservices. |
|
| Replicas for the presence service. |
|
| Replicas for the DDP streamer service. |
|
| Replicas for the account service. |
|
| Replicas for the authorization service. |
|
| Replicas for the NATS cluster that the microservices use to communicate. |
|
Ingress and service
Parameter | Description | Default |
|---|---|---|
| Creates an ingress when set to |
|
| Ingress class of the ingress controller in your cluster. | Not set |
| Path type for the ingress resource. |
|
| Annotations for the ingress, such as the cert-manager ClusterIssuer. |
|
| Path of the ingress. |
|
| List of IngressTLS items. |
|
| Kubernetes service type. |
|
| Service port. |
|
| Node port to use when | Not set |
| Annotations for the Rocket.Chat service. |
|
| Additional labels for the Rocket.Chat service. |
|
Scheduling and resources
Parameter | Description | Default |
|---|---|---|
| Pod resource requests and limits. | Not set |
| Controls whether Rocket.Chat replicas can run on the same node. |
|
| Topology key used when anti-affinity is enabled, for example |
|
| Custom affinity rules for the Rocket.Chat pods. |
|
| Additional labels for the Rocket.Chat pods. |
|
| Additional annotations for the Rocket.Chat pods. |
|
Storage
Parameter | Description | Default |
|---|---|---|
| Stores Rocket.Chat data on a persistent volume claim (PVC). You don't need this when you use the default GridFS file storage. |
|
| Storage class of the PVC. | Not set |
| Access mode of the PVC. |
|
| Size of the PVC. |
|
| Name of an existing PVC to use. | Not set |
| Extra volumes, for example to add certificates or other files. |
|
| Mount paths for |
|
Security
Parameter | Description | Default |
|---|---|---|
| User ID the pod runs as. See Upgrade to Helm chart 7.0.0. |
|
| File system group for the pod. |
|
| Creates a ServiceAccount. |
|
| Name of the ServiceAccount. If empty and |
|
Health checks
Parameter | Description | Default |
|---|---|---|
| Turns the liveness probe on or off. |
|
| Delay before the first liveness probe. |
|
| Interval between liveness probes. |
|
| Seconds before a liveness probe times out. |
|
| Consecutive failures before the probe fails. |
|
| Consecutive successes before the probe succeeds. |
|
| Turns the readiness probe on or off. |
|
| Delay before the first readiness probe. |
|
| Interval between readiness probes. |
|
| Seconds before a readiness probe times out. |
|
| Consecutive failures before the probe fails. |
|
| Consecutive successes before the probe succeeds. |
|
Metrics
Parameter | Description | Default |
|---|---|---|
| Exposes the |
|
| Port for Rocket.Chat metrics. |
|
| Port for microservices metrics. |
|
| Creates ServiceMonitor resources for the Prometheus Operator. Requires |
|
| Scrape intervals. |
|
| Port names that expose metrics. |
|
Email, license, and registration
Parameter | Description | Default |
|---|---|---|
| Sends email through SMTP. |
|
| SMTP account username. |
|
| SMTP account password. |
|
| SMTP server hostname. |
|
| SMTP server port. |
|
| Contents of your license file, if you have one. | Not set |
| Registration token for Rocket.Chat Cloud. | Not set |
For every available parameter, see the chart's
values.yamlfile on GitHub.
Set environment variables
Environment variables control how your workspace is deployed and configured. To set an environment variable on Kubernetes:
Open your
values.yamlfile:nano values.yamlAdd an
extraEnvsection 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"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:
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.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:
Update the
image.tagfield in thevalues.yamlfile to the desired release:image: tag: <release>Replace
<release>with your chosen Rocket.Chat release number. For available versions, see Rocket.Chat release notes.After you update the image, run this command to apply changes:
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchatThe
helm upgradecommand 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.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:
Check the release notes to verify that your target MongoDB version is supported by your current Rocket.Chat release.
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.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.
Confirm the database
featureCompatibilityVersionaligns 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:
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.Check the pods and wait for MongoDB to start running again:
kubectl get pods -n rocketchatConfirm 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:
The Rocket.Chat application version, which determines the version of Rocket.Chat running in your workspace.
The Helm chart version, which defines how Rocket.Chat is deployed and configured in your Kubernetes cluster.
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:
Identify the persistent volume claim (PVC) used by Rocket.Chat:
kubectl get pvc -n rocketchatScale down the Rocket.Chat deployment so no pod is actively using the volume:
kubectl scale deployment rocketchat-rocketchat --replicas=0 -n rocketchatRun 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=busyboxWith 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:
To check the pods in your deployment:
kubectl get pods -n rocketchatTo view the logs for a specific Rocket.Chat pod:
kubectl logs -n rocketchat <pod-name>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.
To check MongoDB replica set status:
kubectl exec -it mongodb-0 -n rocketchat -- \ mongosh admin --eval "rs.status()"Get the service details for the deployment:
kubectl get svc -n rocketchatTo 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 rocketchatThis 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 rocketchatPersistent volume claims created for MongoDB are not deleted automatically. Deleting them with
kubectl delete pvcpermanently removes your workspace data.