Rocket.Chat Air-Gapped Deployment with Docker

An air-gapped system is one that is physically isolated from external networks, such as the public internet, to ensure maximum security. This setup is commonly used by organizations with heightened security needs, like government agencies, defense sectors, and critical infrastructure operators.

Rocket.Chat supports deployment in air-gapped environments but requires a premium (Starter, Pro, or Enterprise) license due to the following reasons:

1. Commercial Code Inclusion: Rocket.Chat’s codebase includes both open-source and commercial components. A premium license ensures access to advanced features and allows organizations to audit the code for compliance.

2. Intellectual Property Protection: Without internet access, Rocket.Chat cannot verify license usage for commercial features. The premium license ensures compliance and protects Rocket.Chat’s intellectual property.

3. Compliance and Feature Unlock: A premium license unlocks enterprise-grade features, including advanced security tools, scalability options, and premium support.

For organizations using Community workspaces, there are two options:

• Purchase a Premium License: Unlocks advanced features and ensures compliance in air-gapped environments. To upgrade to the free Starter plan, refer to Upgrade to Starter from Community workspace.

• Build and Maintain a FOSS Version: Users can build from the open-source repository without requiring a license, though premium features and support are excluded.

A premium license ensures compliance, enhances scalability, and provides access to Rocket.Chat’s full feature set in secure, air-gapped deployments.

Air-gapped workspace deployment options

This document covers the following options to deploy Rocket.Chat in an air-gapped environment:

1. Copy Rocket.Chat Docker images from a server with internet access

2. Deploy Rocket.Chat with a private Docker registry

Option 1: Copy Rocket.Chat Docker images from a server with internet access

Given that an air-gapped environment has no internet access, simply download the required Docker images on a server with internet access and transfer them to the air-gapped server.

Prerequisites

1. One server that has internet access to download the Docker images.

2. One air-gapped server to deploy Rocket.Chat.

3. Ensure that Docker is installed and operational on the two servers.

4. Ensure that you have a method for transferring files from the server with internet access to the air-gapped server, for example, USB drives.

Transfer methods may vary depending on your company's policies and network configurations.

Step 1: Download the Rocket.Chat files

1. Go to the server with internet access and download the Rocket.Chat and MongoDB images with the following commands:

   docker pull registry.rocket.chat/rocketchat/rocket.chat:7.0.0
   
   docker pull docker.io/bitnami/mongodb:latest

   • Download Rocket.Chat version 6.5 or higher.

   • Instead of the latest MongoDB image, confirm that you're downloading the supported MongoDB version by checking our release notes. For example, 6.0.

2. Run docker images to see the images you just downloaded.

3. Save the images as .tar files with these commands:

docker save -o rocketchat.tar registry.rocket.chat/rocketchat/rocket.chat

docker save -o mongodb.tar bitnami/mongodb

4. Next, download the Rocket.Chat sample compose.yml file by executing this command:

curl -L https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/compose.yml -O

5. Run ls to view the files. You should have the two .tar files and the compose.yml file.

6. Editing the configurations in the compose.yml file is not recommended. Instead, set environment variables using a .env file. Download the sample .env file using this command:

curl -L https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/env.example -O

Note the following points while modifying the .env file:

• Change the file name to .env.

• Uncomment the variables that you are updating.

• Set the RELEASE variable in the .env to your desired Rocket.Chat version. See our releases page and available docker images. Keeping the default release as latest is not recommended.

• Edit ROOT_URL from the default http://localhost:3000 to match your domain name or IP address if you're deploying a production workspace.

• Set the MONGODB_VERSION to the supported MongoDB version according to our releases.

• For example, the values in the .env file should look something like this:

RELEASE=7.0.0
ROOT_URL=https://test.rocket.chat
MONGO_VERSION=6.0.3

• If you have a registration token to register the workspace automatically, you can add it like this: REG_TOKEN={your token here}

• Save the .env file after making the necessary changes and follow the next steps.

Step 2: Transfer the files

• If your server with internet access and the air-gapped server cannot communicate and are not on the same network, copy the downloaded files to a USB drive and transfer them to the air-gapped server using the USB drive. Then, follow Step 3.

• Alternatively, if the two servers can communicate with each other, you can transfer the downloaded files to your air-gapped server with the following commands:

scp -i [key] <rocketchat_tar_file_path> <user_name@target_ip_address:/destination_path>

scp -i [key] <mongodb_tar_file_path> <user_name@target_ip_address:/destination_path>

scp -i [key] <compose_file_path> <user_name@target_ip_address:/destination_path>

scp -i [key] <env_file_path> <user_name@target_ip_address:/destination_path>

Update the following with the appropriate values:

• key: The key to access the air-gapped server where the file should be sent.

• rocketchat_tar_file_path: The rocketchat.tar file path.

• mongodb_tar_file_path: The mongodb.tar file path.

• compose_file_path: The compose.yml file path.

• env_file_path: The .env file path.

• user_name@target_ip_address: The username and IP address of the air-gapped server where the file should be sent.

• destination_path: The directory path on the air-gapped server where you want to save the file.

For example, scp -i firstServer.pem rocketchat.tar [email protected]:/home/ubuntu

Step 3: Deploy Rocket.Chat on the air-gapped server

1. Go to the destination directory in the air-gapped server where you transferred the files.

2. Run ls to confirm that the files were transferred successfully. You should have two .tar files, a compose.yml file, and a .env file.

3. Load the Rocket.Chat and MongoDB images to Docker with the following commands:

   docker load -i rocketchat.tar
   
   docker load -i mongodb.tar

   Run docker images to view the images.

4. If you have not edited the .env file in Step 1, you can do so here. It is not recommended to modify the compose file, but if you need to, you can also edit the ROOT_URL in the compose.yaml file from the default http://localhost:3000 to match your server URL or domain name. For example,

   ROOT_URL: http://172.55.18.208

5. To install Rocket.Chat, execute this command:

   docker compose up -d

6. Confirm that the RocketChat and Mongo DB containers are actively running by executing the command docker ps.

7. To see the log/status of your Rocket.Chat container, execute this command:

   docker compose logs -f rocketchat

It also displays your site URL, which you can use to access your workspace.

Great! You have successfully deployed Rocket.Chat in your air-gapped environment. Log into your workspace using your site URL. The first user to log in becomes the workspace administrator.

The following section walks you through the second deployment method.

Option 2: Deploy Rocket.Chat with a private Docker registry

A Docker registry is a system for storing and distributing Docker images with specific names. Considering that an air-gapped computer can't access the internet to download the required Docker images for deploying Rocket.Chat, this method will demonstrate how to use a private registry to store the necessary images and deploy Rocket.Chat.

Prerequisites

• One server that has internet access to download the Docker images.

• Two air-gapped servers (one for hosting the private registry, one for installing Rocket.Chat).

• Ensure that Docker is installed and operational on the three servers.

• Ensure that you have a method for transferring files from the server with internet access to the air-gapped server, for example, USB drives.

The diagram below highlights an overview of the servers:

Transfer methods may vary depending on your company's policies and network configurations.

Step 1: Create a private registry

Given that the server to host the registry doesn't have internet access, it is impossible to download images from Docker Hub or any public registry. As a result, you need to download the registry image on a server with internet access and transfer it to the air-gapped registry host server before proceeding with the installation.

Follow these steps to complete the process:

1. On the server that has internet access, pull the image that'll be used to create the registry with this command:

   docker pull registry:2

2. Run docker images to see that the image has been downloaded.
   

3. Create a .tar file of the registry image:

   docker save -o registry_image.tar registry:2

4. If your server with internet access and the air-gapped server cannot communicate and are not on the same network, copy the downloaded .tar file to a USB drive and transfer it to the air-gapped server using the USB drive.

   
   Alternatively, if the two servers can communicate with each other, you can transfer the .tar file to the air-gapped registry host server using the following command:

   scp -i [key] <registry_tar_file_path> <user_name@target_ip_address:/destination_path>

   Update the following with the appropriate values:

   • key: The key to access the registry host server where the file should be sent.

   • registry_tar_file_path: The registry_image.tar file path.

   • user_name@target_ip_address: The username and IP address of the registry host server where the file should be sent.

   • destination_path: The directory path on the registry host server where the file should be located.

   For example, scp -i firstServer.pem registry_image.tar [email protected]:/home/ubuntu

   Transfer methods may vary depending on your company's policies and network configurations.

5. Now, go to the air-gapped registry host server. Run the following commands to confirm that you don't have the registry image or container yet:

   docker images 
   
   docker ps

6. Go to the destination path where you sent the .tar file and run the ls command and verify that the transfer was successful.

7. To load the tar file on the air-gapped registry host server, execute this command in your preferred directory:

   docker load -i registry_image.tar

8. Now run docker images to see the registry image that you downloaded and transferred from the first server.

   

9. To start the registry container for this image, execute this command:

   docker run -d -p 5000:5000 --restart=always --name private-registry registry:2

   • It's not mandatory to run the container on port 5000. The suggested port is an example and can be updated according to your specific requirements.

   • Update private-registry with your preferred name for the registry container.

   • For production environments, ensure the persistence of images by either specifying a local folder on the host for storage or by implementing other suitable persistence mechanisms.

10. Run docker ps to see the new registry container running.

    

Now, you have a functioning registry on an air-gapped server ready to store the Rocket.Chat and MongoDB images.

Step 2: Transfer the Rocket.Chat and MongoDB images to the registry

Recall that the air-gapped server containing the registry has no internet access, so it's impossible to download the Rocket.Chat and MongoDB images from external registries. Download the images on the first server with internet access and push the images to the registry in the air-gapped server.

Follow these steps to continue the process:

1. Return to the first server with internet access and execute these docker-pull commands to download the Rocket.Chat and MongoDB images:

   docker pull registry.rocket.chat/rocketchat/rocket.chat:7.0.0
   
   docker pull docker.io/bitnami/mongodb:latest

   • Download Rocket.Chat version 6.5 or higher.

   • Instead of the latest MongoDB image, confirm that you're downloading the appropriate MongoDB version by checking our release notes. For example, 6.0.

2. Run docker images to confirm that the images have been successfully downloaded.
   

   

3. Tag the Rocket.Chat and MongoDB images with these commands:

   docker tag registry.rocket.chat/rocketchat/rocket.chat:7.0.0 <registry_ip_address>:5000/registry.rocket.chat/rocketchat/rocket.chat:7.0.0
   
   docker tag bitnami/mongodb:latest <registry_ip_address>:5000/docker.io/bitnami/mongodb:latest 

   Update <registry_ip_address:5000> with the IP address of your registry host server and the appropriate port number, if your registry container is not running on port 5000.

4. Execute the docker images command to see the newly tagged images in the list of images.

5. If the air-gapped registry host server is HTTP, modify the docker daemon file to allow communication with insecure registries:

   sudo nano /etc/docker/daemon.json

6. Update the file with the following content and save it:

   {
       "insecure-registries": ["<registry_ip_address>:5000"]
   }

   Update <registry_ip_address:5000> with the IP address of your registry host server and the appropriate port number if your registry container is not running on port 5000.

7. Restart docker with this command:

   sudo systemctl restart docker

8. Push the tagged images to the registry on the air-gapped server with these commands:

   docker push <registry_ip_address>:5000/registry.rocket.chat/rocketchat/rocket.chat:7.0.0
   
   docker push <registry_ip_address>:5000/docker.io/bitnami/mongodb:latest

   Update <registry_ip_address:5000> with the IP address of your registry host server and the appropriate port number if your registry container is not running on port 5000.

9. Now, go to the air-gapped registry host server to confirm that the images were successfully pushed. To do this, run this command to open an interactive shell inside the registry container:

   docker exec -it private-registry sh

   Update private-registry with the name of your registry container if it's different.

10. Execute this command to see the docker images in the registry:

    ls /var/lib/registry/docker/registry/v2/repositories

Confirm that the MongoDB and Rocket.Chat images exist in the registry, and you're ready to install Rocket.Chat from the air-gapped server with the registry.

You may only see the first name of the image path. For example, docker.io instead of /docker.io/bitnami/mongodb.

Step 3: Download and transfer the Rocket.Chat files

In this step, we will download the necessary files and transfer them to the air-gapped server in which you want to install Rocket.Chat. Follow these steps:

1. Download the sample compose.yml and .env files using the following commands:

curl -L https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/compose.yml -O

curl -L https://raw.githubusercontent.com/RocketChat/Docker.Official.Image/master/env.example -O

2. Editing the configurations in the compose.yml file is not recommended. Instead, set environment variables in the .env file. Note the following points while modifying the .env file:

   1. Change the file name to .env.

   2. Uncomment the variables that you are updating.

   3. Set the RELEASE variable in the .env to your desired Rocket.Chat version. See our releases page and available docker images. Keeping the default release as latest is not recommended.

   4. Edit ROOT_URL from the default http://localhost:3000 to match your domain name or IP address if you're deploying a production workspace.

   5. Set the MONGODB_VERSION to the supported MongoDB version according to our releases.

   6. For example, the values in the .env file should look something like this:

      RELEASE=7.0.0
      ROOT_URL=https://test.rocket.chat
      MONGO_VERSION=6.0.3

   7. If you have a registration token to register the workspace automatically, you can add it like this: REG_TOKEN={your token here}

   8. Save the .env file after making the necessary changes and follow the next steps.

3. If your server with internet access and the air-gapped server cannot communicate and are not on the same network, copy the downloaded files to a USB drive. Transfer them to the air-gapped server in which you will install Rocket.Chat using the USB drive. Then, follow Step 4.
   

   Alternatively, if the two servers can communicate with each other, you can transfer the downloaded files to your air-gapped server with the following commands:

scp -i [key] <compose_file_path> <user_name@target_ip_address:/destination_path>

scp -i [key] <env_file_path> <user_name@target_ip_address:/destination_path>

Update the following with the appropriate values:

• key: The key to access the air-gapped server where the file should be sent.

• compose_file_path: The compose.yml file path.

• env_file_path: The .env file path.

• user_name@target_ip_address: The username and IP address of the air-gapped server where the file should be sent.

• destination_path: The directory path on the air-gapped server where you want to save the file.

For example, scp -i firstServer.pem rocketchat.tar [email protected]:/home/ubuntu

Step 4: Install Rocket.Chat

Now that the Rocket.Chat and MongoDB images have been pushed to the air-gapped server containing the registry, the next step is to install Rocket.Chat on the second air-gapped server. You have to deploy Rocket.Chat using the images from the air-gapped server with the registry and the files that we transferred from the previous step. Follow these steps to do so:

1. Run the following commands to confirm that no Rocket.Chat and MongoDB images are running on the air-gapped server:

   docker images 
   
   docker ps

2. If you are using HTTP to communicate between your server and registry, modify the docker daemon file to allow communication with insecure registries:

   sudo nano /etc/docker/daemon.json

3. Update the file with the following content and save it:

   {
       "insecure-registries": ["<registry_ip_address>:5000"]
   }

   Update <registry_ip_address:5000> with the IP address of your registry host server and the appropriate port number, if your registry container is not running on port 5000.

4. Restart docker with this command:

   sudo systemctl restart docker

5. If you have not edited the .env file in Step 3, you can do so here. It is not recommended to modify the compose file, but if you need to, you can also edit the ROOT_URL in the compose.yaml file from the default http://localhost:3000 to match your server URL or domain name. For example,

   ROOT_URL: http://172.55.18.208

6. Update the image paths for Rocket.Chat and MongoDB to reference the images on the registry in the air-gapped server. For example,

   rocketchat:
       image: <registry_ip_address>:5000/registry.rocket.chat/rocketchat/rocket.chat:7.0.0
       
   mongodb:
       image:<registry_ip_address>:5000/docker.io/bitnami/mongodb:latest

   Update <registry_ip_address:5000> with the IP address of your registry host server and the appropriate port number, if your registry container is not running on port 5000.

7. Install Rocket.Chat by executing this command:

   docker compose up -d

8. Run these commands to confirm that the RocketChat and MongoDB images are present with their containers actively running:

   docker images 
   
   docker ps

9. To see the log/status of your Rocket.Chat container, execute this command:

   docker compose logs -f rocketchat

It also displays your site URL, which you can use to access your workspace.

Now, you have successfully deployed Rocket.Chat in your air-gapped environment. Log into your workspace using your site URL, and the first user to log in becomes the workspace administrator.

Next steps

Once your air-gapped workspace is deployed successfully, you must register your workspace. Follow the Air-Gapped Workspace Registration document. After this, you need to apply the workspace license. Then, you are ready to begin using your workspace! You can refer to the additional configurations and app installation details for air-gapped workspaces.

To learn more about your workspace, you can refer to the following:

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

Upgrade from Community air-gapped workspace to Starter

From 7.0, air-gapped Community workspaces will be in read-only mode. Community workspaces must be subscribed to a premium plan to access the air-gapped features. Workspace admins can follow these steps to upgrade the workspaces:

1. Log in to the Rocket.Chat Cloud portal and select the Workspaces tab.

2. Click the kebab menu against the Community workspace that you want to upgrade.

3. Select Upgrade to Starter. Your workspace will be subscribed to the Starter plan.

Once your workspace is subscribed to the Starter plan, follow these steps to get the air-gapped license and activate the workspace:

1. In the cloud portal, select the upgraded workspace. The workspace details page opens.

2. Click the Get License button from the Rocket.Chat License section.

3. An Apply Offline License pop-up opens. Copy the License Code.

4. In your workspace, go to Workspace > Settings > Premium.

5. Under the Premium section, in the Premium License field, paste the license code you copied from the cloud portal.

6. Save the changes.

You have successfully activated your air-gapped workspace! For other premium plans, you can refer to the Air-Gapped License document.