Deploy a Federated Rocket.Chat Workspace with Docker

This page guides you through the steps to set up your federated Rocket.Chat workspace using Docker following any of these methods:

• Automated installation: Install Synapse and Rocket.Chat using a simple setup script.

• Manual installation: Manually install and configure your Homeserver with Rocket.Chat.

In the installation methods, we are using Element and Traefik, along with Matrix, to configure a federated workspace.

We recommend using automated installation since this comes with some pre-configurations.

System requirements

• 8GB of RAM

• 2CPU

• 20GB of Storage

• Ubuntu 20.04

You are required to have a domain available to host your matrix homeserver.

Important warning about the installation

You must be aware of this vital setting before proceeding with the installation.

• Enabling ephemeral events like user typing indicator can affect the performance of your Matrix Homeserver and Rocket.Chat server for federated communication. This can be enabled by adding the following property in your Application Service configuration file:

de.sorunome.msc2409.push_ephemeral: true

• Add and enable the following properties to make public rooms visible and searchable on other Matrix networks.

allow_public_rooms_without_auth: true

allow_public_rooms_over_federation: true

• Following the automated installation enables everything by default and can be disabled by editing the generated configuration at data/matrix/synapse.

• You must use the Synapse version 1.8.x and above.

Automated installation

The automated install offers a simple option to install a matrix homeserver pre-configured with Rocket.Chat.

Prerequisites

You are required to have the following on your system before installing.

• A domain pointing to your server's IP.

• Docker and Docker compose (> 2.3.3)

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

curl -L https://get.docker.com | sh

To run Docker commands without using sudo, add the current user to the Docker group and then reboot using the following commands:

sudo usermod -aG docker $USER

sudo reboot

Installation steps

1. Open your terminal in any directory of your choice

2. Download and execute the script by running the following command. This creates a docker-compose and a .env file that can be edited as needed.

   bash <(curl -L -s https://go.rocket.chat/i/federation-setup)

3. Follow the instructions provided by the script to configure the workspace:

   1. Server's hostname: Add your domain name.

   2. Create A domain records pointing to your server's IP address as requested.

      1. synapse.<your-domain>

      2. element.<your-domain>

      3. traefik.<your-domain>

   3. Enter your email address. This is used to issue an SSL certificate for your domain.

4. To install a specific version of Rocket.Chat, navigate to the .env file, and replace these variables as shown below:

   RC_IMAGE=registry.rocket.chat/rocketchat/rocket.chat:x.x.x
   
   ROCKETCHAT_IMAGE_TAG=x.x.x

Replace x.x.x with the docker image tag of your preferred version.

5. Start the container by running the following command:

   docker compose up -d

Test the setup

To test and ensure your Matrix setup is successful, download and execute the test script in the same directory where the setup was initiated using the following command:

bash <(curl -L -s https://go.rocket.chat/i/federation-test)

You get a notice about the setup status. This concludes the automated setup. Access your federated workspace at the domain! By default, the first user to log in is the workspace administrator.

Next steps

Now that your federated workspace is ready, you can:

• View the configuration details from Administration > Workspace > Settings > Federation.

• Allow or Block specific IP addresses to communicate with your workspace.

• Go to the Federation User Guide to learn how to invite external users, join channels on the Matrix network, etc.

• Installing with the automated setup automatically sets the values at Administration > Workspace > Settings > Federation > Matrix Bridge.

• Rocket.Chat Matrix setup CLI is coming soon!

The following section guides you through the manual installation steps for a federated workspace.

Standalone Manual installation

Prerequisites

• Docker

If you don't have it installed, you can conveniently set it up using Docker's official helper script:

curl -L https://get.docker.com | sh

• To run Docker commands without using sudo, add the current user to the Docker group and then reboot using the following commands:

sudo usermod -aG docker $USER

sudo reboot

• Your domain records and SSL certificates. For example, if your domain is ps-rocketchat.com, you can create subdomains under it like matrix2.ps-rocketchat.com.

Name the subdomains based on your preference.

• All the generated DNS records pointed to your server's IP address (the same IP address).

Installation steps

To set up a Matrix Homeserver with Synapse manually,

Replace ps-rocketchat.com and matrix2.ps-rocketchat.com with your domain and subdomain respectively while following this guide.

• Set up the docker network with this command:

docker network create rocketchat

• To set up a server, run this command to set up the Synapse environment:

docker run --rm -e SYNAPSE_SERVER_NAME=ps-rocketchat.com -e SYNAPSE_REPORT_STATS=yes -v $PWD/data:/data matrixdotorg/synapse generate

The homeserver.yaml configuration file is stored in the "data" directory of your current working directory. To start the Synapse Docker, use this command:

docker run --name synapse --network rocketchat -v $PWD/data:/data:rw -d matrixdotorg/synapse

• Next, set up MongoDB with this command:

docker run --network rocketchat -d     --name "mongodb"     -e ALLOW_EMPTY_PASSWORD=yes -e MONGODB_REPLICA_SET_MODE=primary     -e MONGODB_REPLICA_SET_NAME=rs0 -e MONGODB_PORT_NUMBER=27017     -e MONGODB_INITIAL_PRIMARY_HOST="mongodb" -e MONGODB_INITIAL_PRIMARY_PORT_NUMBER=27017     -e MONGODB_ADVERTISED_HOSTNAME="mongodb" bitnami/mongodb:5.0

• To start Rocket.Chat, execute this command:

docker run --network rocketchat -d 	--name "rocketchat" 	-e ROOT_URL=https://ps-rocketchat.com -e PORT=3000 	-e MONGO_URL=mongodb://mongodb:27017/rocketchat?replicaSet=rs0 -e MONGO_OPLOG_URL=mongodb://mongodb:27017/local?replicaSet=rs0 	registry.rocket.chat/rocketchat/rocket.chat

Set up reverse proxy

Before accessing your Rocket.Chat workspace, set up the reverse proxy following the next steps:

• Obtain SSL certificates for your domain records, if you don't have any. You can use Lets Encrypt.

• Create an nginx.conf file containing forwarding rules for each domain. Create the file in the same folder where you intend to start your docker instance and paste the following contents:

Update your domain, subdomain, and the paths to your SSL certificate and key.

worker_processes 1;
events { worker_connections 1024; }
http {
    server {
	listen 443 ssl;
	server_name ps-rocketchat.com;
	ssl_certificate /cert/certificate.crt;
        ssl_certificate_key /cert/private.key;
	add_header X-Frame-Options DENY;
	add_header X-Content-Type-Options nosniff;
	add_header X-XSS-Protection "1; mode=block";
        location /.well-known/matrix/server {
            default_type application/json;
            add_header Access-Control-Allow-Origin *;
	    return 200 '{"m.server": "matrix2.ps-rocketchat.com:443"}';
	}
        location /.well-known/matrix/client {
            default_type application/json;
            add_header Access-Control-Allow-Origin *;
            return 200 '{"m.homeserver": {"base_url": "https://matrix2.ps-rocketchat.com"}}';
        }
        location / {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://rocketchat:3000;
        }
   }
   server {
    listen 80;
    server_name ps-rocketchat.com;
    return 302 https://$server_name$request_uri;
   }
    
   server {
    listen 443 ssl;
    server_name matrix2.ps-rocketchat.com;
    ssl_certificate /cert/certificate.crt;
    ssl_certificate_key /cert/private.key;
	add_header X-Frame-Options DENY;
	add_header X-Content-Type-Options nosniff;
	add_header X-XSS-Protection "1; mode=block";
    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://synapse:8008;
    }
  }
}

• Start the reverse proxy mapping the nginx.conf and the certificate and private key for SSL by running this command:

  Ensure to specify the paths to certificates if you are using relative paths. In this example, the reference location for certificates is the home folder.

  Additionally, it's recommended to use the complete directory path for your nginx file, for example — /home/ubuntu/test/nginx.conf:/etc/nginx/nginx.conf:ro

  docker run --name nginx --network rocketchat -p 443:443 -p 80:80 -v ./nginx.conf:/etc/nginx/nginx.conf:ro -v ./cert2/fullchain.pem:/cert/certificate.crt:ro -v ./cert2/privkey.pem:/cert/private.key:ro -d nginx

Visit your domain URL in a web browser to access your Rocket.Chat workspace. Complete the Rocket.Chat Setup Wizard and your workspace will be set up and ready to use.

Configure Rocket.Chat Matrix Bridge

Before you proceed, subscribe to any of our premium plans or apply trial on your workspace to unlock all the available federation features.

See Matrix Bridge Configuration to learn more about the configurations and their definitions.

Now that your workspace is set up, navigate to Administration > Workspace > Settings > Federation > Matrix Bridge and follow these steps:

• Enable Matrix Bridge.

• Update the following fields with these values:

  • Homeserver URL: http://synapse:8008

  • Homeserver Domain: <your domain>

  • Bridge URL: http://rocketchat:3300

Be cautious not to include "https://" before your homeserver domain.

• Save your changes and copy the contents of your registration file.

  

• Configure the support for Application Service on the matrix home server by creating a registration.yaml file in the data directory that was created for synapse earlier and paste the contents of the registration file.

• Creating and modifying files in the data directory may require administrative(sudo) rights.

• For Synapse versions 1.9 and higher, the registration.yaml file must include the following line:

  • use_appservice_legacy_authorization: true

• Add the following content at the end of the homeserver.yaml file in that same data directory and save:

app_service_config_files:

  - /data/registration.yaml

• Now restart the rocketchat and synapse containers with these commands:

docker restart synapse

docker restart rocketchat

Now, you can proceed to test your workspace setup. To run multiple Rocket.Chat instances, see Clustered Manual Installation .

Testing your setup

For testing the Matrix setup, you can use the Matrix Federation Tester if your certificates are from a “standard” CA recognized by Linux distros, etc.

For more real-time testing, visit Element and complete these steps:

• Create a user using matrix.org as a homeserver (assuming the default whitelisted matrix.org is still set on your matrix homeserver)

• Start a direct message from your Rocket.Chat workspace with the user you just created using their matrixId (@username:matrix.org).

• Check Element to confirm that you received the DM from your Rocket.Chat user. You can choose to respond to the message from Element and confirm that you can receive the response in your Rocket.Chat workspace.

Now that your federated is successful on your workspace, see the Federation User Guide  to learn more about how to use federation.

Use your own federation-tester

If you're in an air-gapped environment or use non-standard certificates, you can decide to use your own federation tester.

• Download the GitHub project locally and run the test yourself from (supposing you have the CA in your keychain) using these commands:

  git clone https://github.com/matrix-org/matrix-federation-tester.git
  
  cd matrix-federation-tester 
  
  go build
  
  BIND_ADDRESS=:8080 ./matrix-federation-tester

• Now, execute this command:

  curl 'http://localhost:8080/api/report?server_name=ps-rocketchat.com'

Clustered manual installation

To distribute the work on Rocket.Chat, you run two identical Rocket.Chat applications ( can be named rocketchat1 and rocketchat2) that both connect to the same MongoDB. To make this setup accessible externally, you use an NGINX load balancer. This load balancer acts as a single entry point, and internally it distributes the workload between the two Rocket.Chat instances.

Before you proceed, ensure you have completed the Standard Manual Installation.

• Start the second Rocket.Chat with this command:

docker run --network rocketchat -d 	--name "rocketchat2" 	-e ROOT_URL=https://ps-rocketchat.com -e PORT=3000 	-e MONGO_URL=mongodb://mongodb:27017/rocketchat?replicaSet=rs0 -e MONGO_OPLOG_URL=mongodb://mongodb:27017/local?replicaSet=rs0 	registry.rocket.chat/rocketchat/rocket.chat

• Update the nginx.conf file with these contents:

worker_processes 1;

events { worker_connections 1024; }

http {

    upstream web-rocketchat {
        ip_hash;
        server rocketchat:3000;
        server rocketchat2:3000;
    }

    upstream matrix-rocketchat {
        server rocketchat:3300;
        server rocketchat2:3300;
    }

    server {
       listen 3300;

       server_name nginx;

       location / {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://matrix-rocketchat;
        }
    }
    
    server {docker
    	listen 443 ssl;

    	server_name ps-rocketchat.com;

    	ssl_certificate /cert/certificate.crt;
        ssl_certificate_key /cert/private.key;

    	add_header X-Frame-Options DENY;
    	add_header X-Content-Type-Options nosniff;
    	add_header X-XSS-Protection "1; mode=block";

        location /.well-known/matrix/server {
            default_type application/json;
            add_header Access-Control-Allow-Origin *;
	       return 200 '{"m.server": "matrix2.ps-rocketchat.com:443"}';
	   }

        location /.well-known/matrix/client {
            default_type application/json;
            add_header Access-Control-Allow-Origin *;
            return 200 '{"m.homeserver": {"base_url": "https://matrix2.ps-rocketchat.com"}}';
        }

        location / {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-For $remote_addr;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://web-rocketchat;
        }
   }

   server {
    listen 80;

    server_name ps-rocketchat.com;

    return 302 https://$server_name$request_uri;
   }
    
   server {
    listen 443 ssl;
    server_name matrix2.ps-rocketchat.com;
    ssl_certificate /cert/certificate.crt;
    ssl_certificate_key /cert/private.key;

	add_header X-Frame-Options DENY;
	add_header X-Content-Type-Options nosniff;
	add_header X-XSS-Protection "1; mode=block";

    location / {
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_pass http://synapse:8008;
    }
  }

}

• Restart nginx with this command:

docker restart nginx

• Navigate to Administration > Workspace > Settings > Federation > Matrix Bridge and update these configurations:

  • Homeserver URL: http://synapse:8008

  • Homeserver Domain: <your domain>

  • Bridge URL: http://nginx:3300

• Save your changes and copy the contents of your registration file.

• Paste the contents in the data/registration.yaml file. For Synapse versions 1.9 and higher, the registration.yaml file must include the following line:

  use_appservice_legacy_authorization: true

• Now restart the rocketchat and synapse containers with these commands:

docker restart synapse

docker restart rocketchat

docker restart rocketchat2   

• Now you can proceed to test your workspace again.

Reset your environment and restart your setup

Execute the following commands to clean up your files, reset your environment, and restart your setup:

docker stop rocketchat
docker stop synapse
docker stop mongodb
docker remove rocketchat
docker remove synapse
docker remove mongodb
sudo rm -fr data

If you had a cluster set, you also need to stop/remove the rocketchat2 docker instance. See Federation FAQ for more troubleshooting tips.