Deploy with OpenShift

Deploy Rocket.Chat on Red Hat OpenShift with the official Rocket.Chat Helm chart. The deployment is the same as Deploy with Kubernetes, except for pod permissions, ingress, and monitoring. This document covers only those differences.

Follow Deploy with Kubernetes for every step this document doesn't mention, including MongoDB and the rest of your values.yaml file.

Prerequisites

Before you begin, make sure you have the following:

• An OpenShift 4 cluster and cluster-admin access. Granting a Security Context Constraint (SCC) requires cluster-admin.

• The oc command-line tool, logged in to the cluster.

• Helm version 3.

• The prerequisites listed in Deploy with Kubernetes.

• A DNS record for your workspace hostname that points to the OpenShift router, and a TLS certificate and private key for that hostname.

Differences from standard Kubernetes

Grant the nonroot-v2 SCC

OpenShift uses SCCs to control pod permissions, including the user account a pod runs as. If you don't set an SCC, OpenShift uses the restricted-v2 SCC.

restricted-v2 makes every pod run as a UID that OpenShift picks from the namespace's assigned range. The Rocket.Chat chart asks for UID 65533, the UID the Rocket.Chat image was built with, so restricted-v2 rejects the Rocket.Chat pod. This applies only to the rocketchat-rocketchat pods. The other services, such as rocketchat-account, rocketchat-authorization, and rocketchat-presence, aren't affected.

The nonroot-v2 SCC lets the Rocket.Chat service account run a pod as any non-root UID it asks for. The pod is admitted as UID 65533, which owns the image's files, and the root user stays blocked.

The chart names the service account <release>-rocketchat. The examples in this document use the release name rocketchat and the namespace rocketchat, so the service account is rocketchat-rocketchat. Replace these values if you use different names.

Grant the SCC before you run helm install.

1. Create the namespace if it doesn't exist yet:

   oc new-project rocketchat

2. Grant nonroot-v2 to the Rocket.Chat service account. Use one of these methods:

   • Command line: Run the following command:

     oc adm policy add-scc-to-user nonroot-v2 -z rocketchat-rocketchat -n rocketchat

   • Manifest: Save the following RoleBinding as rocketchat-scc.yaml:

     apiVersion: rbac.authorization.k8s.io/v1
     kind: RoleBinding
     metadata:
       name: rocketchat-nonroot-v2
       namespace: rocketchat
     roleRef:
       apiGroup: rbac.authorization.k8s.io
       kind: ClusterRole
       name: system:openshift:scc:nonroot-v2
     subjects:
       - kind: ServiceAccount
         name: rocketchat-rocketchat
         namespace: rocketchat

     Then apply it:

     oc apply -f rocketchat-scc.yaml

Configure the ingress

On standard Kubernetes, you deploy an ingress controller to allow HTTP access from outside the cluster. OpenShift includes the OpenShift router, an HAProxy-based ingress controller that is preconfigured in the cluster. The router handles standard Ingress objects and OpenShift's own Route objects. It converts the Ingress that the Rocket.Chat chart creates into Routes and terminates TLS.

1. Create a TLS secret from your certificate and private key:

   oc create secret tls rocketchat-tls --cert=<path-to-certificate> --key=<path-to-private-key> -n rocketchat

2. Add the following to your values.yaml file. Replace rocketchat.example.com with your workspace hostname. It must match the host value in the same file.

   ingress:
     enabled: true
     ingressClassName: openshift-default
     annotations:
       route.openshift.io/termination: edge
     tls:
       - secretName: rocketchat-tls
         hosts:
           - rocketchat.example.com

When you install the chart, OpenShift creates the Routes from these ingress entries.

Install Rocket.Chat

1. Install the chart with your values.yaml file as described in Deploy with Kubernetes:

   helm install rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat

2. Confirm which SCC admitted each pod:

   oc get pods -n rocketchat -o custom-columns='NAME:.metadata.name,SCC:.metadata.annotations.openshift\.io/scc'

   The rocketchat-rocketchat pods show nonroot-v2.

3. Confirm the UID the Rocket.Chat container runs as:

   oc exec -n rocketchat deploy/rocketchat-rocketchat -- id

   The output starts with uid=65533.

4. Confirm the router created the Routes:

   oc get route -n rocketchat

   Each Route shows your workspace hostname.

5. Open https://<your-hostname> in a browser and complete the setup wizard as described in Deploy with Kubernetes.

Set up monitoring

OpenShift includes its own monitoring stack. User Workload Monitoring (UWM) extends it to collect metrics from your own projects, including the Prometheus metrics endpoints that Rocket.Chat provides. On OpenShift, use UWM and import the Rocket.Chat dashboards instead of installing the rocketchat/monitoring chart.

1. Enable UWM by following Enabling monitoring for user-defined projects in the OpenShift documentation.

2. Import the Rocket.Chat dashboards. See Grafana for the dashboard IDs and download URL.

For details about the metrics Rocket.Chat exposes, see Monitor Workspace Logs and Metrics.

Troubleshooting

The Rocket.Chat pod is never created

Symptom: The other service pods start, but no rocketchat-rocketchat pod appears.

Cause: OpenShift rejected the pod because it asks for UID 65533 under restricted-v2. The SCC grant is missing, or it names the wrong service account.

Resolution: Run oc describe replicaset -n rocketchat and check the events for an SCC error. Confirm the service account in the grant matches <release>-rocketchat, then grant nonroot-v2 as described in Grant the nonroot-v2 SCC.

No Routes are created

Symptom: oc get route -n rocketchat returns no Routes.

Cause: ingress.enabled is false, or ingressClassName isn't set to openshift-default.

Resolution: Update the ingress values as described in Configure the ingress, then run helm upgrade with the same values file.

For general Kubernetes issues, see the Kubernetes Deployment FAQ.

Related topics

• Deploy with Kubernetes

• Kubernetes Deployment FAQ

• Monitor Workspace Logs and Metrics