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.

Podman offers a modern alternative to Docker, especially on Red Hat Enterprise Linux (RHEL) and CentOS systems. In this guide, you’ll learn how to set 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 a RHEL account, you can get one for free with a Red Hat Developer Subscription for non-production use.

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 repo 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
```
4. Finally, clear cache with these commands:
```
sudo dnf clean all
sudo dnf makecache
```

Step 1: Install Git, Podman & Podman Compose

With your RHEL system registered and repositories enabled, you’re ready to install the tools needed to run Rocket.Chat.

Install Git

Run the following command to install Git in your server:
```
sudo dnf install git
```
To confirm the installation, check the version:
```
git -v
```

Install Podman

Podman is available in the default RHEL repositories. Install it using the following command:
```
sudo dnf install -y podman
```
Verify the installation 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.

It’s best to use Python 3.8+ as compatibility is more reliable with newer versions (this example uses Python 3.12).

First, install Python 3.12 and pip:

sudo dnf install -y python3.12 python3.12-pip

Next, install Podman Compose using pip:
```
python3.12 -m pip install --user podman-compose
```
You can replace python3.12 with any installed Python version 3.8 or later.

To ensure the installed binary is accessible, add it to your PATH:

echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

Finally, verify that Podman Compose is working:
```
podman-compose --version
```

Step 2: Fetch the Rocket.Chat compose configuration

All the necessary configuration files for deploying Rocket.Chat are available in the official rocketchat-compose repository.

First, clone the repository using Git and navigate into the new directory:
```
git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git
cd rocketchat-compose
```
This repository includes the compose.yml , .env.example file and other configuration files required for setting up your Rocket.Chat instance.
To customize your deployment without editing compose.yml directly, create a .env file from the provided example:
```
cp .env.example .env
```
You’ll edit this .env file in the next step to configure your Rocket.Chat instance before deployment.

Step 3: Configure Rocket.Chat

Before starting your Rocket.Chat workspace, you need to configure key variables in the .env file.

Open the file with a text editor like nano:
```
nano .env
```
Set the RELEASE variable to the Rocket.Chat version you want to deploy. It's highly recommended to specify a version (e.g., 7.5.0) for production environments instead of using latest to ensure stability.
```
RELEASE=7.5.0
```
See Rocket.Chat releases for available versions.
Configure the ROOT_URL and DOMAIN to determine how your workspace will be accessed. It depends on whether you're in a local test or a production environment.

Local Development

Enable TLS with a domain

If you're testing Rocket.Chat locally, you can leave the ROOT_URL and DOMAIN variables as their default values.
```
DOMAIN=localhost
ROOT_URL=http://localhost
```
Your workspace will be accessible at http://localhost:3000 after deployment.
If you’re using rootless Podman with Traefik, you need to allow it bind to port 80:
```
echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
⚠️ This system-wide change allows any unprivileged user to listen on ports 80 and above. Be aware of this security implication.

If you’re deploying to production with a custom domain, the rocketchat-compose configuration includes Traefik, a reverse proxy that can automatically generate and manage free TLS/SSL certificates from Let's Encrypt.

Continue with the following steps:

Make sure your domain's A record (or CNAME) points to your server's IP address.
Update and save the following variables in your .env file:
1. DOMAIN: Your domain or subdomain name (e.g., chat.example.com). Do not include https:// or any trailing slashes.
2. ROOT_URL: The full URL users will use to access the workspace (e.g., https://chat.example.com).
3. LETSENCRYPT_ENABLED: Set to true to enable automatic certificate generation.
4. LETSENCRYPT_EMAIL: Your email address for Let's Encrypt notifications.
5. TRAEFIK_PROTOCOL: Set to https to enable secure access.
Here is an example configuration:
```
DOMAIN=chat.example.com
ROOT_URL=https://chat.example.com
LETSENCRYPT_ENABLED=true
[email protected]
TRAEFIK_PROTOCOL=https
```
If you’re using rootless Podman with Traefik, you need to allow it bind to port 80:
```
echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```
⚠️ This system-wide change allows any unprivileged user to listen on ports 80 and above. Be aware of this security implication.

Step 4: Enable monitoring

The rocketchat-compose repository includes Grafana and Prometheus, providing a powerful 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.

To enable monitoring, you'll need to configure how you want to access the Grafana dashboard. You can choose to access it either through a path (e.g., https://your-domain.com/grafana) or a subdomain (e.g., https://grafana.your-domain.com).

Grafana via a path

Grafana via a subdomain

This option is ideal for local development or if you want to keep all your services under a single domain, accessing your Grafana dashboard as a subdirectory (e.g., your-domain.com/grafana).

To configure this, follow these steps:

Leave the following variables in your .env file as thier default values:
1. GRAFANA_DOMAIN: Keep this variable empty.
2. GRAFANA_PATH: Set this to your desired path, ensuring there is no trailing slash (e.g., /grafana).
```
GRAFANA_DOMAIN=
GRAFANA_PATH=/grafana
```
Set a strong password for the Grafana admin user by updating the GRAFANA_ADMIN_PASSWORD variable.
```
GRAFANA_ADMIN_PASSWORD=your_secure_password
```

Accessing your Grafana dashboard through a dedicated subdomain is the recommended approach for production environments, as it provides a cleaner and more secure access point.

To set this up, follow these steps:

Ensure your subdomain's A record is correctly pointing to your server's IP address in your DNS settings.
Open your .env file and configure the following Grafana variables:
1. GRAFANA_DOMAIN: Set this to your desired subdomain (e.g., grafana.your-domain.com).
2. GRAFANA_PATH: Leave this variable empty.
```
GRAFANA_DOMAIN=grafana.your-domain.com
GRAFANA_PATH=
```
Set a strong password for the Grafana admin user by updating the GRAFANA_ADMIN_PASSWORD variable.
```
GRAFANA_ADMIN_PASSWORD=your_secure_password
```

Step 5: Optional configurations

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

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

Run the following command to pull the required images and start Rocket.Chat along with its supporting services:
```
podman-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 main Rocket.Chat application and its core database.
2. compose.database.yml: Manages the MongoDB database and the NATS message broker.
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 for secure routing and HTTPS.
After running the command, check if all containers are running as expected:
```
podman ps
```

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

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

Congratulations! You now have a fully running Rocket.Chat workspace on Podman.

Step 7: Access your Rocket.Chat workspace

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

For local testing: Open your browser and 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 configure 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 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.

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.

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:
```
podman 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.

Enable HTTPS with Nginx on Podman 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

A public domain with an A record pointing to your Rocket.chat’s server IP.
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 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.

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.

View logs:

podman logs -f <MongoDB_Container_Name>                     # Stream MongoDB logs
podman logs --tail 50 <MongoDB_Container_Name>              # Show the last 50 lines
podman-compose logs -f mongodb                              # If using Podman Compose

Check MongoDB server status:

To inspect MongoDB’s health, run the following command:

podman exec -it mongodb mongosh --eval "db.runCommand({ serverStatus: 1 })"

This will return useful metrics such as memory usage, active connections, replication state, and other operational details.

Replace <Container_Name> with the appropriate values.
If you're not using mongosh, replace it with mongo if installed in the container.

With Rocket.Chat successfully deployed using Podman, your team now has a secure, self-hosted communication platform that's flexible, reliable, and ready to scale with your organization’s needs.