As of December 15, 2023, Rocket.Chat has ceased support for connections from cloud services and official mobile/desktop apps to workspaces running legacy versions outside our support window. Users on unsupported legacy servers are advised to upgrade to the latest Rocket.Chat version to ensure continued access to cloud, mobile, and desktop applications. Each Rocket.Chat version is supported for six months post-release.
Deploying Rocket.Chat using Docker and Docker Compose is a highly recommended deployment method for running Rocket.Chat due to its simplicity and flexibility.
In this guide, you'll learn how to:
Step 1: Install Docker, Docker Compose and Git
This guide is intended for Linux users. Users on macOS or Windows can install Docker Desktop instead.
Ensure you have Docker, Docker Compose (Docker Compose v2 is required) and Git installed and operational on your system. If you don't have them installed, you can conveniently set them up in Linux distributions with the command below:
curl -L https://get.docker.com | sh # Install Docker sudo apt install git # Install Git
For other OS or alternative installation methods, refer to the official Docker documentation and Git documentation.
To run Docker commands without using
sudo
, add your current user to the Docker group.Find your current username with this command:
whoami
Add your user to the docker group:
sudo usermod -aG docker $USER
You can replace $USER with the username from the previous step.
Finally, reboot the system to for the changes to take effect:
sudo reboot
If your server has an active firewall, you may need to whitelist specific URLs to allow communication with Rocket.Chat's cloud services (e.g., push notifications, marketplace). Refer to the Firewall Configuration documentation for the complete list of required URLs.
Step 2: Fetch the Rocket.Chat compose configuration files
The official rocketchat-compose repository contains all the configuration files you need to successfully deploy Rocket.Chat using Docker Compose.
Clone the repository using Git and navigate to the cloned directory:
git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git cd rocketchat-compose
This repository includes:
compose.yml
: The main configuration file for Docker Compose to deploy Rocket.Chat..env.example
: An example enviroment file for customizing your deployment.Additional configs: Other configuration files to support your deployment, such as Traefik (for reverse proxy and HTTPS) and monitoring tools.
To configure your deployment without editing the
compose.yml
, you’ll need a dedicated.env
file. Copy the example file to start your customization:cp .env.example .env
This command creates the
.env
file where you can now define your deployment variables, such as the desired Rocket.Chat version and your workspace URL.
Step 3: Configure Rocket.Chat
Before launching your Rocket.Chat workspace, you must configure some key variables in the .env
file you created. Start by opening the .env
file:
nano .env
Set Rocket.Chat version
Modify the RELEASE
variable to specify the exact version of Rocket.Chat you wish to deploy. Refer to the Rocket.Chat releases page for a list of available stable versions.
RELEASE=7.5.0
For production environments, it’s strongly recommended to specify a fixed version number (e.g., 7.5.0) instead of using
latest
. This prevents unexpected issues from automatic, breaking updates.
Configure access URLs
The next step is to configure the ROOT_URL
and DOMAIN
. These variables determine how users will access your Rocket.Chat workspace. Configuration differs based on whether you are running a local test or a public production instance.
If you are only testing Rocket.Chat locally on your machine and do not require external access or HTTPS, you can use the default values for these variables:
DOMAIN=localhost
ROOT_URL=http://localhost
Your workspace will be accessible at http://localhost:3000
once succesfully deployed.
For a publicly accessible and secure deployment, configure HTTPS using a domain name. Rocket.Chat's default configuration leverages Traefik, a reverse proxy that can automatically manage and generate free TLS/SSL certificates from Let's Encrypt.
Before proceeding, verify that your domain's A record (or optional CNAME record) is correctly pointed to the public IP address of the server where you are running Docker.
Update the following variables in your .env
file:
Field | Description | Example |
---|---|---|
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 |
LETSENCRYPT_EMAIL | Your valid email address for certificate renewal and security notifications from Let's Encrypt. | |
TRAEFIK_PROTOCOL | Set to | https |
Here is an example of the configuration:
DOMAIN=chat.example.com
ROOT_URL=https://chat.example.com
LETSENCRYPT_ENABLED=true
[email protected]
TRAEFIK_PROTOCOL=https
To use Nginx as a reverse proxy instead of Traefik, refer to Securing Rocket.Chat with Nginx.
Enable monitoring
The rocketchat-compose repository includes Grafana (for visualization) and Prometheus (for data collection) to provide a powerful, 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
).
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, follow these steps in the .env
file:
You can use the default values for the following variables:
GRAFANA_DOMAIN
: Leave this variable empty.GRAFANA_PATH
: Set this to your desired path, ensuring there is no trailing slash (e.g.,/grafana
).GRAFANA_DOMAIN= GRAFANA_PATH=/grafana
Set a strong password for the Grafana
admin
user by updating theGRAFANA_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 this up, follow these steps:
Verify that your subdomain's A record is correctly pointed to the public IP address of your server.
Open your
.env
file and configure the following Grafana variables:GRAFANA_DOMAIN
: Set this to your desired subdomain for accessing the Grafana dashboard. (e.g.,grafana.your-domain.com
).GRAFANA_PATH
: Leave this variable empty.GRAFANA_DOMAIN=grafana.your-domain.com GRAFANA_PATH=
Set a strong password for the Grafana
admin
user by updating theGRAFANA_ADMIN_PASSWORD
variable:GRAFANA_ADMIN_PASSWORD=your_secure_password
Step 4: Optional configurations
Here are some additional optional configurations you can add to your .env
file before launching Rocket.Chat:
External MongoDB connection: If you wish to use an existing or dedicated MongoDB instance (such as a managed service like MongoDB Atlas or a separately hosted deployment) instead of the bundled local database, configure the
MONGO_URL
in the.env
file like this:MONGO_URL=mongodb://<user>:<pass>@host1:27017,host2:27017,host3:27017/<databaseName>?replicaSet=<replicaSet>&ssl=true&authSource=admin
For production use, MongoDB must be deployed separately (non-containerized) and configured as a replica set.
Registration token: If you’ve received a registration token from our Sales team or Rocket.Chat Cloud, you can use it to automatically register your workspace upon initial startup. To do this, add the token to the
.env
file like this:REG_TOKEN=your_token_here
This step is optional, as you can also register the workspace through the setup wizard UI after deployment. Once the server successfully starts and registration is complete, the token is permanently stored in the database's cloud settings and is no longer required in the
.env
file. For security reasons, proceed to remove the token from your.env
file after the first successful deployment.
Step 5: 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:
compose.yml
: Starts the Rocket.Chat application.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.compose.monitoring.yml
: Enables monitoring with Prometheus (for collecting metrics) and Grafana (for visualizing them in dashboards).compose.traefik.yml
: Manages the Traefik reverse proxy, which handles secure routing and automatic HTTPS certificate generation from Let's Encrypt.
You can easily customize your deployment by including only the services you need. For example, if you did not configure monitoring or Traefik (e.g., you are using a separate Nginx proxy), you can omit those
.yml
files:docker compose -f compose.database.yml -f compose.yml up -d
To check that all services have successfully started, use this command to list all running containers:
docker ps
If you encounter issues during deployment, refer to the following resources for logging and troubleshooting:
Step 6: Access your Rocket.Chat workspace
Once your Rocket.Chat instance is deployed, you can access the workspace through your web browser to begin your final configuration:
For local testing: Go to
http://localhost:3000
.For production: Navigate to the
ROOT_URL
you configured in your.env
file (e.g.,https://your-domain.com
).
After the workspace loads, follow the on-screen prompts to create your first admin user and complete the initial workspace setup. Your workspace and email will be registered to the Rocket.Chat Cloud portal during this process.
Access monitoring dashboard
You can 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.
Step 7: Update file storage
Rocket.Chat stores file uploads using GridFS by default. While this doesn't require extra setup, it's not ideal for production because it increases database load and reduces scalability performance. Rocket.Chat highly recommends using a dedicated object storage service such as Amazon S3, Google Cloud Storage (GCS), or MinIO. Refer to the File Uploads guide for detailed instructions on configuring your preferred file storage solution.
Next steps
Great! You’ve successfully created your Rocket.Chat workspace with Docker and logged in. Next, explore the following resources to continue using your new workspace:
User Guides: Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users.
Workspace Administration: Administrators and owners can set and manage various configurations.
Marketplace: Explore the available apps to enhance your workspace.
Update Rocket.Chat with Docker
Before you proceed, consult the general guidelines for updating Rocket.Chat.
Updating the Rocket.Chat image will not affect your data, as it is stored persistently in the separate MongoDB service. Before updating to a new major Rocket.Chat release, confirm that your existing MongoDB version is compatible with the intended new release. See the MongoDB version requirements for more details.
To update your Rocket.Chat version, continue with the following steps:
Modify the
RELEASE
variable in the.env
file to point to the release tag of that version. Alternatively, you can edit thecompose.yml
file to point to the desired Rocket.Chat version.Changing version in
.env
In the
.env
file, change theRELEASE
value to your specified version.RELEASE=<desired version>
Changing version in
compose.yml
In the
compose.yml
file, change therocketchat
serviceimage
value to point to an image in the rocketchat registry image with a tag of your desired version.services: rocketchat: image:registry.rocket.chat/rocketchat/rocket.chat:<desired version>
Run the following command to pull the new image and restart the Rocket.Chat container:
docker compose -f compose.yml up -d
Refer to the official documentation for more details on Rocket.Chat Docker images.
Securing Rocket.Chat with Nginx and Let's Encrypt
This section details how to replace the default Traefik service with Nginx as a reverse proxy to secure your Rocket.Chat deployment with HTTPS, using a free TLS/SSL certificate from Let's Encrypt. This setup requires running Rocket.Chat locally so Nginx can handle all public-facing secure traffic.
We recommend using Traefik as it’s shipped with our official Docker image.
Prerequisites
Before starting, verify the following:
Your domain's A record (or optional CNAME record) is correctly pointed to your server’s public IP address.
You have completed Step 1 and Step 2 to fetch the official Rocket.Chat Docker Compose configuration files.
Deploy Rocket.Chat locally
The next step is to configure Rocket.Chat to run on localhost so that Nginx can act as the front-facing reverse proxy. Continue with these steps to run Rocket.Chat on http://localhost:3000
:
Verify the following variables in your
.env
file are set to these default values:DOMAIN=localhost ROOT_URL=http://localhost LETSENCRYPT_ENABLED=false [email protected] TRAEFIK_PROTOCOL=http GRAFANA_DOMAIN= GRAFANA_PATH=/grafana
Modify the
RELEASE
variable in.env
to specify the exact version of Rocket.Chat you wish to deploy. Refer to the Rocket.Chat releases page for a list of available stable versions.RELEASE=7.5.0
For production environments, it’s strongly recommended to specify a fixed version number (e.g., 7.5.0) instead of using
latest
. This prevents unexpected issues from automatic, breaking updates.Set a strong password for the Grafana
admin
user by updating theGRAFANA_ADMIN_PASSWORD
variable in.env
:GRAFANA_ADMIN_PASSWORD=your_secure_password
Start your Rocket.Chat services, explicitly omitting the Traefik configuration file (compose.traefik.yml):
docker compose -f compose.database.yml -f compose.monitoring.yml -f compose.yml up -d
Confirm that all necessary services have started successfully:
docker ps
Rocket.Chat should now be running locally on http://localhost:3000
.
Get an SSL certificate from Let's Encrypt
Use Let's Encrypt to get a free & open-source SSL certificate by following these steps:
Install
certbot
using the relevant package manager for your version of Linux. For Debian-based distributions such as Debian and Ubuntu use :sudo apt update sudo apt install certbot
For RPM-based distributions such as Redhat and Centos, use:
sudo yum install yum-utils sudo yum install nginx
The installation commands may vary based on your Linux distribution and version.
Obtain a certificate from Let's Encrypt by running this command (a second or more domains are optional):
sudo certbot certonly --standalone --email <[email protected]> -d <domain.com> -d <subdomain.domain.com>
Replace
<[email protected]>
and<domain.com>
with your actual email adress and domain names. If successful, your certificate files will be stored in/etc/letsencrypt/live/<your.domain.com>/
.
Configure Nginx web server with TLS/SSL
Now, link your domain to the Rocket.Chat service running locally on port 3000. Nginx will serve as the secure public entry point, handling HTTPS traffic on port 443 and directing requests to the local Rocket.Chat and Grafana services.
Install Nginx web server:
sudo apt-get install nginx
Backup the default config file for reference:
cd /etc/nginx/sites-available sudo mv default default.reference
Create a new site configuration for Rocket.Chat:
sudo nano /etc/nginx/sites-available/default
Paste the following in the new file:
server { listen 443 ssl; server_name <ABC.DOMAIN.COM>; #replace <ABC.DOMAIN.COM> with your domain name ssl_certificate /etc/letsencrypt/live/<ABC.DOMAIN.COM>/fullchain.pem; #replace <ABC.DOMAIN.COM> with your domain name ssl_certificate_key /etc/letsencrypt/live/<ABC.DOMAIN.COM>/privkey.pem; #replace <ABC.DOMAIN.COM> with your domain name ssl_protocols TLSv1 TLSv1.1 TLSv1.2; ssl_prefer_server_ciphers on; ssl_ciphers 'EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH'; root /usr/share/nginx/html; index index.html index.htm; # Make site accessible from http://localhost/ server_name localhost; location / { proxy_pass http://localhost:3000/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto http; proxy_set_header X-Nginx-Proxy true; proxy_redirect off; } # Grafana Reverse Proxy location /grafana { proxy_pass http://localhost:5050/grafana; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto https; # Crucial for secure path access proxy_set_header X-Nginx-Proxy true; proxy_redirect off; } } server { listen 80; server_name <ABC.DOMAIN.COM>; #replace <ABC.DOMAIN.COM> with your domain name return 301 https://$host$request_uri; }
Replace
ABC.DOMAIN.COM
with your domain name.Test the Nginx configuration to make sure there are no syntax errors:
sudo nginx -t
If the syntax test is successful, restart Nginx:
sudo systemctl restart nginx
If you have security group restrictions, allow TCP/22 from your current IP for SSH connections and TCP/443 from the IP you plan to use for access.
Access your workspace
Once your Rocket.Chat instance is deployed, you can access the workspace workspace securely at
https://<your-domain.com>
.
After the workspace loads, follow the on-screen prompts to create your first admin user and complete the initial workspace setup. Your workspace and email will be registered to the Rocket.Chat Cloud portal during this process.
Access monitoring dashboard
You can 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.
Great job! You have successfully enabled TLS on your Rocket.Chat workspace with Nginx.
Set Rocket.Chat deployment environment variable on Docker
Enviroment variables are additional settings that impacts your workspace deployment and configuration. Refer to the official documentation to learn more about Rocket.Chat deployment enviroment variables.
To set up an environment variable in Docker,
Open your compose.yml file:
nano compose.yml
Add the environment variable under the
environment
section of therocketchat
service. For example, to override the SMTP Host setting, add:services: rocketchat: ... environment: ... OVERWRITE_SETTING_SMTP_Host: "my.smtp.server.com"
Tip: This is the same section where
ROOT_URL
,MONGO_URL
, etc is defined.Restart your Rocket.Chat container to apply the changes:
docker compose stop rocketchat docker compose rm rocketchat docker compose up -d rocketchat
For a full list of available environment variables, refer to Deployment Environment Variables.
Additional steps
Rocket.Chat Docker images
You can use any of the following Docker images according to your needs:
Official image (stable and tested): The official Docker images repository is responsible for maintaining and controlling Rocket.Chat's official stable image through Docker. It is also reviewed by the Docker committee.
docker pull registry.rocket.chat/rocketchat/rocket.chat
Latest release image: This image holds the latest Rocket.Chat updates on the Docker repository. The release may be from the
develop
ormaster
branch. You can use this to test some of the latest updates.docker pull registry.rocket.chat/rocketchat/rocket.chat:latest
Using the
latest
image tag for production deployments is not recommended.
Specific release image: You can set up your Rocket.Chat workspace with a specific release image. Select the release you need from the Docker hub tags and use it to run the following command:
docker pull registry.rocket.chat/rocketchat/rocket.chat:<release-tag>
Bleeding-edge untested develop build image: This is an image maintained at Rocket.Chat's Docker repository. This update comes from the develop (untested) branch, which contains the latest updates for those who want to work with the newest features.
docker pull registry.rocket.chat/rocketchat/rocket.chat:develop
Back up and restore MongoDB data using Docker
Rocket.Chat stores all workspace data in MongoDB. Follow the steps in the commands below to back up and restore your database when running in Docker.
Back up your MongoDB database in Docker
List all running Docker containers to find the name of your MongoDB service
docker ps -a
Take note of your mongo container name (e.g.,
rocketchat-mongodb-1
)Run this command to dump the database into a binary file
db.dump
:docker exec <container_name> sh -c 'mongodump --archive' > db.dump
When successful, you should see
db.dump
file in the current directory.
Restore MongoDB database backup in Docker
To restore the data, use mongorestore inside the MongoDB container, piping the data from your local db.dump file.
docker exec -i <container_name> sh -c 'mongorestore --archive' < db.dump
Export to an external database (e.g., MongoDB Atlas)
If you are migrating your data or performing an offline restore, you can use the local db.dump
file directly with an external MongoDB connection string.
mongorestore --uri mongodb+srv://<user>:<password>@cluster0.w2btl.mongodb.net --archive=db.dump
Monitoring and logging your deployment
Effective logging helps you monitor the health and status of your Rocket.Chat deployment. This section covers logging for Rocket.Chat, MongoDB, and reverse proxies like Traefik or Nginx.
Logging Rocket.Chat
To check the status and logs of your Rocket.Chat container, follow these steps:
Use any of the following commands to list containers running in your Docker environment:
docker ps # Shows currently running containers with details like ID, status, and ports docker ps -a # Lists all containers, including stopped ones docker ps -q # Displays only container IDs for a concise view docker compose ps # Lists services managed by Docker Compose
Once you identify your Rocket.Chat container, you can inspect its logs using any of these commands:
docker compose logs -f <Service_Name> # If using Docker Compose, this follows real-time logs docker logs <Container_Name> # Displays logs for the specific Rocket.Chat container docker logs -f <Container_Name> # Shows real-time logs (follow mode) docker logs --tail 10 <Container_Name> # Displays the last 10 lines of logs
Note:
Replace
<Container_Name>
and<Service_Name>
with the appropriate values such asdocker compose logs -f rocketchat
.Rocket.Chat logs to stdout, so there isn't a specific log file within the container. The Docker logging system captures these stdout logs, making them accessible through the docker logs command
Logging MongoDB
MongoDB is a crucial part of your Rocket.Chat deployment. Monitoring its logs can help identify database-related issues.
View MongoDB logs by running any of these commands:
docker logs -f <MongoDB_Container_Name> # View real-time logs docker logs --tail 20 <MongoDB_Container_Name> # Show the last 20 log lines docker compose logs -f mongodb # If using Docker Compose
To inspect MongoDB’s health, run:
docker exec -it <MongoDB_Container_Name> mongosh --eval "db.runCommand({ serverStatus: 1 })"
This returns detailed server status information.
Replace
<Container_Name>
with the appropriate values.
Logging reverse proxy (Traefik or Nginx)
If you use a reverse proxy, checking its logs can help diagnose connectivity and SSL issues.
If Traefik is handling requests, check its logs with:
docker logs -f <Traefik_Container_Name> # Show real-time logs docker logs --tail 50 <Traefik_Container_Name> # Show the last 50 log lines
If using Nginx as a reverse proxy, logs are stored inside the container at
/var/log/nginx/
. To view logs, run:sudo tail -f /var/log/nginx/access.log # Access logs sudo tail -f /var/log/nginx/error.log # Error logs
Encountering issues with your deployment? See the Deployment FAQ for detailed troubleshooting assistance.
Congratulations on successfully deploying Rocket.Chat using Docker! You can now effortlessly communicate with your team members in your workspace. Visit the accessing your workspace guide to configure your workspace and onboard other team members.