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.

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.

Prerequisites

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.

Example: Standard replica set

MONGO_URL=mongodb://USERNAME:PASSWORD@mongo1.example.com:27017,mongo2.example.com:27017/rocketchat?replicaSet=rs0&authSource=admin

Example: MongoDB Atlas (SRV)

MONGO_URL=mongodb+srv://USERNAME:PASSWORD@cluster0.xxxxx.mongodb.net/rocketchat?retryWrites=true&w=majority

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.

Example: 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.

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:

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, or when your infrastructure already provides one.

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.

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

NATS_URL=monolith+nats://YOUR_NATS_HOST:4222

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 without the bundled NATS service:

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.

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.