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 with Docker and Docker-compose is a straightforward and highly recommended deployment method due to its simplicity and flexibility. This guide will walk you through the essential steps, whether you're a seasoned Docker expert or new to containerization, ensuring a smooth deployment for your Rocket.Chat workspace.

In this guide, you'll learn how to:

• Deploy Rocket.Chat on Docker

• Update Rocket.Chat on Docker

• Docker Mongo backup and restore

• Set Rocket.Chat deployment environment variable

Step 1: Install Docker, Docker Compose and Git

This guide is intended for Linux users. If you're using macOS or Windows, follow the Docker Desktop installation instructions for macOS or Windows instead.

1. Ensure you have Docker, Docker Compose (Docker Compose v2 is required) and Git installed and operational.

   If you don't have them installed, you can conveniently set them up in Linux environments using Docker's official helper script:

   curl -L https://get.docker.com | sh # Install Docker
   sudo apt install git # Install Git

   For other operating systems or for different 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. If you are unsure who the user is, run:

   whoami

   Then use the following command, replacing $USER with the output from the above:

   sudo usermod -aG docker $USER
   sudo reboot

   If you are using a firewall, you may need to whitelist some URLs to communicate with our cloud services. See Firewall Configuration for the complete list.

Step 2: Fetch the Rocket.Chat compose configuration

All the necessary configuration files for you to deploy Rocket.Chat via Docker successfully are available in the official rocketchat-compose repository.

1. Clone the official rocketchat-compose repository using Git:

   git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git

2. Then change into the cloned directory:

   cd rocketchat-compose

   This repository includes the compose.yml , .env.example file and other configuration files required for setting up your Rocket.Chat instance.

3. To customize your deployment without directly editing the compose.yml file, you will use a .env file to define the deployment configurations. Copy the example environment file:

   cp .env.example .env

   This command creates a new .env file where you can define your deployment configurations such as the Rocket.Chat version, workspace URL, and optional HTTPS configuration.

Step 3: Configure Rocket.Chat

Before launching your Rocket.Chat workspace, you must configure some few key variables in the .env file you created.

1. First, open the .env file:

   nano .env

2. Set the RELEASE variable to the desired Rocket.Chat version you want to deploy. For production environments, it's highly recommended to avoid using latest and specify a version (e.g., 7.5.0) to ensure stability.

   RELEASE=7.5.0

   See Rocket.Chat releases for available versions.

3. Configure the ROOT_URL and DOMAIN to specify how your workspace is accessed, depending on whether you're in a local test or a production environment.

DOMAIN=localhost
ROOT_URL=http://localhost

DOMAIN=chat.example.com
ROOT_URL=https://chat.example.com
LETSENCRYPT_ENABLED=true
[email protected]
TRAEFIK_PROTOCOL=https

Step 4: Enable monitoring

The default rocketchat-compose repository  includes Grafana and Prometheus to provide a powerful, out-of-the-box monitoring solution for your workspace. This 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 path (e.g., https://your-domain.com/grafana) or a subdomain (e.g., https://grafana.your-domain.com).

Step 5: Optional configurations

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

1. MongoDB connection: If you want to use an existing MongoDB instance (e.g., MongoDB Atlas) instead of the bundled database, add the MONGO_URL with your connection string to your .env file:

   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 register your workspace automatically. To do this, add the token to the .env file like this:

   REG_TOKEN=your_token_here

   This step is optional because you can also register your workspace during configuration after deployment. Once registration is complete (confirmed when server starts), the token is no longer needed. If stored in the .env file, it can be removed as the registration is stored in the database clould settings.

Step 6: Start Rocket.Chat

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

1. Run the following command to download the required Docker images and start the Rocket.Chat container with its supporting services:

   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 itself and its core database, MongoDB.

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

2. To check if all the containers are running, run the following command:

   docker ps

You can customize your deployment by including only the services you need. For example, if you're not using monitoring or the Traefik reverse proxy, you can simply omit those  .yml files from the command.

docker compose -f compose.database.yml -f compose.yml up -d

If you encounter issues during deployment, refer to the following resources for logging and troubleshooting:

• Logging Rocket.Chat

• Deployment FAQ

• MongoDB best practices

Step 7: Access your Rocket.Chat workspace

Once your Rocket.Chat instance is deployed, you can access it through your web browser.

• 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 complete the initial setup and configuration of your workspace. During this process, your workspace and email will be registered to the Rocket.Chat Cloud portal, where you can manage your subscriptions.

Access monitoring dashboard

If you enabled monitoring, 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.

Next steps

Great! You’ve successfully created your Rocket.Chat workspace with Docker and logged in. Next, check out the following documents to get started:

• 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 on Docker

• Before you proceed, see the general guidelines for updating Rocket.Chat.

• Updating the Rocket.Chat image doesn't affect your data since it exists in the Mongo image. Before proceeding with the update, ensure that the version of your MongoDB is compatible with the intended release.

Using Docker & Docker compose, you can update your rocketchat docker image to the latest or preferred version of Rocket.Chat. To update your Rocket.Chat version,

1. For a specific version, modify the RELEASE variable in the .env file to point to the Docker image 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. Now, restart the rocketchat service with this command

   docker compose -f  compose.yml up -d

See the official documentation for more details on Rocket.Chat Docker images.

Enable HTTPS with Nginx for your Rocket.Chat workspace

Enabling HTTPS is crucial for securing your Rocket.Chat workspace. While the official Rocket.Chat Compose repository ships with Traefik for this purpose, you can also use Nginx as a reverse proxy to secure your deployment with a free TLS/SSL certificate from Let's Encrypt.

We recommend using Traefik as it’s shipped with our official Docker image.

Prerequisites

1. A public domain with an A record pointing to your Rocket.chat’s server IP.

2. Rocket.Chat must be running 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 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 <[email protected]> -d <domain.com> -d <subdomain.domain.com>

Configure Nginx web server with TLS/SSL

Rocket.Chat is usually set to run on port 3000 by default. However, you can make it more accessible to your users by using Nginx as a reverse proxy. This will link your domain name to the Rocket.Chat server running on that port. By doing this, your users can access your workspace through your domain name instead of directly using the port in the URL. Follow these steps:

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;
        }
    }
    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.

Open a web browser and access your Rocket.Chat workspace securely at https://your-domain.com, using the actual domain name you configured.

Great job! You have successfully enabled HTTPs 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

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:

   docker exec -it <Nginx_Container_Name> cat /var/log/nginx/access.log  # Access logs  
   docker exec -it <Nginx_Container_Name> cat /var/log/nginx/error.log   # Error logs  

   To continuously monitor logs in real-time, run:

   docker exec -it <Nginx_Container_Name> tail -f /var/log/nginx/access.log  

Docker Mongo backup and restore

To back up your MongoDB database in Docker

• Run the following command on your terminal to list out all running containers:

  docker ps -a

  Take note of your mongo container name.

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

To restore the backup

Run the following command:

docker exec -i <container_name> sh -c 'mongorestore --archive' < db.dump

You can export your database dump directly to MongoDB Atlas by simply running

mongorestore --uri mongodb+srv://<user>:<password>@cluster0.w2btl.mongodb.net --archive=db.dump

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.

Encountering issues with your deployment? See the Deployment FAQ for more details on troubleshooting.