Deploy a Federated Rocket.Chat Workspace with Kubernetes

To configure a Matrix bridge that allows Rocket.Chat users to engage in federated rooms and communicate with federated users, a homeserver is required. Homeservers are key components that host user accounts and other data related to communication. It also facilitates communication between users on different servers by relaying messages through a network of matrix servers until they reach the destination. Rocket.Chat listens to events happening in the homeserver and sends events relayed to other networks. For further details, explore the Rocket.Chat and Matrix architecture.

This documentation details the deployment of a federated Rocket.Chat workspace with Kubernetes using Helm.

Before you proceed, consult the official guide for deploying a basic Rocket.Chat workspace with Kubernetes to gain a foundational understanding of the Kubernetes procedure.

Prerequisites

This section details the prerequisites for deploying a federated workspace with Kubernetes, including recommendations and examples to guide you.

Server requirements

  1. Kubernetes cluster: Ensure your Kubernetes cluster is up and running.

  2. Helm v3: Install Helm v3 if not already installed.

  3. Firewall configuration: Verify that your firewall rules allow HTTPS traffic.

  4. Two domains: Confirm that the domains point to your server's IP address. For example,

    1. domain.xyz - The domain for your Rocket.Chat workspace.

    2. synapse.domain.xyz - The domain for your Synapse server. Note that you need the Synapse version 1.8.x and above.

Kubernetes resources requirement

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.

  1. Storage Class: Use an existing storage class in your Kubernetes cluster, or set up a new one depending on your cluster configuration.

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

  3. 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  federated 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 deploying a federated workspace: 

image:
 pullPolicy: IfNotPresent
 repository: registry.rocket.chat/rocketchat/rocket.chat
 tag: <release> #Set the Rocket.Chat release

mongodb:
 enabled: true  #For test purposes, a single mongodb pod is deployed, consider an external MongoDB cluster for production environments
 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: federation #Use a different name if preferred
     hosts:
       - domain.xyz #Replace with your Rocket.Chat domain
       - synapse.domain.xyz #Replace with your Synapse server domain 

federation:
 enabled: true
 host: synapse.domain.xyz #Replace with your Synapse server domain 
 persistence:
   enabled: true

postgresql:
 enabled: true

  1. Replace <release> with the Rocket.Chat release tag you intend to deploy.

  2. Update domain.xyz with your actual domain name.

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

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

The values.yaml file contents provided here serve as examples for your reference. Your implementation may vary according to your specific requirements. To scale your workspace with microservices, visit the Microservices documentation.

Step 3: Install Rocket.Chat and Synapse

  1. With your configurations defined in values.yaml, proceed with the Rocket.Chat installation by running:

helm install rocketchat -f values.yaml rocketchat/rocketchat

If your deployment is successful, you’ll get a response similar to the following:

After a few minutes, verify that the corresponding certificates, secrets, and pods have been successfully created with the kubectl get pods command. The response is similar to the image below, depending on your configurations:

You can now access your workspace at the domain where Rocket.Chat was deployed and complete the setup wizard.

Step 4: Verify your federation connection status

After deploying your workspace, it's essential to validate your federation configuration to confirm it's functioning properly before creating federated rooms. To verify the configuration:

  1. Go to Administration > Workspace > Settings > Federation > Matrix Bridge.

  2. Click Verify Configuration to check the status of the federation connection.

The Configuration Status field is updated to show the current federation connection status. If the status is Valid, you can proceed to test federation within the workspace.

Congratulations! You have successfully deployed and set up your federated Rocket.Chat workspace on Kubernetes. Your workspace is now live and ready to use. Refer to the next section to conduct a basic test on your workspace or access the user guide to begin using your workspace.

Step 5: Test the federated workspace

To test the federation, send a direct message to any user on a matrix-compatible server. You can DM a user on another federated Rocket.Chat workspace or Element.

To send a DM to a user on Element:

  • Create a user account on Element.

  • Create a 1:1 Direct Message on your Rocket.Chat workspace. Add the Element user as a member of the DM using this syntax: @username:matrix.org. Then, send a message.

  • You receive an invite notification on Element from a user in your Rocket.Chat workspace who wants to send a message. Accept the invite and continue the conversation.

To send a DM to a user on another federated Rocket.Chat workspace:

  • Deploy another federated workspace with the steps highlighted above.

  • Create a 1:1 Direct Message on your Rocket.Chat workspace. Add a user from the second federated workspace as a member of the DM using this syntax: @username:server. For example, @test_user:your_workspace_domain.

  • Then, send a message to the user. The user receives the message, and you can continue exchanging conversations.

Refer to Create federated rooms to learn more about sending messages to federated users.

Now that your federated workspace is ready, you can:

  • Go to the Federation User Guide to learn how to invite external users on the Matrix protocol to your workspace, join other channels on the Matrix network, etc.

  • Allow or block specific IP addresses to communicate with your workspace.