--- title: "Configure External MongoDB" slug: "configure-external-mongodb-for-rocket-chat" updated: 2026-06-18T17:55:12Z published: 2026-06-18T17:55:12Z canonical: "docs.rocket.chat/configure-external-mongodb-for-rocket-chat" stale: true --- > ## 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. # Configure External MongoDB for Rocket.Chat This guide explains how to run Rocket.Chat with the Docker Compose stack against a MongoDB instance you manage yourself, for example on a separate host, on MongoDB Atlas, or on another managed service, instead of the bundled MongoDB that ships with the stack. By default, the stack provisions a MongoDB container for you. Connect to an external MongoDB when you run a managed database service, when you maintain MongoDB separately from Rocket.Chat, or when your production setup keeps the database on its own host. > [!NOTE] > When you replace a bundled component with an external one, the monitoring stack cannot scrape metrics from that component. To collect those metrics in Grafana, see [Metrics for external services.](/v1/docs/configure-external-mongodb-for-rocket-chat#metrics-for-external-services) ## Prerequisites > [!WARNING] > This guide assumes you already have the Rocket.Chat Docker Compose stack set up, including the repository cloned and a working `.env` file. If you have not done this yet, follow [Deploy with Docker and Docker Compose](https://docs.rocket.chat/docs/deploy-with-docker-docker-compose) first. Before connecting Rocket.Chat to an external MongoDB instance, ensure the following requirements are met: ### Replica set Rocket.Chat requires the database to run as a replica set: - A single-node replica set is supported. - The replica set name must match the value used in MONGO_URL. ### Database access Create or use the MongoDB user that Rocket.Chat will use for the final database, and make sure it has `readWrite` permission on that database: - The user should have `readWrite` on the `rocketchat` database, or on whatever database name is used in `MONGO_URL`. - If the user is authenticated against a different database, specify the correct `authSource` in `MONGO_URL`. ### Network reachability The Rocket.Chat container must be able to connect to the database: - All hosts in the connection string must be reachable. - Required ports (typically 27017) must be open. - Hostnames or IP addresses must resolve correctly from inside the container. --- ## Step 1: Configure `Mongo_URL` Copy `.env` example to `.env` , then set the `MONGO_URL` environment variable. This variable defines how Rocket.Chat connects to your external MongoDB instance. **Standard replica set** ```bash MONGO_URL=mongodb://USERNAME:PASSWORD@mongo1.example.com:27017,mongo2.example.com:27017/rocketchat?replicaSet=rs0&authSource=admin ``` **MongoDB Atlas (SRV)** ```bash MONGO_URL=mongodb+srv://USERNAME:PASSWORD@cluster0.xxxxx.mongodb.net/rocketchat?retryWrites=true&w=majority ``` > [!WARNING] > SRV (`mongodb+srv`) URLs are handled differently by the Rocket.Chat container and do not use the same connection checks as standard `mongodb://` URLs. > > When using SRV, Rocket.Chat may receive additional hostnames from DNS. Make sure all of those hostnames are resolvable from inside the container. If the SRV record returns IP addresses, make sure those IPs are reachable from the container, for example through the private network when private IPs are used. **MongoDB on the Docker host** If MongoDB runs on the Docker host (not inside the stack), use a hostname or IP address that is accessible from inside the container. ```bash MONGO_URL=mongodb://user:pass@172.17.0.1:27017/rocketchat?replicaSet=rs0&authSource=admin ``` Alternatively, you can configure Docker to resolve `host.docker.internal` using `extra_hosts`. The hostname used in the replica set configuration must match the hostname used in `MONGO_URL` . ## Step 2: Update the Docker Compose command The default deployment includes MongoDB via `compose.database.yml`. When using an external MongoDB instance, do not include this file. Run Rocket.Chat without the bundled database: ```bash docker compose \  -f compose.monitoring.yml \  -f compose.traefik.yml \  -f compose.yml \  -f compose.nats.yml \  -f docker.yml \  up -d ``` If you are not using monitoring or Traefik, you can omit those files as needed. ## Step 3: Monitoring considerations When using an external MongoDB instance: - The included `mongodb-exporter` will not collect metrics from your external database - Prometheus and Grafana dashboards may not show MongoDB metrics - You may need to configure external monitoring separately Additionally: - Variables such as `MONGODB_BIND_IP` and `MONGODB_PORT_NUMBER `only apply to the bundled MongoDB service - These variables do not affect external MongoDB deployments --- ## Configuring external NATS By default, the stack runs a NATS service and its exporter for you. Connect to an external NATS when you operate a NATS server separately from [Rocket.Chat](http://Rocket.Chat), or when your infrastructure already provides one. > [!NOTE] > When you replace a bundled component with an external one, the monitoring stack cannot scrape metrics from that component. To collect those metrics in Grafana, see [Metrics for external services.](/v1/docs/configure-external-mongodb-for-rocket-chat#metrics-for-external-services) ### Prerequisites Before connecting Rocket.Chat to an external NATS server, make sure the following requirements are met. #### Reachable broker The Rocket.Chat container must be able to open a client connection to your NATS server. - The NATS host and port must be reachable from inside the container. - The default NATS client port is `4222`. - Required firewall rules and security groups must allow the connection. #### Transporter URL Rocket.Chat connects to NATS through the `TRANSPORTER` environment variable, which is set from `NATS_URL` in `compose.yml`. - When `NATS_URL` is unset, it defaults to `monolith+nats://nats:4222`, where the hostname `nats` refers to the bundled service. The `monolith+nats://` prefix is only for non-microservice deployments. - For an external broker in a non-microservice deployment, use the same `monolith+nats://` scheme with your own host and port, for example `monolith+nats://nats.example.com:4222`. - For microservices deployments, use `nats://` instead. Microservices deployments are recommended to run with an orchestrator such as Kubernetes. ### Step 1: Configure `NATS_URL` Copy `.env.example` to `.env`, then set the `NATS_URL` environment variable. This variable defines how Rocket.Chat connects to your external NATS server. **Example: external NATS** ```bash NATS_URL=monolith+nats://YOUR_NATS_HOST:4222 ``` > [!WARNING] > Use the hostname or IP address that is reachable from inside the Rocket.Chat container, not only from your local machine. For NATS running on the Docker host from a Linux container, you may need to use the host gateway IP or configure an `extra_hosts` entry. > > If your external NATS server uses TLS or a non-default port, use the URL form that your Rocket.Chat and NATS deployment expects for that setup. ### Step 2: Update the Docker Compose command The default deployment includes NATS through `compose.nats.yml`. When you use an external NATS server, do not include this file. Run [Rocket.Chat](http://Rocket.Chat) without the bundled NATS service: ```bash docker compose \  -f compose.monitoring.yml \  -f compose.traefik.yml \  -f compose.yml \  -f compose.nats.yml \  -f docker.yml \  up -d ``` Adjust the file list to match your deployment. For example, also omit `compose.database.yml` when you use an external MongoDB. Use the same `-f` list consistently for `up`, `logs`, and `down`. ### Step 3: Review monitoring considerations When you use an external NATS server: - The included `nats-exporter` does not collect metrics from your external broker. - Prometheus and Grafana dashboards may not show NATS metrics. - You may need to configure external monitoring separately. Additionally: - Variables such as `NATS_BIND_IP` and `NATS_PORT_NUMBER` apply only to the bundled NATS service. - These variables do not affect external NATS deployments. --- ## Metrics for external services When you replace a bundled component with an external service, the monitoring stack cannot scrape metrics from that service. As a result, those metrics do not appear in the Grafana dashboards. To show them, deploy an exporter for the external service and point Prometheus to it. ### Step 1: Deploy a metrics exporter Deploy a metrics exporter for the external service, unless the service already provides its own exporter. The exporter exposes the service metrics in a format that Prometheus can scrape. ### Step 2: Update the Prometheus scrape configuration Add a new file under `files/prometheus/file_sd_configs.d` instead of editing the existing files under `files/prometheus/file_sd_configs`. This keeps your changes separate and avoids conflicts when the stack is updated. > [!NOTE] > Prometheus handles scrape failures gracefully for the exporters that ship with the stack, so the dashboards continue to work while you configure the external targets.