This guide walks you through deploying Rocket.Chat on Kubernetes using the Helm package manager. The official Rocket.Chat helm chart provisions a complete installation and provides strong support for scaling and high availability.
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
Domain name: Your domain name must be configured to point to your server’s external IP address.
Kubernetes cluster: A running Kubernetes cluster.
Helm v3: Helm version 3 must be installed on your server.
Firewall configuration: Verify that your firewall rules allow HTTPS traffic. If you're using a firewall, you may need to whitelist certain URLs to communicate with our cloud services. See the Firewall Configuration guide for a complete list.
Kubernetes resource requirements
The following Kubernetes resources must be available or configured in your cluster before deployment.
The examples provided here are intended as a guide. Your implementation may vary based on your enviroment and Kubernetes configuration.
Storage Class: A Storage Class is required to provision Persistent Volumes (PVs). If your cluster doesn't have one, you'll need to create it.
Ingress Controller: An Ingress Controller is essential for routing external traffic to your Rocket.Chat services. In this guide, we’ll use nginx as an example. Install Ingress-Nginx controller by running:
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-v1.8.2/deploy/static/provider/cloud/deploy.yaml
Confirm that the
ingress-nginx-controller
service has an external IP address by running:kubectl get svc -n ingress-nginx
Certificate manager and ClusterIssuer: If you don’t already have a valid TLS certificate for your domain, configure one using
cert-manager
and aClusterIssuer
.Cert manager: To facilitate TLS certificate management, install cert-manager by running:
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
Confirm the resources are created by running:
kubectl get all -n cert-manager
ClusterIssuer: cert-manager requires a ClusterIssuer to automatically issue TLS certificates across the cluster. In this guide, we’ll use Let’s Encrypt. Save the following to a file named
clusterissuer.yaml
:apiVersion: cert-manager.io/v1 kind: ClusterIssuer metadata: labels: app.kubernetes.io/instance: use1-cert-manager name: production-cert-issuer # Set your preferred name; referenced in values.yaml later spec: acme: server: https://acme-v02.api.letsencrypt.org/directory email: [email protected] # Replace with your email privateKeySecretRef: name: cert-manager-secret-production # Set your preferred name solvers: - http01: ingress: class: nginx
Create the resource by running:
kubectl apply -f clusterissuer.yaml
Verify the ClusterIssuer was deployed and the secret was created succesfully:
kubectl get clusterissuer kubectl get secret -n cert-manager
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 these cases, you can do either of the following:
Disable the bundled MongoDB chart and connect to an external MongoDB instance
Install a storage provisioner that is compatible with your environment
Once you've confirmed that all prerequisites are met, continue with the next steps to deploy a Rocket.Chat workspace using Kubernetes.
Step 1: Add the Helm chart repository
Add the Rocket.Chat helm chart repository by running:
helm repo add rocketchat https://rocketchat.github.io/helm-charts
If successful, you'll see a confirmation message stating that "rocketchat" has been added to your repositories.
Step 2: Define Rocket.Chat configurations
Create a values.yaml
file to define your deployment configurations. This file specifies how Helm should configure your Rocket.Chat instance. Below is an example configuration to use for your deployment:
image:
pullPolicy: IfNotPresent
repository: registry.rocket.chat/rocketchat/rocket.chat
tag: <release> # Set the Rocket.Chat release
mongodb:
enabled: true
auth:
passwords:
- rocketchat
rootPassword: rocketchatroot
microservices:
enabled: true # Enable microservices
replicaCount: 1
host: domain.xyz # Replace with your Rocket.Chat domain
ingress:
enabled: true
ingressClassName: nginx # Specify the installed ingress controller in the K8s cluster
annotations:
cert-manager.io/cluster-issuer: production-cert-issuer # Replace with your ClusterIssuer name
tls:
- secretName: rckube # Use a different name if preferred
hosts:
- domain.xyz # Replace with your Rocket.Chat domain
Replace
<release>
with the Rocket.Chat version you want to deploy.Update
domain.xyz
with your actual domain name.Set the
ingressClassName
to the ingress controller you are using.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, theannotations
andtls
values can be omitted.Explore additional deployment configuration options you can set in your
values.yaml
file to suit your workspace requirements.For production environments, it's crucial to deploy MongoDB (non-containerized) separately and configure it as a replica set for high availability.
While microservices is enabled in this configuration, it uses a single replica which is suitable for Community workspaces. To scale your workspace with multiple replicas, see our Microservices documentation.
Step 3: Configure monitoring
The next step is to set up a basic monitoring dashboard using Grafana. Create a separate file named values-monitoring.yaml
and add the following configuration:
ingress:
enabled: true
ingressClassName: "nginx" # Specify the installed ingress controller in the K8s cluster
tls: true
grafana:
enabled: true
host: "domain.xyz"
path: "/grafana"
Update
domain.xyz
with your actual domain name.Set the
ingressClassName
to the ingress controller you are using.
Step 4: Install Rocket.Chat and monitoring
First, install the monitoring stack with Helm:
helm install monitoring -f values-monitoring.yaml rocketchat/monitoring
A successful output should look like this:
Next, install Rocket.Chat with the configurations you defined in
values.yaml
:helm install rocketchat -f values.yaml rocketchat/rocketchat
If your deployment is successful, you’ll get a response similar to the following:
Verify that the pods for your deployment are running:
kubectl get pods
You should see a list of pods in the
Running
state, similar to the example below:Your output may vary depending on your configuration.
Step 5: Access your Rocket.Chat workspace
After a few minutes, your Rocket.Chat workspace will be accessible at the domain you configured (e.g., 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 (e.g., https://domain.xyz/grafana
). To log in, use the following default credentials:
User:
admin
Password:
admin
You’ll be prompted to set a new password after your first login.
Step 6: Update file storage
Rocket.Chat stores file uploads using GridFS by default. While this doesn't require extra setup, it's not ideal for production because it increases database load and reduces scalability performance. Rocket.Chat highly recommends using 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
Congratulations! You have successfully deployed your Rocket.Chat workspace on Kubernetes. Your workspace is now live and ready to use. Next, check out the following resources to continue using your workspace:
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.
Updating Rocket.Chat on Kubernetes
To update your Rocket.Chat workspace to a new version, update the image tag
field in your values.yaml
file with the desired release. For details about available Rocket.Chat versions, refer to the Rocket.Chat releases.
image:
tag: 7.0.0
After updating the file, execute the following command:
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat
For more information on updating Rocket.Chat, refer to this issue. Whenever you update your
values.yaml
file, always run thehelm upgrade
command above to apply the changes to your workspace.
Additional steps
Logging your deployment
To verify that the pods for your deployment are running, execute:
kubectl get pods
To view the logs for a specific Rocket.Chat pod, use:
kubectl logs <pod-name>
To stream real-time logs from a running Rocket.Chat pod:
kubectl logs -f <pod-name>
This helps in tracking ongoing events and debugging issues as they occur.
To view the Rocket.Chat logs:
kubectl logs -l app.kubernetes.io/name=rocketchat
Uninstalling Rocket.Chat on Kubernetes
To uninstall and delete the Rocket.Chat deployment, use the command:
helm delete rocketchat
You said
Set Rocket.Chat deployment environment variable on Kubernetes
Enviroment variables define key settings that influence or control how your workspace is deployed and configured. To set an environment variable in Kubernetes,
Open your
values.yaml
file:nano values.yaml
Add the environment variable under
extraEnv
. For example, to override the SMTP Host setting, add:extraEnv: - name: OVERWRITE_SETTING_SMTP_Host value: "my.smtp.server.com"
Finally, upgrade your deployment to apply the new changes:
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat
For a full list of available environment variables, refer to Deployment Environment Variables.
To further explore and enhance your workspace on Kubernetes, consider the following next steps: