Deploy with Docker & Docker Compose

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:

• Deploy Rocket.Chat using Docker Compose

• Update Rocket.Chat to a newer version

• Back up and restore your MongoDB database

• Configure Rocket.Chat using environment variables

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.

1. 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.

2. To run Docker commands without using sudo, add your current user to the Docker group.

   1. Find your current username with this command:

      whoami

   2. Add your user to the docker group:

      sudo usermod -aG docker $USER

      You can replace $USER with the username from the previous step.

   3. 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.

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

   1. compose.yml : The main configuration file for Docker Compose to deploy Rocket.Chat.

   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.

2. 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.

DOMAIN=localhost
ROOT_URL=http://localhost

DOMAIN=chat.example.com
ROOT_URL=https://chat.example.com

LETSENCRYPT_ENABLED=true
LETSENCRYPT_EMAIL=demo@email.com
TRAEFIK_PROTOCOL=https

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).

Step 4: Optional configurations

Here are some additional optional configurations you can add to your .env file before launching Rocket.Chat:

1. 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.

2. 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.

1. 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.

   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

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

• Logging Rocket.Chat

• Deployment FAQ

• MongoDB best practices

Step 6: Access your Rocket.Chat workspace

1. 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).

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

1. Modify the RELEASE variable in the .env file to point to the release tag of that version. Alternatively, you can edit the compose.yml file to point to the desired Rocket.Chat version.

   Changing version in .env

   In the .env file, change the RELEASE value to your specified version.

   RELEASE=<desired version>

   Changing version in compose.yml

   In the compose.yml file, change the rocketchat service image 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>

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

1. Your domain's A record (or optional CNAME record) is correctly pointed to your server’s public IP address.

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

1. Verify the following variables in your .env file are set to these default values:

   DOMAIN=localhost
   ROOT_URL=http://localhost
   LETSENCRYPT_ENABLED=false
   LETSENCRYPT_EMAIL=demo@email.com
   TRAEFIK_PROTOCOL=http
   GRAFANA_DOMAIN=
   GRAFANA_PATH=/grafana

2. 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.

3. Set a strong password for the Grafana admin user by updating the GRAFANA_ADMIN_PASSWORD variable in .env:

   GRAFANA_ADMIN_PASSWORD=your_secure_password

4. 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

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

1. 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.

2. Obtain a certificate from Let's Encrypt by running this command (a second or more domains are optional):

   sudo certbot certonly --standalone --email <emailaddress@email.com> -d <domain.com> -d <subdomain.domain.com>

   Replace <emailaddress@email.com> 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.

1. Install Nginx web server:

   sudo apt-get install nginx

2. Backup the default config file for reference:

   cd /etc/nginx/sites-available
   sudo mv default default.reference

3. Create a new site configuration for Rocket.Chat:

   sudo nano /etc/nginx/sites-available/default

4. 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.

5. Test the Nginx configuration to make sure there are no syntax errors:

   sudo nginx -t

6. 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

1. Once your Rocket.Chat instance is deployed, you can access the workspace workspace securely at https://<your-domain.com> .

2. 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,

1. Open your compose.yml file:

   nano compose.yml

2. Add the environment variable under the environment section of the rocketchat 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.

3. 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 or master 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

1. 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 )

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

1. 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  

2. 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 as docker 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.

1. 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  

2. 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.

1. 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 

2. 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.