Deploy with Podman & Podman 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 Podman is a modern and efficient alternative to traditional Docker-based setups well-suited for Red Hat Enterprise Linux (RHEL) or CentOS environments. This guide walks you through setting up Rocket.Chat using Podman and Podman Compose.

In this guide, you'll learn how to:

Preparing a RHEL System for Podman Deployment

To run Rocket.Chat with Podman on Red Hat Enterprise Linux (RHEL), you need:

A RHEL-based system (8.10 or higher): If you don’t have an account, you can register for a Red Hat Developer Subscription, which provides a free access for non-production use.
On macOS, you can test deployments locally by installing the RHEL ISO in a virtual machine using a tool like UTM.

Register your system to Red Hat
If your RHEL system already has access to software repositories, you can skip the registration and repo setup steps below.
1. After installing RHEL, register the system using your activation key or Red Hat credentials to enable software installation via the package manager:
```
sudo subscription-manager register
```
2. Then enable the necessary software repositories:
```
sudo subscription-manager repos \
  --enable=rhel-8-for-x86_64-baseos-rpms \
  --enable=rhel-8-for-x86_64-appstream-rpms
```
  The exact command may vary depending on your RHEL version.
3. If your system has alternate repos (such as -eus) enabled by default, it’s recommended to disable them to avoid conflicts:
```
sudo subscription-manager repos \
  --disable=rhel-8-for-x86_64-baseos-eus-rpms \
  --disable=rhel-8-for-x86_64-appstream-eus-rpms
```
  The exact command may vary depending on your RHEL version.
4. Finally, clear cache with these commands:
```
sudo dnf clean all
sudo dnf makecache
```

Step 1: Install Podman & Podman Compose

With your system registered and the necessary repositories enabled, you can now install Podman & Podman Compose to run and manage Rocket.Chat containers on RHEL.

Install Podman

Podman is available in the default RHEL repositories. Install it using the following command:
```
sudo dnf install -y podman
```
Once installed, confirm that Podman is functioning correctly by running:
```
podman --version
```

Install Podman Compose

Podman Compose is a lightweight tool that allows you to run Docker Compose files using Podman. Since it's not always available through dnf, it's recommended to install it using Python's package manager, pip. For best results, use Python 3.8 or later, as compatibility is more reliable with newer versions.

To install Python 3.11, run the following command:
```
sudo dnf install -y python3.11 python3.11-pip
```
Then, install Podman Compose using pip:
```
python3.11 -m pip install --user podman-compose
```
You can replace python3.11 with any installed Python version 3.8 or later.
To ensure the installed binary is accessible, run the following command:
```
echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```
After installation, verify that it’s working by running:
```
podman-compose --version
```

Step 2: Fetch the compose file

Create your preferred working directory where you'll store the Rocket.Chat configuration files. For example:
```
mkdir ~/rocketchat-deploy
cd ~/rocketchat-deploy
```
Fetch the official Rocket.Chat Docker image compose.yml file by running the following command:
```
curl -L https://go.rocket.chat/i/docker-compose.yml -O
```
This file defines the required services for a successful deployment, such as Rocket.Chat and MongoDB. Alternatively, you can create a compose.yml file manually and copy the contents into it.

Step 3: Create a `.env` file

The next step is to create a .env file to define environment variables. This simplifies managing and updating your deployment configuration without directly modifying the docker-compose.yml file.

In your project directory, create a .env file using the following command, then paste the contents of the official .env.example file into it:
```
nano .env
```
Uncomment or set the following environment variables as needed for your deployment:
1. RELEASE: Specify the Rocket.Chat version you want to deploy. Refer to the releases page and available Docker images to choose the appropriate version.
2. ROOT_URL: Set this to the base URL where your Rocket.Chat workspace will be accessed. For example, http://<your-domain> .By default, it’s http://localhost:3000.
3. REG_TOKEN: If you’ve received a registration token from from the Rocket.Chat Sales team or Rocket.Chat Cloud, set it here to automatically register your workspace.
  - Adding the registration token to the .env file is optional. You can also register your workspace manually during the post-deployment configuration process.
  - Once registration is complete (confirmed when the server starts) the token is no longer required. If you included it in the .env file, you may safely remove it afterward, as the registration details are stored in the database's cloud settings.
4. MONGO_URL: If you're using an external MongoDB instance, such as MongoDB Atlas, set the MONGO_URL variable to your connection string. Use the following format:
```
MONGO_URL=mongodb://<user>:<pass>@host1:27017,host2:27017,host3:27017/<databaseName>?replicaSet=<replicaSet>&ssl=true&authSource=admin
```

Step 4: Start Rocket.Chat

Once your compose.yml and .env files are configured, you can start the Rocket.Chat and MongoDB containers.

Run the following command from your project directory:
```
podman-compose up -d
```
Running this command will:
1. Pull the required container images for Rocket.Chat and MongoDB
2. Start both services in the background (-d stands for detached mode)
This command may take some time to complete successfully.
To check if the containers are running, run the following command:
```
podman ps
```
You should see two active containers: One for MongoDB and one for Rocket.Chat.

Congratulations! You've successfully deployed a Rocket.Chat workspace using Podman.

Step 5: Accessing your Rocket.Chat workspace

To access your workspace, open http://localhost:3000 in your browser. Follow the on-screen prompts to complete the configuration process.

During configuration, your workspace and email address will be registered with the Rocket.Chat Cloud portal, where you can manage your workspace settings and subscriptions.

Next steps

Great job! You’ve successfully created your Rocket.Chat workspace using Podman and logged in. Next, explore the following resources to get started:

User Guides: Learn the basics of your Rocket.Chat account, including how to use different room types and communicate effectively with other users.
Workspace Administration: For administrators and owners: manage settings, configure permissions, and tailor the workspace to your organization’s needs.
Marketplace: Browse and install apps to extend your workspace's functionality and integrate with popular tools.

Enable HTTPS on Podman for your Rocket.Chat workspace

To ensure secure access to your Rocket.Chat workspace, your domain should be accessible only via HTTPS. If HTTPS is not already configured for your domain, you can set it up using Nginx as a reverse proxy. This section walks you through securing your Rocket.Chat deployment by configuring Nginx with a TLS/SSL certificate from Let’s Encrypt.

Prerequisite

Before you begin, make sure your domain name points to the public IP address of your Rocket.Chat server.

Get an SSL certificate from Let's Encrypt

Use Let's Encrypt to get a free & open-source SSL certificate by following the steps below:

Follow the Certbot instructions for Nginx on Snap up to the “Prepare the Certbot command” section to set up Certbot on your system.
Once Certbot is installed, run the following command to generate your certificate:
```
sudo certbot certonly --standalone --email <[email protected]> -d <domain.com> 
```

Configure Nginx web server with TLS/SSL

By default, Rocket.Chat runs on port 3000. To make access more user-friendly, you can use Nginx as a reverse proxy. This setup allows users to access your workspace using your domain name, without needing to specify the port in the URL.

Follow these steps to set it up:

Install Nginx using your package manager:
```
sudo dnf install -y nginx
```
Create a new Nginx configuration file for your Rocket.Chat domain:
```
sudo nano /etc/nginx/conf.d/rocketchat.conf
```

Paste the following config into the newly created file, replacing the placeholders with your actual domain name:

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

Test the Nginx configuration to make sure there are no syntax errors:
```
sudo nginx -t
```
On RHEL-based systems, Nginx may be restricted from making outbound network connections. Run this command to allow it:
```
sudo setsebool -P httpd_can_network_connect 1
```
If the syntax test was successful, restart Nginx service:
```
sudo systemctl restart nginx
```
If you're using cloud hosting (e.g., AWS, Azure, etc.) and have firewall or security group rules in place, ensure the following ports are open:
- TCP/22 from your current IP for SSH access
- TCP/443 from any IP that should access Rocket.Chat over HTTPS

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’ve successfully enabled HTTPS for your Rocket.Chat workspace using Nginx and Let’s Encrypt.

Update Rocket.Chat on Podman

Updating Rocket.Chat is straightforward when using Podman. Since all your data is stored in MongoDB, updating the Rocket.Chat container will not affect your persistent data.

Before updating Rocket.Chat, make sure to:
Review the general update guidelines to understand best practices and potential changes.
Verify MongoDB compatibility with the version of Rocket.Chat you plan to deploy. Using an incompatible MongoDB version may cause issues during or after the upgrade.

Using Podman & Podman Compose, you can update your rocketchat docker image to your preferred version of Rocket.Chat.

To update your Rocket.Chat version,

If you're using a .env file, update the RELEASE variable to the Docker image tag of your desired version.
```
RELEASE=<enter-desired-version>
```
Alternatively, edit the rocketchat service image in the compose.yml file to the Docker image tag of your desired version.
```
services:
  rocketchat:
    image:registry.rocket.chat/rocketchat/rocket.chat:<desired version>
```
To restart Rocket.Chat with the new version, stop and remove the existing container, then bring it back up:
```
podman stop <rocketchat_container_name>
podman rm <rocketchat_container_name>
podman-compose up -d rocketchat
```
Replace <rocketchat_container_name> with your container’s name or ID. You can find it using:
```
podman ps -a
```
After a few seconds, check that the new container is running:
```
docker ps
```
You should see a new Rocket.Chat container running with the updated version tag.

Now, open your browser and return to your workspace URL. Your instance should now be running the newly specified version.

For additional details about available versions and image tags, refer to the official Rocket.Chat Docker image documentation.

Additional steps

Monitoring and logging your deployment

Monitoring logs is essential for tracking the health, performance, and debugging of your Rocket.Chat deployment. This section explains how to inspect logs for both Rocket.Chat and MongoDB when running under Podman.

Logging Rocket.Chat

View running containers:

podman ps           # Shows active containers
podman ps -a        # Shows all containers, including stopped ones

If you’re using Podman Compose, you can also run:

podman-compose ps   # Lists containers managed by your compose file

View logs:

podman logs <Container_Name>               # Displays logs for the specific Rocket.Chat container
podman logs -f <Container_Name>            # Follow logs in real time
podman logs --tail 20 <Container_Name>     # Show the last 20 lines of logs
podman-compose logs -f <Service_Name>      # If using Docker Compose, this follows real-time logs

Replace <Container_Name> and <Service_Name> with the appropriate values such as docker compose logs -f rocketchat.

Logging MongoDB

MongoDB is a critical component of your Rocket.Chat deployment. Monitoring its logs helps you detect and troubleshoot database-related issues, such as connection problems, performance bottlenecks, or authentication errors.