---
title: "Deploy Rocket.Chat with Kubernetes Guide"
slug: "deploy-with-kubernetes"
status: "update"
updated: 2026-10-21T15:41:26Z
published: 2026-10-21T15:41:26Z
canonical: "docs.rocket.chat/deploy-with-kubernetes"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Deploy with Kubernetes

This guide shows you how to deploy Rocket.Chat on [Kubernetes](https://kubernetes.io/) with [Helm](https://helm.sh/). The [official Rocket.Chat Helm chart](https://github.com/RocketChat/helm-charts/tree/master/rocketchat) creates a workspace designed for scalability, resilience, and high availability.

The deployment separates Rocket.Chat from its database. You can manage your database layer independently of the application layer. It follows this approach:

1. **Provision an external MongoDB database**. This guide covers deploying a database using the [MongoDB Kubernetes operator](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity). If you already have an external MongoDB instance or use a managed service like Atlas, skip to step 5.
2. After your external MongoDB is ready, [**configure the monitoring stack**](/v1/docs/deploy-with-kubernetes#step-5-deploy-the-monitoring-stack). This enables observability in your workspace and ensures you can monitor your deployment effectively.
3. Once the database and monitoring stack are healthy, proceed to [**deploy Rocket.Chat and connect it to your external MongoDB instance**](/v1/docs/deploy-with-kubernetes#step-7-deploy-rocketchat).

> [!NOTE]
> If you currently use the bundled setup with the internal MongoDB chart, refer to [Moving from Bitnami to Official MongoDB Chart](https://forums.rocket.chat/t/action-required-moving-from-bitnami-to-official-mongodb-chart/22679) on the Rocket.Chat forum for migration guidance.

In this guide, you'll learn how to:

- [Deploy Rocket.Chat on Kubernetes](/v1/docs/deploy-with-kubernetes#prerequisites)
- [Configure your deployment with Helm values](/v1/docs/deploy-with-kubernetes#configure-your-deployment)
- [Update Rocket.Chat, MongoDB, and the Helm chart](/v1/docs/deploy-with-kubernetes#update-your-deployment)
- [Check, troubleshoot, and uninstall your deployment](/v1/docs/deploy-with-kubernetes#manage-your-deployment)

## Prerequisites

This guide assumes you have a basic understanding of Kubernetes and Helm. Before you begin, verify you have the following [server requirements](/v1/docs/deploy-with-kubernetes#server-requirements) and [Kubernetes resources](/v1/docs/deploy-with-kubernetes#kubernetes-resource-requirements).

### Server requirements

1. Your domain name must point to your server’s external IP address.
2. You need a live Kubernetes cluster with kubectl v1.21 or higher configured.
3. Helm version 3 must be installed on your server.
4. Check that your firewall allows HTTPS traffic.

### Kubernetes resource requirements

Make sure the following Kubernetes resources are ready in your cluster before moving on with deployment.

> [!WARNING]
> The examples that follow are intended as a guide. Adjust your implementation as needed based on your environment and Kubernetes setup before advancing to subsequent steps.

1. **Storage Class**: A [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) is required to provision Persistent Volumes (PVs). If your cluster doesn't have one, you'll need to create it. Run this command to check your storage class:

```bash
kubectl get storageclass
```

Copy the name of your StorageClass, you’ll need it to [configure the database](/v1/docs/deploy-with-kubernetes#step-3-configure-database-secrets-and-replica-set) in subsequent steps.

> [!NOTE]
> The [Rocket.Chat Helm chart](https://github.com/RocketChat/helm-charts/tree/master/rocketchat) 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 such cases, you can either connect to an external MongoDB instance or install a compatible local storage provisioner.
2. **Ingress Controller**: An [Ingress Controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) is essential for routing external traffic to your Rocket.Chat services. This guide uses Traefik as an example.
  1. Add the official Traefik Helm repository:

```bash
helm repo add traefik https://traefik.github.io/charts
helm repo update
```
  2. Install Traefik:

```bash
helm install traefik traefik/traefik \
  --namespace traefik \
  --create-namespace
```
  3. Confirm that the service has an external IP address by running:

```bash
kubectl get svc -n traefik
```
3. **TLS certificate manager**: If you don't have a valid TLS certificate, install `cert-manager` to automate certificate management via Let's Encrypt.
  1. Install [cert-manager](https://cert-manager.io/docs/installation/kubectl/#1-install-from-the-cert-manager-release-manifest) by running:

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.3/cert-manager.yaml
```
  2. Confirm the resources are created:

```bash
kubectl get all -n cert-manager
```
4. **ClusterIssuer**: cert-manager requires a [ClusterIssuer](https://cert-manager.io/docs/concepts/issuer/) to automatically issue TLS certificates across the cluster. This guide uses Let’s Encrypt.
  1. Create a `clusterissuer.yaml` file and save the following content:

```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
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: traefik
```

Replace `user01@mycompany.com` with your email address and set `privateKeySecretRef.name` to your preferred name.
  2. Create the resource:

```bash
kubectl apply -f clusterissuer.yaml
```
  3. Verify the ClusterIssuer was deployed and the secret was created successfully:

```bash
kubectl get clusterissuer
kubectl get secret -n cert-manager
```

---

## Step 1: Add the Helm chart repositories

Add the official [Rocket.Chat](https://github.com/RocketChat/helm-charts/tree/master/rocketchat) and [MongoDB Helm](https://github.com/mongodb/helm-charts) repositories:

```bash
helm repo add mongodb https://mongodb.github.io/helm-charts
helm repo add rocketchat https://rocketchat.github.io/helm-charts
helm repo update
```

Helm confirms that each repository was added.

## Step 2: Install the MongoDB Kubernetes operator

With the required Kubernetes resources in place, the next step is to install the [MongoDB Kubernetes operator](https://github.com/mongodb/mongodb-kubernetes/tree/master/docs/mongodbcommunity) to manage MongoDB lifecycle tasks like provisioning, scaling, and health checks.

1. Create a namespace:

```bash
kubectl create namespace rocketchat
```

> [!NOTE]
> This guide uses "rocketchat" as the namespace. You can change the namespace, but ensure you use the chosen name in subsequent steps.
2. Install the MongoDB operator:

```bash
helm install mongodb-kubernetes-operator mongodb/mongodb-kubernetes \
  -n rocketchat
```

Do not install CRDs separately. The operator chart manages them automatically.
3. Wait for the MongoDB operator to be ready:

```bash
kubectl rollout status deployment/mongodb-kubernetes-operator \
  -n rocketchat \
  --timeout=300s
```

## Step 3: Configure database secrets and replica set

Once the MongoDB operator is running, define the [MongoDB resources](https://www.mongodb.com/docs/kubernetes/current/reference/k8s-operator-specification/) to provision a replica set and configure authentication for Rocket.Chat.

1. Create `mongodb-secrets.yaml` with the following MongoDB secrets for database administrators, application user, and the monitoring endpoints:

```yaml
---
apiVersion: v1
kind: Secret
metadata:
  namespace: rocketchat
  name:  mongodb-admin-password
type: Opaque
stringData:
  password: <your-secure-admin-password>
---
apiVersion: v1
kind: Secret
metadata:
  namespace: rocketchat
  name: mongodb-rocketchat-password
type:  Opaque
stringData:
  password: <your-secure-rocketchat-password>
---
apiVersion: v1
kind: Secret
metadata:
  namespace: rocketchat
  name: metrics-endpoint-password
type:  Opaque
stringData:
  password: <your-secure-prometheus-password>
---
apiVersion: v1
kind: Secret
metadata:
  namespace: rocketchat
  name: admin-scram-credentials
type:  Opaque
stringData: 
  username: admin
  password: <your-secure-admin-password>
---
apiVersion: v1
kind: Secret
metadata:
  namespace: rocketchat
  name: rocketchat-scram-credentials
type: Opaque
stringData:
  username: rocketchat
  password: <your-secure-rocketchat-password>
```

> [!NOTE]
> Replace these placeholder passwords with secure values: `&lt;your-secure-admin-password&gt;`, `&lt;your-secure-rocketchat-password&gt;`, `&lt;your-secure-prometheus-password&gt;` .
2. Apply the secrets:

```bash
kubectl apply -f mongodb-secrets.yaml
```
3. Create `mongodb-community.yaml` file. Choose between a single node or multiple node ReplicaSet for MongoDB as needed:

**Single-node ReplicaSet**

```yaml
apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata: 
  name: mongodb
  namespace: rocketchat
spec:
  members:  1 
  type: ReplicaSet
  version: "8.0.0"
  security:
    authentication: 
      modes:  ["SCRAM"]
    tls:
      enabled: false
  users:
  - name:  admin
    db:  admin
    passwordSecretRef: 
      name: mongodb-admin-password
    scramCredentialsSecretName: admin-scram-credentials
    roles:
    - name: root
      db: admin
  - name: rocketchat
    db: rocketchat
    passwordSecretRef:
      name:  mongodb-rocketchat-password
    scramCredentialsSecretName: rocketchat-scram-credentials
    roles:
    - name: readWrite
      db: rocketchat
  prometheus:
    username:  prometheus-username
    passwordSecretRef:
      name: metrics-endpoint-password
  statefulSet:
    spec:
      volumeClaimTemplates:
      - metadata:
          name: data-volume
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: <your-storage-class>
          resources:
            requests:
              storage: 50Gi
      template:
        spec:
          containers:
          - name: mongod
            resources:
              limits:
                cpu:  1500m
                memory:  1Gi       #Configure the limits memory as required
              requests:
                cpu: 500m
                memory: 1Gi        #Configure the requests memory as required
```

- Replace `&lt;your-storage-class&gt;` with your actual StorageClass name.

**Multi-node ReplicaSet**

```yaml
apiVersion: mongodbcommunity.mongodb.com/v1
kind: MongoDBCommunity
metadata: 
  name: mongodb
  namespace: rocketchat
spec:
  members:  3    #Set your desired number of replicaSet
  type: ReplicaSet
  version: "8.0.0"
  security:
    authentication: 
      modes:  ["SCRAM"]
    tls:
      enabled: false
  users:
  - name:  admin
    db:  admin
    passwordSecretRef: 
      name: mongodb-admin-password
    scramCredentialsSecretName: admin-scram-credentials
    roles:
    - name: root
      db: admin
  - name: rocketchat
    db: rocketchat
    passwordSecretRef:
      name:  mongodb-rocketchat-password
    scramCredentialsSecretName: rocketchat-scram-credentials
    roles:
    - name: readWrite
      db: rocketchat
  prometheus:
    username:  prometheus-username
    passwordSecretRef:
      name: metrics-endpoint-password
  statefulSet:
    spec:
      volumeClaimTemplates:
      - metadata:
          name: data-volume
        spec:
          accessModes: ["ReadWriteOnce"]
          storageClassName: <your-storage-class>
          resources:
            requests:
              storage: 50Gi
      template:
        spec:
          containers:
          - name: mongod
            resources:
              limits:
                cpu:  1500m
                memory:  6Gi       #Configure the limits memory as required
              requests:
                cpu: 500m
                memory: 3Gi        #Configure the requests memory as required
```

- Replace `&lt;your-storage-class&gt;` with your actual StorageClass name.
- Update the value of `spec.members` to the desired number of replica set members. Replace the existing number as needed.
- Update the value of `limits.memory` and `requests.memory` as required for your workspace.

1. Apply the MongoDB resource:

```bash
kubectl apply -f mongodb-community.yaml
```

## Step 4: Verify the MongoDB deployment

After you deploy MongoDB, confirm that the database is healthy and reachable before you deploy Rocket.Chat.

1. Wait for the MongoDB pods to become ready:

```bash
kubectl wait --for=condition=ready pod -l app=mongodb-svc \
  -n rocketchat \
  --timeout=300s
```
2. Confirm the pod status:

```bash
kubectl get pods -n rocketchat | grep mongodb
```
3. Verify the MongoDB service endpoints:

```bash
kubectl get endpoints mongodb-svc -n rocketchat
```

You should see the MongoDB pod’s IP address listed. If no endpoints appear, the service selector may not match the pod labels correctly. Consult the [Kubernetes Deployment FAQ](/v1/docs/kubernetes-deployment-faq) for troubleshooting guidance.

### Validate MongoDB health

Choose the setup that matches how you created `mongodb-community.yaml` earlier to deploy MongoDB:

**Single-node ReplicaSet**

Run a ping against the admin database to confirm MongoDB is responding:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh admin --eval "db.adminCommand('ping')"
```

Expected output: `{ ok: 1 }`. If you see an error, do not proceed until MongoDB is healthy.

**Multiple-node ReplicaSet**

1. Verify that the primary database is healthy:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh admin --eval "db.adminCommand('ping')"
```

Expected output: `{ ok: 1 }`. If you see an error, do not proceed until MongoDB is healthy.
2. Check the status of all replica set members to confirm they are in sync:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- mongosh admin \
  -u admin \
  -p $(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d) \
  --eval "rs.status()"
```

### Build the MongoDB connection string

Rocket.Chat requires a specific URI format to connect to the database.

1. Extract the rocketchat user password and generate the MongoDB connection string:

```bash
MONGO_PASSWORD=$(kubectl get secret mongodb-rocketchat-password \
  -n rocketchat -o jsonpath='{.data.password}' | base64 -d)
echo "MongoDB URI:"
echo "mongodb://rocketchat:${MONGO_PASSWORD}@mongodb-0.mongodb-svc.rocketchat.svc.cluster.local:27017/rocketchat?authSource=rocketchat&replicaSet=mongodb"
```

The generated connection string will be in the following format:

```bash
mongodb://rocketchat:testrc123@mongodb-0.mongodb-svc.rocketchat.svc.cluster.local:27017/rocketchat?authSource=rocketchat&replicaSet=mongodb
```
2. Save the generated MongoDB connection string. You’ll need it later to [connect Rocket.Chat to your database](/v1/docs/deploy-with-kubernetes#step-6-configure-rocketchat).

> [!NOTE]
> If you deployed a multi-node ReplicaSet for MongoDB, update the connection string to include all replica set members as comma-separated hosts before the database path. The number of hosts should match the number of members you configured in `spec.members`.

## Step 5: Deploy the monitoring stack

The Rocket.Chat monitoring Helm chart deploys Prometheus to collect metrics, Loki to aggregate logs, and Grafana to display metrics and logs in dashboards.

1. Create a file named `values-monitoring.yaml` and add the following configuration:

```yaml
ingress:
  enabled: true
  ingressClassName: "traefik" # Specify the installed ingress controller in the K8s cluster
  tls: true
  grafana:
    enabled: true
    host: "domain.xyz"
    path: "/grafana"
```
  1. Replace `domain.xyz` with your actual domain name.
  2. Set `ingressClassName` to match the ingress controller deployed in your Kubernetes cluster.
2. Install the monitoring stack:

```bash
helm install monitoring -f values-monitoring.yaml rocketchat/monitoring -n rocketchat
```

Helm returns the release details with `STATUS: deployed`.

## Step 6: Configure Rocket.Chat

With database and monitoring stack running, the next step is to define how Rocket.Chat should run in your cluster. These configuration values control image versions, ingress, TLS, and service behavior.

1. Create a `values.yaml` file to define your [deployment configurations](/v1/docs/deploy-with-kubernetes#configure-your-deployment). This file specifies how Helm should configure your Rocket.Chat workspace.

Below is an example configuration to use for your `values.yaml` file:

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

mongodb:
  enabled: false

externalMongodbUrl: "<enter-external-mongodb-uri>"

microservices:
  enabled: true
replicaCount: 1

host: <domain.xyz>

ingress:
  enabled: true
  ingressClassName: traefik
  annotations:
    cert-manager.io/cluster-issuer: production-cert-issuer
  tls:
    - secretName: rckube
      hosts:
        - <domain.xyz>
nats:
  cluster:
    name: rocketchat-nats-cluster
```
  1. Replace `&lt;release&gt;` with the [Rocket.Chat version](https://github.com/RocketChat/Rocket.Chat/releases) you want to deploy.
  2. Connect the external MongoDB by replacing `&lt;enter-external-mongodb-uri&gt;` with the connection string you saved in [step 4](/v1/docs/deploy-with-kubernetes#build-the-mongodb-connection-string).
  3. Update `&lt;domain.xyz&gt;` with your actual domain name.
  4. Set the `ingressClassName` to the ingress controller you are using.
  5. 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.
  6. To set other options, see [Configure your deployment](/v1/docs/deploy-with-kubernetes#configure-your-deployment).

> [!NOTE]
> This configuration enables microservices with a single replica, which suits [Community workspaces](/v1/docs/our-plans#community-workspaces). To scale your workspace with multiple replicas, see [Scaling Rocket.Chat with Microservices](/v1/docs/microservices).

## Step 7: Deploy Rocket.Chat

After finalizing the configuration, launch the Rocket.Chat deployment.

1. Install Rocket.Chat with the configurations you defined in `values.yaml`:

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

Helm returns the release details with `STATUS: deployed`.
2. Wait for Rocket.Chat to be ready:

```bash
kubectl rollout status deployment/rocketchat-rocketchat \
  -n rocketchat \
  --timeout=300s
```
3. Verify that the pods for your deployment are running:

```bash
kubectl get pods -n rocketchat
```

Each pod shows `Running` in the `STATUS` column. The pods listed depend on your configuration.
4. Check the Rocket.Chat logs to confirm that it started:

```bash
kubectl logs deployment/rocketchat-rocketchat -n rocketchat | grep -A 15 "SERVER RUNNING"
```

The output shows a `SERVER RUNNING` block that lists the Rocket.Chat version, the MongoDB version, and the site URL.

> [!NOTE]
> If you encounter any issues with your deployment, refer to the [Kubernetes Deployment FAQ](/v1/docs/kubernetes-deployment-faq).

## Step 8: Access your Rocket.Chat workspace

After a few minutes, your Rocket.Chat workspace will be accessible at the configured domain (for example, `https://domain.xyz`).

Follow the [on-screen prompts](/v1/docs/setup-your-workspace) 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](https://docs.rocket.chat/docs/rocketchat-cloud), where you can manage your subscriptions.

### Access monitoring dashboard

A Grafana dashboard will also be available at the [path you configured](/v1/docs/deploy-with-kubernetes#step-5-deploy-the-monitoring-stack) (for example, `https://domain.xyz/grafana`). Log in with the following default credentials:

- User: `admin`
- Password: `admin`

You’ll be prompted to set a new password after your first login.

For more details on how to monitor your workspace metrics and logs, refer to the [Monitor Workspace Logs and Metrics guide](/v1/docs/access-workspace-logs).

## Step 9: Configure file storage

By default, Rocket.Chat uses GridFS for file uploads. While easy to set up, GridFS increases database load and does not scale well for production. For higher performance and scalability, use a dedicated object storage service such as [Amazon S3](/v1/docs/file-upload#configure-amazon-s3-file-storage), [Google Cloud Storage (GCS)](/v1/docs/file-upload#configure-google-cloud-storage), or [MinIO](/v1/docs/minio). Refer to the [File Uploads guide](/v1/docs/file-upload) for detailed instructions on configuring your preferred file storage solution.

### Next steps

To continue setting up your workspace, see these guides:

- [User Guides](/v1/docs/collaborate-using-rocketchat): Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users.
- [Workspace Administration](/v1/docs/administrators-guide): Administrators and owners can set and manage various configurations.
- [Marketplace](/v1/docs/rocketchat-marketplace): Explore the available apps to enhance your workspace.

---

## Configure your deployment

The [Rocket.Chat Helm chart](https://github.com/RocketChat/helm-charts/tree/master/rocketchat) reads its settings from your `values.yaml` file. To change a setting, add or update the parameter in `values.yaml`, then apply the change:

```bash
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat
```

Helm replaces the Rocket.Chat pods one at a time with a rolling update.

### Helm chart parameters

The following tables list the parameters you are most likely to set. Defaults come from the chart's `values.yaml` file. A default of *Not set* means the key is absent or commented out in that file.

#### Image, host, and replicas

| Parameter | Description | Default |
| --- | --- | --- |
| `image.repository` | Image repository. | `registry.rocket.chat/rocketchat/rocket.chat` |
| `image.tag` | Rocket.Chat release to deploy. Set this to pin your workspace to a specific release. | *Not set* |
| `image.pullPolicy` | Image pull policy. | `IfNotPresent` |
| `host` | Hostname for Rocket.Chat. The ingress also uses this value when it is enabled. | *Not set* |
| `replicaCount` | Number of Rocket.Chat replicas to run. | `1` |
| `minAvailable` | Minimum number or percentage of pods that must stay scheduled. | `1` |
| `podDisruptionBudget.enabled` | Creates a PodDisruptionBudget for the Rocket.Chat deployment. | `true` |

#### Database

| Parameter | Description | Default |
| --- | --- | --- |
| `mongodb.enabled` | Deploys the bundled MongoDB chart. Set to `false` when you connect to an external MongoDB, as this guide does. | `true` |
| `externalMongodbUrl` | Connection string for an externally provisioned MongoDB. | *Not set* |
| `existingMongodbSecret` | Name of an existing secret that contains the MongoDB connection string. | `""` |

#### Microservices

| Parameter | Description | Default |
| --- | --- | --- |
| `microservices.enabled` | Runs Rocket.Chat as [microservices](/v1/docs/microservices). | `true` |
| `microservices.presence.replicas` | Replicas for the presence service. | `1` |
| `microservices.ddpStreamer.replicas` | Replicas for the DDP streamer service. | `1` |
| `microservices.account.replicas` | Replicas for the account service. | `1` |
| `microservices.authorization.replicas` | Replicas for the authorization service. | `1` |
| `nats.cluster.replicas` | Replicas for the NATS cluster that the microservices use to communicate. | `2` |

#### Ingress and service

| Parameter | Description | Default |
| --- | --- | --- |
| `ingress.enabled` | Creates an ingress when set to `true`. | `false` |
| `ingress.ingressClassName` | Ingress class of the ingress controller in your cluster. | *Not set* |
| `ingress.pathType` | Path type for the ingress resource. | `Prefix` |
| `ingress.annotations` | Annotations for the ingress, such as the cert-manager ClusterIssuer. | `{}` |
| `ingress.path` | Path of the ingress. | `/` |
| `ingress.tls` | List of [IngressTLS](https://kubernetes.io/docs/reference/kubernetes-api/service-resources/ingress-v1/#IngressSpec) items. | `[]` |
| `service.type` | Kubernetes service type. | `ClusterIP` |
| `service.port` | Service port. | `80` |
| `service.nodePort` | Node port to use when `service.type` is `NodePort`. | *Not set* |
| `service.annotations` | Annotations for the Rocket.Chat service. | `{}` |
| `service.labels` | Additional labels for the Rocket.Chat service. | `{}` |

#### Scheduling and resources

| Parameter | Description | Default |
| --- | --- | --- |
| `resources` | Pod resource requests and limits. | *Not set* |
| `podAntiAffinity` | Controls whether Rocket.Chat replicas can run on the same node. `soft` prefers separate nodes without guaranteeing it. `hard` requires separate nodes. An empty value disables anti-affinity. | `""` |
| `podAntiAffinityTopologyKey` | Topology key used when anti-affinity is enabled, for example `topology.kubernetes.io/zone`. | `kubernetes.io/hostname` |
| `affinity` | Custom [affinity rules](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/) for the Rocket.Chat pods. | `{}` |
| `podLabels` | Additional labels for the Rocket.Chat pods. | `{}` |
| `podAnnotations` | Additional annotations for the Rocket.Chat pods. | `{}` |

#### Storage

| Parameter | Description | Default |
| --- | --- | --- |
| `persistence.enabled` | Stores Rocket.Chat data on a persistent volume claim (PVC). You don't need this when you use the default [GridFS](/v1/docs/file-upload) file storage. | `false` |
| `persistence.storageClass` | Storage class of the PVC. | *Not set* |
| `persistence.accessMode` | Access mode of the PVC. | `ReadWriteOnce` |
| `persistence.size` | Size of the PVC. | `8Gi` |
| `persistence.existingClaim` | Name of an existing PVC to use. | *Not set* |
| `extraVolumes` | Extra volumes, for example to add certificates or other files. | `[]` |
| `extraVolumeMounts` | Mount paths for `extraVolumes` inside the container. | `[]` |

#### Security

| Parameter | Description | Default |
| --- | --- | --- |
| `securityContext.runAsUser` | User ID the pod runs as. See [Upgrade to Helm chart 7.0.0](/v1/docs/deploy-with-kubernetes#upgrading-to-helm-chart-700). | `65533` |
| `securityContext.fsGroup` | File system group for the pod. | `65533` |
| `serviceAccount.create` | Creates a ServiceAccount. | `true` |
| `serviceAccount.name` | Name of the ServiceAccount. If empty and `serviceAccount.create` is `true`, the chart generates a name. | `""` |

#### Health checks

| Parameter | Description | Default |
| --- | --- | --- |
| `livenessProbe.enabled` | Turns the liveness probe on or off. | `true` |
| `livenessProbe.initialDelaySeconds` | Delay before the first liveness probe. | `60` |
| `livenessProbe.periodSeconds` | Interval between liveness probes. | `15` |
| `livenessProbe.timeoutSeconds` | Seconds before a liveness probe times out. | `5` |
| `livenessProbe.failureThreshold` | Consecutive failures before the probe fails. | `3` |
| `livenessProbe.successThreshold` | Consecutive successes before the probe succeeds. | `1` |
| `readinessProbe.enabled` | Turns the readiness probe on or off. | `true` |
| `readinessProbe.initialDelaySeconds` | Delay before the first readiness probe. | `10` |
| `readinessProbe.periodSeconds` | Interval between readiness probes. | `15` |
| `readinessProbe.timeoutSeconds` | Seconds before a readiness probe times out. | `5` |
| `readinessProbe.failureThreshold` | Consecutive failures before the probe fails. | `3` |
| `readinessProbe.successThreshold` | Consecutive successes before the probe succeeds. | `1` |

#### Metrics

| Parameter | Description | Default |
| --- | --- | --- |
| `prometheusScraping.enabled` | Exposes the `/metrics` endpoint for Prometheus. | `true` |
| `prometheusScraping.port` | Port for Rocket.Chat metrics. | `9100` |
| `prometheusScraping.msPort` | Port for microservices metrics. | `9458` |
| `serviceMonitor.enabled` | Creates ServiceMonitor resources for the Prometheus Operator. Requires `prometheusScraping.enabled`. | `false` |
| `serviceMonitor.intervals` | Scrape intervals. | `[30s]` |
| `serviceMonitor.ports` | Port names that expose metrics. | `[metrics]` |

#### Email, license, and registration

| Parameter | Description | Default |
| --- | --- | --- |
| `smtp.enabled` | Sends email through SMTP. | `false` |
| `smtp.username` | SMTP account username. | `""` |
| `smtp.password` | SMTP account password. | `""` |
| `smtp.host` | SMTP server hostname. | `""` |
| `smtp.port` | SMTP server port. | `587` |
| `license` | Contents of your license file, if you have one. | *Not set* |
| `registrationToken` | Registration token for [Rocket.Chat Cloud](https://cloud.rocket.chat/). | *Not set* |

> [!NOTE]
> For every available parameter, see the chart's [`values.yaml`](https://github.com/RocketChat/helm-charts/blob/master/rocketchat/values.yaml) file on GitHub.

### Set environment variables

[Environment variables](/v1/docs/deployment-environment-variables) control how your workspace is deployed and configured. To set an environment variable on Kubernetes:

1. Open your `values.yaml` file:

```bash
nano values.yaml
```
2. Add an `extraEnv` section and set the environment variable. For example, to override the SMTP Host setting, add:

```yaml
extraEnv:
 - name: OVERWRITE_SETTING_SMTP_Host
   value: "my.smtp.server.com"
```
3. Upgrade your deployment to apply the new changes:

```bash
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat
```

For a full list of available environment variables, refer to [Deployment Environment Variables](/v1/docs/deployment-environment-variables).

### Scale your deployment

To run more than one replica of Rocket.Chat or of individual services, see [Scaling Rocket.Chat with Microservices](/v1/docs/microservices).

#### Scale MongoDB replicas

The MongoDB Kubernetes operator manages the replica set. To add or remove members, patch the `MongoDBCommunity` resource and the operator applies the change:

1. Update the number of MongoDB members in the ReplicaSet with this command:

```bash
kubectl patch mongodbcommunity mongodb -n rocketchat \
  --type='json' -p='[{"op": "replace", "path": "/spec/members", "value": <replica-set-number>}]'
```

Replace `&lt;replica-set-number&gt;` with the number of replica set members you want.
2. To verify, check the running pods for additional mongodb pods:

```bash
kubectl get pods -n rocketchat
```

---

## Update your deployment

### Update Rocket.Chat

> [!WARNING]
> Before you proceed, **consult the** [**general guidelines for updating Rocket.Chat**](/v1/docs/guidelines-for-updating-rocketchat).

To update your workspace to a new Rocket.Chat release:

1. Update the `image.tag` field in the `values.yaml` file to the desired release:

```yaml
image:
  tag: <release>
```

Replace `&lt;release&gt;` with your chosen Rocket.Chat release number. For available versions, see [Rocket.Chat release notes](/v1/docs/rocketchat-release-notes).
2. After you update the image, run this command to apply changes:

```bash
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat
```

> [!NOTE]
> The `helm upgrade` command above does not pin a chart version, so it installs the latest Rocket.Chat Helm chart. Updating your app version may therefore also move you to a newer chart version automatically, which can include breaking changes. See [Understand Helm chart versions](/v1/docs/deploy-with-kubernetes#understanding-helm-chart-versions).
3. After a few minutes, return to your workspace [subscription](/v1/docs/subscription) to verify the updated Rocket.Chat version.

> [!WARNING]
> If you are upgrading to Helm chart 7.0.0 and you have `persistence.enabled: true`, additional steps are required. Refer to [Upgrade to Helm chart 7.0.0](/v1/docs/deploy-with-kubernetes#upgrading-to-helm-chart-700) for more details.

### Update MongoDB

Before you change the MongoDB version, confirm the following:

1. Check the [release notes](https://github.com/RocketChat/Rocket.Chat/releases) to verify that your target MongoDB version is supported by your current Rocket.Chat release.
2. Ensure that the MongoDB image for the target version is available on Quay.io under [mongodb-community-server](https://quay.io/repository/mongodb/mongodb-community-server?tab=tags). Look for an image tagged `&lt;target-version&gt;-ubi8`.
3. Avoid skipping major versions. For example, to move from 4.4 to 6.0, you must upgrade to 5.0 first, ensure it is stable, and then proceed to 6.0.
4. Confirm the database `featureCompatibilityVersion` aligns with the current major version. If you are running MongoDB 5.0 but your fCV is still set to 4.4, an upgrade to 6.0 will fail.

To check your current `featureCompatibilityVersion`:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" --eval "db.adminCommand({getParameter: 1, featureCompatibilityVersion: 1})"
```

To upgrade or downgrade MongoDB:

1. Set the new MongoDB version:

```bash
kubectl patch mongodbcommunity mongodb -n rocketchat \
  --type='json' -p='[{"op":  "replace", "path": "/spec/version", "value":"<mongodb-version>"}]'
```

Replace `&lt;mongodb-version&gt;` with your target MongoDB version number.
2. Check the pods and wait for MongoDB to start running again:

```bash
kubectl get pods -n rocketchat
```
3. Confirm the MongoDB version that is running:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" \
  --eval "db.version()"
```

### Understand Helm chart versions

A Helm deployment of Rocket.Chat has two independently versioned components:

- The [Rocket.Chat application version](https://github.com/RocketChat/Rocket.Chat/releases), which determines the version of Rocket.Chat running in your workspace.
- The [Helm chart version](https://github.com/RocketChat/helm-charts), which defines how Rocket.Chat is deployed and configured in your Kubernetes cluster.

These versions change independently. A new Rocket.Chat release does not always mean a new chart version, and a chart update may ship without a corresponding application release. When you run `helm upgrade`, Helm automatically pulls the latest chart version available in the repository unless it is pinned to a specific version. New chart releases can include updates to deployment templates, configuration options, and default values. In major chart releases, these changes may require you to update your existing `values.yaml` file before updating your deployment.

To stay on a specific chart version, add `--version` to the command:

```bash
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat --version <chart-version>
```

To list the available chart versions, run `helm search repo rocketchat/rocketchat --versions`.

### Upgrade to Helm chart 7.0.0

Helm chart 7.0.0 changes the default user and group that Rocket.Chat runs as. The chart now uses UID `65533` instead of `999` to match the UID baked into the Rocket.Chat image at build time. This change also resolves the EACCES error that causes Apps Engine to fail in Rocket.Chat 8.5.0 and later.

If your deployment does not use persistent storage (`persistence.enabled: false`), no additional steps are required. Update your workspace [following the usual steps](/v1/docs/deploy-with-kubernetes#updating-rocketchat-on-kubernetes).

If your deployment uses persistent storage (`persistence.enabled: true`), the existing volume data is likely owned by UID `999`. After updating, the pod runs as UID 65533 and cannot access that data, which causes the pod to fail to start or apps to fail with permission errors.

To prevent this, update the ownership of the existing volume data to UID 65533:

1. Identify the persistent volume claim (PVC) used by Rocket.Chat:

```bash
kubectl get pvc -n rocketchat
```
2. Scale down the Rocket.Chat deployment so no pod is actively using the volume:

```bash
kubectl scale deployment rocketchat-rocketchat --replicas=0 -n rocketchat
```
3. Run a temporary pod to update the volume ownership. Replace `&lt;pvc-name&gt;` with the PVC name from step 1:

```bash
kubectl run chown-migration -n rocketchat --rm -it --restart=Never \
  --overrides='{"spec":{"volumes":[{"name":"data","persistentVolumeClaim":{"claimName":"<pvc-name>"}}],"containers":[{"name":"chown","image":"busybox","command":["chown","-R","65533:65533","/data"],"volumeMounts":[{"name":"data","mountPath":"/data"}]}]}}' \
  --image=busybox
```
4. With ownership corrected, update the deployment:

```bash
helm upgrade rocketchat -f values.yaml rocketchat/rocketchat -n rocketchat
```

> [!WARNING]
> Reverting to UID 999 is only safe on Rocket.Chat versions before 8.5.0. From 8.5.0 onward, Apps Engine requires write access to paths owned by UID 65533. On those versions, running the container as UID 999 stops apps from starting. On Rocket.Chat 8.5.0 or later, migrate the volume instead of overriding the UID.

---

## Manage your deployment

### Check status and logs

Use these commands to inspect your deployment:

1. To check the pods in your deployment:

```bash
kubectl get pods -n rocketchat
```
2. To view the logs for a specific Rocket.Chat pod:

```bash
kubectl logs -n rocketchat <pod-name>
```
3. To stream real-time logs from a running Rocket.Chat pod:

```bash
kubectl logs -n rocketchat -f <pod-name>
```

This helps in tracking ongoing events and debugging issues as they occur.
4. To check MongoDB replica set status:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh admin --eval "rs.status()"
```
5. Get the service details for the deployment:

```bash
kubectl get svc -n rocketchat
```
6. To check the current MongoDB version that is running:

```bash
kubectl exec -it mongodb-0 -n rocketchat -- \
  mongosh "mongodb://admin:$(kubectl get secret mongodb-admin-password -n rocketchat -o jsonpath='{.data.password}' | base64 -d)@localhost:27017/admin?authSource=admin" \
  --eval "db.version()"
```

If you encounter further issues with your deployment, refer to the [Kubernetes Deployment FAQ](/v1/docs/kubernetes-deployment-faq).

### Uninstall Rocket.Chat

To uninstall the Rocket.Chat release, run:

```bash
helm uninstall rocketchat -n rocketchat
```

This command removes only the Rocket.Chat release. The monitoring stack, the MongoDB operator, and the MongoDB resource remain in the `rocketchat` namespace. To remove them as well, run:

```bash
helm uninstall monitoring -n rocketchat
kubectl delete mongodbcommunity mongodb -n rocketchat
helm uninstall mongodb-kubernetes-operator -n rocketchat
```

> [!CAUTION]
> Persistent volume claims created for MongoDB are not deleted automatically. Deleting them with `kubectl delete pvc` permanently removes your workspace data.