- Print
- DarkLight
- PDF
Deploy a Federated Rocket.Chat Workspace with Docker
- Print
- DarkLight
- PDF
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
.
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
Open your terminal in any directory of your choice
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)
Follow the instructions provided by the script to configure the workspace:
Server's hostname: Add your domain name.
Create A domain records pointing to your server's IP address as requested.
synapse.<your-domain>
element.<your-domain>
traefik.<your-domain>
Enter your email address. This is used to issue an SSL certificate for your domain.
To install the latest version of Rocket.Chat, navigate to the
.env
file, and replace these variables as shown below:RC_IMAGE=registry.rocket.chat/rocketchat/rocket.chat:latest ROCKETCHAT_IMAGE_TAG=latest
To install a specific version of Rocket.Chat, replace latest with the docker image tag of your preferred version.
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
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 likematrix2.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
andmatrix2.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.
![image(44).png](http://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(44).png)
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.
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
![image(46).png](http://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(46).png)
Save your changes and copy the contents of your registration file.
![image(47).png](http://cdn.us.document360.io/6ae79a05-7252-45d0-96e8-8f375e07b1b2/Images/Documentation/image(47).png)
Paste the contents in the
data/registration.yaml
file .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.