---
title: "Rocket Chat MongoDB URI Authentication Setup"
slug: "mongodb-uri-authentication"
description: "Configure MongoDB URI authentication for Rocket Chat. Secure messaging and collaboration with reliable, scalable open source deployment practices."
updated: 2026-05-08T14:27:03Z
published: 2026-05-08T17:31:00Z
canonical: "docs.rocket.chat/mongodb-uri-authentication"
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.

# MongoDB URL Authentication

Rocket.Chat connects to a MongoDB instance using a [MongoDB connection string URL](https://www.mongodb.com/docs/manual/reference/connection-string/). Authentication is handled via the username and password included in that string.

## Set the connection string

Add the `MONGO_URL` environment variable to your `.env` file using the following format:

```yaml
MONGO_URL=mongodb://[username:password@]host1[:port1][,...hostN[:portN]][/[defaultauthdb][?options]]
```

Depending on the characters in your password, you may need to percent-encode certain values. Refer to the [MongoDB connection string documentation](https://docs.mongodb.com/manual/reference/connection-string/) for details.

## Configuring the connection

**Using docker-compose**

In your `docker-compose.yml` file, pass `MONGO_URL` under the `environment` key:

```yaml
environment:
      - "MONGO_URL=mongodb://rctestuser:mymongopassword@mongo:27017/rocketchat?authSource=admin"
```

**Using docker run**

If you are starting the container with `docker run`, pass the variable using the `-e` flag:

```bash
docker run \
-e "MONGO_URL=mongodb://rctestuser:mymongopassword@mongo:27017/rocketchat?authSource=admin" \
rocketchat/rocket.chat:X.X.X
```

## Replica set connection

If your MongoDB deployment uses a replica set, include all member hosts in the connection string and specify the replica set name as a query parameter.

**Using docker-compose**

```yaml
environment:
  - "MONGO_URL=mongodb://rctestuser:mymongopassword@mongo1:27017,mongo2:27017,mongo3:27017/rocketchat?replicaSet=rs0&authSource=admin"
```

**Using docker run**

```bash
docker run \
-e "MONGO_URL=mongodb://rctestuser:mymongopassword@mongo1:27017,mongo2:27017,mongo3:27017/rocketchat?replicaSet=rs0&authSource=admin" \
rocketchat/rocket.chat:X.X.X
```

Replace `X.X.X` with your [desired Rocket.Chat release](https://github.com/RocketChat/Rocket.Chat/releases).

> [!NOTE]
> Ensure that all hosts listed in the connection string are members of the same replica set, and that the replica set name matches the one configured in your MongoDB deployment.