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

This section details the prerequisites for deploying Rocket.Chat with Kubernetes, including recommendations and examples to guide you. Note that if you use a firewall, you may need to whitelist some URLs to communicate with our cloud services. See Firewall Configuration for the complete list.

Server requirements

Domain name: Confirm that your domain name points to your server's IP address.
Kubernetes cluster: Ensure your Kubernetes cluster is up and running.
Helm v3: Install Helm v3 if not already installed.
Firewall configuration: Verify that your firewall rules allow HTTPS traffic.

Kubernetes resource requirements

The following Kubernetes resources must be deployed on your server:

The examples provided are intended as a guide. Your implementation may vary based on your specific requirements and Kubernetes configuration.

Storage Class: Use an existing storage class in your Kubernetes cluster, or set up a new one depending on your cluster configuration.
Ingress Controller: This deployment requires an ingress controller. 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 with a LoadBalancer type has an external IP address by running:
```
kubectl get svc -n ingress-nginx
```

Certificate manager and ClusterIssuer: If you’re not using a domain with a valid TLS certificate, you may need to set up one to use HTTPS.

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
```
Check the created resources in the cert-manager namespace with:
```
kubectl get all -n cert-manager
```

ClusterIssuer: cert-manager requires a ClusterIssuer to automatically issue TLS certificates across the cluster. Below is an example configuration for setting up Let's Encrypt in a clusterissuer.yaml file:

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  labels:
    app.kubernetes.io/instance: use1-cert-manager
  name: production-cert-issuer  # Customize as needed; 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 # Customize as needed
    solvers:
    - http01:
        ingress:
          class: nginx

Create this resource by running the following command:

kubectl apply -f clusterissuer.yaml

Confirm that the ClusterIssuer was properly deployed and that the secret was successfully created by running:

kubectl get clusterissuer
kubectl get secret -n cert-manager

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

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

Step 2: Define deployment configurations

To install Rocket.Chat using the chart, define your configuration options in a values.yaml file. 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: false  # Set to false for a monolithic deployment
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 release tag you intend 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.
For production deployments, it's recommended to use a non-containerized MongoDB setup configured as a replica set.
Explore additional deployment configuration options you can set in your values.yaml file to suit your workspace requirements.

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.

Step 3: Install Rocket.Chat

With your configurations defined in values.yaml, proceed with the Rocket.Chat installation by running:
```
helm install rocketchat -f values.yaml rocketchat/rocketchat
```
A successful deployment will return output confirming that Rocket.Chat has been installed.
After a few minutes, you can now access your workspace at the domain where Rocket.Chat was deployed and complete the setup wizard.

Congratulations! You have successfully deployed your Rocket.Chat workspace on Kubernetes. Your workspace is now live and ready to use. Enjoy your new Rocket.Chat workspace! Next, check out the following documents to get started:

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.

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 logs for all pods running Rocket.Chat:

kubectl logs -l app.kubernetes.io/name=rocketchat

Debugging with logs

Check for MongoDB connection issues by running:

kubectl logs <pod-name> | grep "Mongo"

You can also identify authentication failures by using:

kubectl logs <pod-name> | grep "error"

Updating Rocket.Chat on Kubernetes

To update your Rocket.Chat workspace to a new version, update the tag field in your values.yaml file with the desired release tag. 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, run the helm upgrade command above to apply the changes to your workspace.

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 are additional settings that impacts your workspace deployment and configuration. 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: