Skip to main content
Version: 0.6

Rocket.Chat installation

This tutorial shows the basic concepts of Capact on the Rocket.Chat installation example.


This instruction will guide you through the installation of Rocket.Chat on a Kubernetes cluster using Capact.

Rocket.Chat depends on the MongoDB database.

The diagram below shows the scenario:



NOTE: For AWS EKS Capact installation, all operation need to be run from the bastion host.

The following tools are required:

Install all Rocket.Chat components in a Kubernetes cluster

  1. Setup Capact CLI

  2. Make sure to separate workloads

    For a better performance and durability, it is recommended to run MongoDB and Rocket.Chat on separate nodes. MongoDB is by default configured to prefer being run on nodes with label We will also configure Rocket.Chat affinity to not schedule pods on such nodes.

    Select any worker node and replace the <NODE NAME> with the node name and run:

    kubectl label node <NODE NAME>
  3. Export Capact cluster domain name as environment variable:

    export CAPACT_DOMAIN_NAME={domain_name} # e.g.
  4. Create a file with installation parameters:

    cat > /tmp/rocketchat-params.yaml << ENDOFFILE
    host: chat.${CAPACT_DOMAIN_NAME}
  5. Create an Action:

    capact action create cap.interface.productivity.rocketchat.install \
    --name rocketchat \
    --parameters-from-file /tmp/rocketchat-params.yaml
  6. Get the status of the Action from the previous step:

    capact action get rocketchat

    Wait until the Action is in READY_TO_RUN state. It means that the Action was processed by the Engine, and the Interface was resolved to a specific Implementation. As a user, you can verify that the rendered Action is what you expected. If the rendering is taking more time, you will see the BEING_RENDERED phase.

  7. Run the Action.

    In the previous step, the Action was in the READY_TO_RUN phase. It is not executed automatically, as the Engine waits for the user's approval. To execute it, execute:

    capact action run rocketchat
  8. Watch the Action:

    capact action watch rocketchat

    Wait until the Action is finished.

  9. Once the Action is succeeded, view output TypeInstances:

    capact action status rocketchat
  10. Open the Rocket.Chat UI using the host value from the previous step.


🎉 Hooray! You now have your own Rocket.Chat instance installed. Be productive!

Validate Rocket.Chat high availability setup

NOTE: The following steps are optional. In this tutorial we used AWS EKS Capact installation and all instructions will be based on this setup.

Now, let's validate the high-availability setup for the Rocket.Chat.

Non-disruptive tests

Here we are simulating maintenance actions which should not disrupt Rocket.Chat. Non-disruptive actions for example are:

  • Rolling update of Rocket.Chat.
  • Scheduled Node maintenance where pods are evicted from the node.
  • Rescheduling pod to another node.
  1. List Rocket.Chat pods

    kubectl get pod -l
  2. Select two random pods from the list above and delete them.

    Use kubectl delete command. For example:

     kubectl delete pod rocketchat-1617956008-rocketchat-5b45b74f77-pncck

    NOTE: Make sure that at least one pod is in Ready state.

  3. Verify if Rocket.Chat is still running without any disruption.

Disruptive tests

Here we are simulating scenario when Kubernetes lost a connection to one of the worker nodes.

  1. Make sure that MongoDB and Rocket.Chat pods are running on different nodes.

    To list pods and assigned nodes run:

    kubectl get pod -o wide
  2. Make sure that the pod with public-ingress-nginx prefix is not running on the same nodes as Rocket.Chat.

    kubectl -n capact-system get pod -o wide
  3. Get a list of nodes where Rocket.Chat pods are running:

    kubectl get pod -o go-template --template='{{ range .items}}{{}} - {{ .spec.nodeName }}{{"\n"}}{{end}}'

    Choose one of them and note the node name.

  4. Terminate the selected worker node from the EKS console.

    To terminate note go to the cluster main page. In the Overview section click on the selected node. In the Info section click a link under Instance name. New tab will be opened. From the menu in the top right select Terminate instance option

    AWS Dashborad - nodes AWS Dashboard - worker AWS Dashboard - instance

  5. Open the Rocket.Chat site again using provided host during Rocket.Chat installation. It should be still accessible.

    NOTE: Depending on which node will be deleted and to which Rocket.Chat Pod you are connected, it may take up to 30 seconds for Kubernetes to change configuration. During that time Rocket.Chat may not be available.


⚠️ CAUTION: This removes all resources that you created.

When you are done, remove the Action and Helm charts:

capact action delete rocketchat
helm delete $(helm list -f="rocketchat-*|mongodb-*" -q

Additional resources

See the Content Development guide, to understand how to develop OCF content for Capact.

If you want to learn more about the project, check the capact repository.