Deploy Rocket.Chat with Kubernetes Guide

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 a ClusterIssuer.

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: user01@mycompany.com   # 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, the annotations and tls 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 the helm 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

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:

Deploy with Kubernetes