Update Rocket.Chat Compose Configuration

As of August 2025, the official rocketchat-compose repository has been updated to standardize Docker-based deployments. This updated configuration integrates a simplified Traefik setup for reverse proxying, NATS for internal messaging, and a Prometheus/Grafana stack for monitoring. Adopting this new architecture reduces the complexity of managing your deployment, allowing you to focus on your workspace while relying on officially maintained configurations for critical services such as NATs, Grafana, and Prometheus. This guide walks you through migrating an existing deployment to the updated rocketchat-compose setup while preserving all your existing data.

Step 1: Backup data and prepare your environment

Before making any changes, you must take a full MongoDB backup to ensure your data is safe.

List your running containers and copy the ID of your MongoDB container.
```
docker ps
```
Navigate to your current deployment directory. This should be the directory containing your existing compose.yml.
```
cd <path-to-old-compose-directory>
```
Execute a MongoDB dump to create a complete backup file locally named db.dump:
```
docker exec -i <mongodb-conatiner-id> mongodump --archive > db.dump
```
Replace <mongodb-conatiner-id> with the ID copied in step 1. This file is crucial for recovery if you encounter any data loss during the migration.
Stop all the running continers for your current deployment:
```
docker compose down
```
To archive the old setup where your current deployment was running, go to the parent directory and rename the folder :
```
cd .. 
mv "<old-folder-name>" "<old-folder-name>_backup"
```
The new setup will reuse the original folder name, so this rename is required.

Step 2: Set up the new Docker compose repository

The next step is to clone the official rocketchat-compose repository and migrate your existing configurations.

Clone the repository into a new directory with the same name as your old setup:
```
git clone https://github.com/RocketChat/rocketchat-compose "<old-folder-name>"
```
This directory now includes:
1. compose.yml : The core Rocket.Chat service.
2. .env.example : An example enviroment file for customizing your deployment.
3. Additional configs: Other configuration files to support your deployment, such as Traefik (for reverse proxy and HTTPS) and monitoring tools.
Copy your previous .env file into the new directory to retain your previous configurations:
```
cd "<old-folder-name>"
cp "../<old-folder-name>_backup/.env" .
```
Replace <old-folder-name> with the name of your previous setup directory to point to the correct backup path.

Update the .env file to verify the following variables are correctly set or added:

Variable	Description	Example value
RELEASE	The specific Rocket.Chat version to deploy.	7.12.0
DOMAIN	Your public domain or subdomain name. Do not include https:// or any trailing slashes.	chat.example.com
ROOT_URL	The complete URL your users will use to access the server, including the secure protocol (https://).	https://chat.example.com
LETSENCRYPT_ENABLED	Set to `true` to enable Traefik to automatically obtain and renew certificates.	true
LETSENCRYPT_EMAIL	Your valid email address for certificate renewal and security notifications from Let's Encrypt.	demo@email.com
TRAEFIK_PROTOCOL	Set to `https` to ensure secure connections are enforced by the proxy.	https

Step 3: Enable monitoring

The rocketchat-compose repository includes Prometheus for collecting workspace metrics and Grafana dashboards to visualize these metrics, providing an out-of-the-box monitoring solution for your workspace. This setup allows you to visualize key metrics, track performance, and gain insights into the health of your Rocket.Chat instance.

You can choose to access Grafana either through a URL path (e.g., https://your-domain.com/grafana) or a subdomain (e.g., https://grafana.your-domain.com).

Grafana via a path

Grafana via a subdomain

This option is ideal for local development or if you prefer to keep all services under a single domain, accessing your Grafana dashboard as a subdirectory (e.g., https://your-domain.com/grafana).

To configure this, update your .env file following these steps:

Add the following variables:
```
GRAFANA_DOMAIN=
GRAFANA_PATH=/grafana
```
Set a strong password for the Grafana admin user by adding the GRAFANA_ADMIN_PASSWORD variable:
```
GRAFANA_ADMIN_PASSWORD=your_secure_password
```

Accessing your Grafana dashboard through a dedicated subdomain is the recommended approach for production environments, as it provides a cleaner and more secure access point.

To set it up, continue with these steps:

Point your subdomain's A Record to your Rocket.Chat public server IP.
Add these variables to the .env file:
1. GRAFANA_DOMAIN: Set this to your desired subdomain for accessing the Grafana dashboard. (e.g., grafana.your-domain.com).
2. GRAFANA_PATH: Leave this variable empty.
3. GRAFANA_ADMIN_PASSWORD: Set a strong password for the Grafana admin user.
```
GRAFANA_DOMAIN=grafana.your-domain.com
GRAFANA_PATH=
GRAFANA_ADMIN_PASSWORD=your_secure_password
```

Step 4: Launch the Rocket.Chat deployment

With your .env file configured and saved, you're ready to start your Rocket.Chat workspace.

Run the following command to download the all required Docker images (Rocket.Chat, MongoDB, Traefik, etc.) and start the containers in the background:
```
docker compose -f compose.database.yml -f compose.monitoring.yml -f compose.traefik.yml -f compose.yml up -d
```
Here’s a brief summary of what each file in the command does:
1. compose.yml: Starts the Rocket.Chat application.
2. compose.database.yml: Manages MongoDB, the database that Rocket.Chat relies on. It also includes NATS, an internal message broker used for communication between services.
3. compose.monitoring.yml: Enables monitoring with Prometheus (for collecting metrics) and Grafana (for visualizing them in dashboards).
4. compose.traefik.yml: Manages the Traefik reverse proxy, which handles secure routing and automatic HTTPS certificate generation from Let's Encrypt.
To check that all services have successfully started, use this command to list all running containers:
```
docker ps
```

Step 5: Access your Rocket.Chat workspace and monitoring dashboard

Once your Rocket.Chat workspace is deployed, you can visit your workspace URL to verify that all your data is intact. You can also access the Grafana dashboard at the path or subdomain you configured in your .env file (e.g., https://your-domain.com/grafana or https://grafana.your-domain.com).

To log in to your Grafana dashboard, use the following credentials:

User: admin
Password: The password you set in the GRAFANA_ADMIN_PASSWORD variable in your .env file.
The GRAFANA_ADMIN_PASSWORD you set in the .env file is only applied once during the first setup of the container. To update your password later, you must change it directly within your Grafana user preferences.

With the migration complete, your workspace now runs on the updated rocketchat-compose configuration. To restore your MongoDB data, refer to Restore MongoDB backup in Docker. If you encounter issues during deployment, see Deploy with Docker & Docker Compose for details on how the updated setup works and common troubleshooting steps.