Deploy with Podman and Podman Compose

Prev Next

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:

What you will have at the end of this guide:

  • A running Rocket.Chat workspace.

  • A reverse proxy (Traefik or Nginx) handling HTTPS traffic.

  • A monitoring stack for your workspace

If you’re using the built in Bitnami MongoDB images, refer to this forum post to upgrade to the official MongoDB 8.2 image required for Rocket.Chat 8.0.

Prerequisites

Before you begin, ensure the following requirements are met:

  • System requirements: Review the System Requirements guide to confirm your environment is compatible.

  • Domain: A domain is required for production deployments. Ensure your domain's A record (or CNAME record) points to the public IP address of the server running Podman.

  • Firewall: If your server has an active firewall, you may need to whitelist specific URLs to allow communication with Rocket.Chat's cloud services (e.g., push notifications, marketplace). Refer to the Firewall Configuration documentation for the complete list of required URLs.

Preparing a RHEL System for Podman deployment

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

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

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

  1. Run the following command to install Git in your server:

    sudo dnf install git

  2. To confirm the installation, check the version:

    git -v

Install Podman

  1. Podman is available in the default RHEL repositories. Install it using the following command:

    sudo dnf install -y podman

  2. 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. For better compatibility, use Python 3.8 or later. This example uses Python 3.12.

  1. First, install Python 3.12 and pip:

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

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

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

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

  4. Finally, verify that Podman Compose is working:

    podman-compose --version

Step 2: Clone the official Rocket.Chat configuration repository

The official rocketchat-compose repository contains all the configuration files you need to successfully deploy Rocket.Chat using Podman Compose.

  1. Clone the repository using Git and navigate to the cloned directory:

    git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git
cd rocketchat-compose

    This repository includes:

    1. compose.yml : The main configuration file for Podman Compose to deploy Rocket.Chat.

    2. .env.example : An example enviroment file for customizing your deployment.

    3. Additional configs: Other configuration files to support your deployment, such as database, Traefik (for reverse proxy and HTTPS) and monitoring tools.

Avoid editing these compose files directly. All deployment configuration can be managed through a single .env, which you’ll create in the next step.

Step 3: Configure Rocket.Chat

All deployment configurations like version, domain, reverse proxy, monitoring credentials can be controlled through variables in a .env file.

  1. Start by copying the provided example file:

    cp .env.example .env

    This command creates the .env file where you can now define your deployment variables, such as the desired Rocket.Chat version and your workspace URL.

  2. Open the file for editing:

    nano .env

Work through the configuration sections below before saving. Each section covers a distinct area of your deployment.

3a. Set Rocket.Chat version

Locate the RELEASE variable and set it to exact version of Rocket.Chat you wish to deploy.  A full list of available stable releases is on the Rocket.Chat releases page. For example, to set Rocket.Chat 7.5.0:

RELEASE=7.5.0

For production environments, it’s strongly recommended to specify a fixed version number (e.g., 7.5.0) instead of using latest. This prevents unexpected issues from automatic, breaking updates.

3b. Configure monitoring

The repository includes a ready-to-use observability stack: Prometheus collects metrics, Loki aggregates logs, and Grafana provides a dashboard for visualizing both. This setup allows you to visualize key metrics, track performance, and gain insights into the health of your Rocket.Chat instance.

You can choose to access Grafana either through a URL path (e.g., https://your-domain.com/grafana) or a subdomain (e.g., https://grafana.your-domain.com).

This option is ideal for local development or single-domain setups, accessing your Grafana dashboard as a subdirectory (e.g., https://your-domain.com/grafana).

To configure this, follow these steps in the .env file:

  1. You can use the default values for the following variables:

    1. GRAFANA_DOMAIN: Leave 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

  2. Set a strong password for the Grafana admin user by updating the GRAFANA_ADMIN_PASSWORD variable:

    GRAFANA_ADMIN_PASSWORD=your_secure_password

After deployment, Grafana will be available at https://your-domain.com/grafana.

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:

  1. In your DNS settings, create an A record for your desired subdomain (e.g., grafana.your-domain.com) and point it to your server's public IP address.

  2. Configure the following Grafana variables in the .env:

    1. GRAFANA_DOMAIN: Set this to the subdomain for accessing the Grafana dashboard. (e.g., grafana.your-domain.com).

    2. GRAFANA_PATH: Leave this variable empty.

      GRAFANA_DOMAIN=grafana.your-domain.com
GRAFANA_PATH=

  3. Set a strong password for the Grafana admin user by updating the GRAFANA_ADMIN_PASSWORD variable:

    GRAFANA_ADMIN_PASSWORD=your_secure_password

After deployment, Grafana will be available at https://grafana.your-domain.com .

3c. Configure domain and reverse proxy

Your reverse proxy determines how users access your workspace and whether connections are secured with HTTPS. The repository ships with Traefik as the default and recommended reverse proxy. Nginx can also be used as an alternative for teams that already operate it or have specific infrastructure requirements. Choose one option and follow only that path.

Traefik integrates directly with Podman and handles TLS certificate provisioning automatically via Let's Encrypt, making it the simpler choice for most deployments.

Local deployment

If you are only testing Rocket.Chat locally on your machine and do not require external access or HTTPS,

  1. Save the default values for these variables in the .env :

    DOMAIN=localhost
ROOT_URL=http://localhost

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

Your workspace will be accessible at http://localhost:3000 once succesfully deployed.

Production deployment

Before proceeding, verify that your domain's A record (or optional CNAME record) is correctly pointed to the public IP address of the server where you are running Podman. Traefik cannot provision a certificate for a domain it cannot reach.

For a publicly accessible and secure production deployment,

  1. Update the following variables in your .env file:

    Field

    Description

    Example

    DOMAIN

    Your public domain. Do not include https:// or any trailing slashes.

    example.com

    ROOT_URL

    The complete URL your users will use to access the server, including the secure protocol (https://).

    https://example.com

    LETSENCRYPT_ENABLED

    Set to true to enable Traefik to automatically obtain and renew certificates.

    true

    LETSENCRYPT_EMAIL

    Your valid email address for certificate renewal and security notifications from Let's Encrypt.

    demo@email.com

    TRAEFIK_PROTOCOL

    Set to https to ensure secure connections are enforced by the proxy.

    https

    Here is an example of the configuration:

    DOMAIN=example.com
ROOT_URL=https://example.com
LETSENCRYPT_ENABLED=true
LETSENCRYPT_EMAIL=demo@email.com
TRAEFIK_PROTOCOL=https

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

With Nginx, Rocket.Chat runs locally on port 3000 and Nginx acts as the public-facing reverse proxy, handling HTTPS and forwarding traffic to the local service. This setup requires a few additional manual steps compared to Traefik.

Before proceeding, verify that your domain's A record (or optional CNAME record) is correctly pointed to the public IP address of the server where you are running Podman.

Step 1: Configure Rocket.Chat to bind to localhost

  1. In your .env file, set the following default values to ensure Rocket.Chat runs locally so that Nginx can proxy requests to it:

    DOMAIN=localhost
ROOT_URL=http://localhost
LETSENCRYPT_ENABLED=false
LETSENCRYPT_EMAIL=demo@email.com
TRAEFIK_PROTOCOL=http

  2. Save the .env changes.

Step 2: Obtain a TLS certificate from Let's Encrypt

Use Let's Encrypt to get a free & open-source TLS certificate by following these steps:

  1. Follow the Certbot instructions for Nginx on Snap up to the “Prepare the Certbot command” section to set up Certbot on your system.

  2. Once certbot is installed, request a certificate for your domain from Let's Encrypt with this command:

    sudo certbot certonly --standalone --email <emailaddress@email.com> -d <domain.com> -d <subdomain.com>

    1. Replace <emailaddress@email.com> and <domain.com> with your actual email adress and domain name for Rocket.Chat.

    2. If you’re configuring Grafana via subdomain, replace <subdomain.com> with the Grafana subdomain (e.g., grafana.your-domain.com), otherwise remove it.

    If successful, your certificate files will be stored in /etc/letsencrypt/live/<your.domain.com>/. You will reference these paths in the Nginx configuration below.

Step 3: Install and configure Nginx

Now, link your domain to the Rocket.Chat service running locally on port 3000. Nginx will serve as the secure public entry point, handling HTTPS traffic on port 443 and directing requests to the local Rocket.Chat and Grafana services.

  1. Install Nginx web server:

    sudo dnf install -y nginx

  2. Create a new Nginx configuration file for your Rocket.Chat domain:

    sudo nano /etc/nginx/conf.d/rocketchat.conf

  3. Add your Nginx configuration to the file: The configuration you choose depends on how you configured Grafana during monitoring.

    If Grafana is configured via a URL path (e.g., https://your-domain.com/grafana), paste the following into the file:

     server {
     listen 443 ssl;
     server_name <ABC.DOMAIN.COM>; 
     ssl_certificate /etc/letsencrypt/live/<ABC.DOMAIN.COM>/fullchain.pem; 
     ssl_certificate_key /etc/letsencrypt/live/<ABC.DOMAIN.COM>/privkey.pem; 
     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;
     }
     # Grafana Reverse Proxy 
    location /grafana {
        proxy_pass http://localhost:5050/grafana;
        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 https; # Crucial for secure path access
        proxy_set_header X-Nginx-Proxy true;
        proxy_redirect off;
    } 
 }
 server {
     listen 80;
     server_name <ABC.DOMAIN.COM>; 
     return 301 https://$host$request_uri;
 }

    1. Replace <ABC.DOMAIN.COM> with your domain name.


    If Grafana is configured via a subdomain (e.g., https://grafana.your-domain.com), paste the following into the file:

     server {
     listen 443 ssl;
     server_name <ABC.DOMAIN.COM>; 
     ssl_certificate /etc/letsencrypt/live/<ABC.DOMAIN.COM>/fullchain.pem; 
     ssl_certificate_key /etc/letsencrypt/live/<ABC.DOMAIN.COM>/privkey.pem; 
     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 443 ssl;
    server_name <GRAFANA.ABC.DOMAIN.COM>; 
     ssl_certificate /etc/letsencrypt/live/<ABC.DOMAIN.COM>/fullchain.pem;
     ssl_certificate_key /etc/letsencrypt/live/<ABC.DOMAIN.COM>/privkey.pem;
    location / {
        proxy_pass http://localhost:5050/; # Note the change here (no /grafana suffix)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $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 https;
    }
}
server {
     listen 80;
     server_name <ABC.DOMAIN.COM>; 
     return 301 https://$host$request_uri;
 }

    1. Replace <ABC.DOMAIN.COM> with your domain name.

    2. Replace <GRAFANA.ABC.DOMAIN.COM> with your Grafana subdomain name.

  4. Validate the configuration for syntax errors before continuing:

    sudo nginx -t

    A message saying “syntax is ok” and “test is successful” confirms the configuration is valid. Do not restart Nginx yet, you’ll do that after the Rocket.Chat deployment is running in step 4.

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

  6. 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 you have security group restrictions, allow TCP/22 from your current IP for SSH connections and TCP/443 from the IP you plan to use for access.

3d. Optional configurations

Here are some additional configurations that are not required to launch but may be relevant depending on your infrastructure. You can add them to your .env file before launching Rocket.Chat:

  1. External MongoDB connection: By default, the stack provisions a MongoDB container automatically. If you prefer to connect to an existing MongoDB instance  such as a managed service like MongoDB Atlas or a separately hosted replica set), configure the MONGO_URL in the .env file like this:

    MONGO_URL=mongodb://<user>:<pass>@host1:27017,host2:27017,host3:27017/<databaseName>?replicaSet=<replicaSet>&ssl=true&authSource=admin

    For production, MongoDB must be deployed separately (non-containerized) and configured as a replica set.

  2. Registration token: If you’ve received a registration token from our Sales team or Rocket.Chat Cloud, you can use it to automatically register your workspace upon initial startup. To do this, add the token to the .env file like this:

    REG_TOKEN=your_token_here

    This step is optional, as you can also register the workspace through the setup wizard UI after deployment. Once the server successfully starts and registration is complete, the token is permanently stored in the database's cloud settings and is no longer required in the .env file. For security reasons, remove the token from your .env file after the first successful deployment.

Step 4: Launch the Rocket.Chat deployment

With your .env file saved, start the deployment following the instructions that corresponds to the reverse proxy you configured in Step 3:

  1. Verify that the podman user socket is active by removing any existing stale socket files before enabling the service:

    [ -d "$XDG_RUNTIME_DIR/podman" ] && rm -f "$XDG_RUNTIME_DIR/podman/podman.sock"
systemctl --user enable --now podman.socket

  2. 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 -f podman.yml up -d

    Here’s a brief summary of what each file in the command does:

    1. compose.yml: Starts the Rocket.Chat application.

    2. compose.database.yml: Manages MongoDB, the database that Rocket.Chat relies on. It also includes NATS, an internal message broker used for communication between services.

    3. compose.monitoring.yml: Enables monitoring with Prometheus (for collecting metrics), Loki (for collecting logs), and Grafana (for visualizing them in dashboards).

    4. compose.traefik.yml: Manages the Traefik reverse proxy, which handles secure routing and automatic HTTPS certificate generation from Let's Encrypt.

  1. Navigate back to the cloned Rocket.Chat directory where you have the compose files.

  2. Verify that the podman user socket is active by removing any existing stale socket files before enabling the service:

    [ -d "$XDG_RUNTIME_DIR/podman" ] && rm -f "$XDG_RUNTIME_DIR/podman/podman.sock"
systemctl --user enable --now podman.socket

  3. 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.yml -f podman.yml up -d

    Here’s a brief summary of what each file in the command does:

    1. compose.yml: Starts the Rocket.Chat application.

    2. compose.database.yml: Manages MongoDB, the database that Rocket.Chat relies on. It also includes NATS, an internal message broker used for communication between services.

    3. compose.monitoring.yml: Enables monitoring with Prometheus (for collecting metrics), Loki (for collecting logs), and Grafana (for visualizing them in dashboards).

    4. compose.traefik.yml: Manages the Traefik reverse proxy, which handles secure routing and automatic HTTPS certificate generation from Let's Encrypt.

  4. Once the containers are up, restart Nginx to begin proxying traffic to Rocket.Chat:

    sudo systemctl restart nginx

You can easily customize your deployment by including only the services you need. For example, if you did not configure monitoring or Traefik , you can omit those .yml files:

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

To check that all services have successfully started, use this command to list all running containers:

podman ps -a

All services should show a status of Up . Some minor MongoDB services may also have a status of Exited (0).

Congratulations! You now have a fully functional Rocket.Chat workspace on Podman. If you encounter issues during deployment, refer to the following resources for logging and troubleshooting:

Step 5: Access your Rocket.Chat workspace

  1. Once your Rocket.Chat instance is deployed, you can access the workspace through your web browser to begin your final configuration:

  • For local deployment: Go to http://localhost:3000.

  • For production: Navigate to the domain you configured.

  1. On first load, a setup wizard prompts you to create your first admin user and complete the initial workspace setup. Your workspace and email will be registered to the Rocket.Chat Cloud portal during this process.

Access monitoring dashboard

You can access the Grafana dashboard via the URL corresponding to your configured access method:

  • Via path: https://your-domain.com/grafana

  • Via subdomain: https://grafana.your-domain.com

Sign in with the following credentials:

  • User: admin

  • Password: The password you set in the GRAFANA_ADMIN_PASSWORD variable in your .env file.

    The GRAFANA_ADMIN_PASSWORD you set in the .env file is only applied once during the first setup of the container. To update your password later, you must change it directly within your Grafana user preferences.

For more details on how to monitor your workspace metrics and logs, refer to the Monitor Workspace Logs and Metrics guide.

Step 6: Update file storage

Rocket.Chat stores file uploads using GridFS by default. While this doesn't require extra setup, it's not ideal for production because it increases database load and reduces scalability performance. Rocket.Chat highly recommends using a dedicated object storage service such as Amazon S3, Google Cloud Storage (GCS), or MinIO. Refer to the File Uploads guide for detailed instructions on configuring your preferred file storage solution.

Next steps

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

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

  • Marketplace: Explore the available apps to enhance your workspace.

Update Rocket.Chat on Podman

Updating the Rocket.Chat image will not affect your data, as it is stored persistently in the separate MongoDB service. Before you proceed, consult the general guidelines for updating Rocket.Chat.

To update your Rocket.Chat version:

  1. Modify the RELEASE variable in the .env file to point to the release tag of new version:

    RELEASE=<desired version>

    For example, RELEASE=8.2.0 .

  2. Run the following command to pull the new version image and restart the containers:

    podman-compose -f compose.yml up -d

    Refer to the official documentation for more details on Rocket.Chat Docker images.

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

  4. After a few minutes, return to your workspace Subscription to verify the updated Rocket.Chat version.

Update MongoDB on Podman

If you’re using the built in Bitnami MongoDB images, refer to this forum post to upgrade to the official MongoDB 8.2 image required for Rocket.Chat 8.0.

Before you proceed, consult the general guidelines for updating MongoDB.

Upgrading or downgrading your MongoDB instance may be required when moving between major Rocket.Chat releases. Your Rocket.Chat workspace stores its data in a dedicated MongoDB service. Updating the Rocket.Chat container does not modify your stored data, as long as the MongoDB volume remains intact.

This section explains how to safely change your MongoDB version for Rocket.Chat in Podman, whether you are upgrading to a newer release or downgrading to an earlier one.

Before you proceed, consult the general guidelines for updating MongoDB.

If you are moving to a higher MongoDB version, follow the steps below:

  1. Ensure that the MongoDB image for the target version is available on Docker Hub under mongodb-community-server. Look for an image tagged <version>-ubi8 .

  2. Set or modify the MONGODB_VERSION variable in the .env file to point to your desired MongoDB version. 

    MONGODB_VERSION=<version>

    For example, MONGODB_VERSION=8.0 .

  3. Run the following command to pull the new image and restart the MongoDB container:

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

    Replace <mongodb_container_name> with your MongoDB container’s name or ID.

  4. After a few minutes, check that the new container is running:

    docker ps

    You should see a new MongoDB container running with the updated version tag.

MongoDB does not support direct binary downgrades if the data files were created by a newer version. To safely downgrade, you must first lower the Feature Compatibility Version (FCV) before changing the MongoDB image. Failing to set the FCV before switching binaries before upgrading will cause MongoDB to exit with an error and the container will repeatedly restart.

Before you proceed, ensure that the MongoDB image for the targeted version is available on Docker Hub under mongodb-community-server. Look for an image tagged <version>-ubi8 .

To downgrade your MongoDB version in Rocket.Chat, continue with these steps:

  1. Before making any changes, create a full database backup:

    podman exec <mongo-container_name> sh -c 'mongodump --archive' > db.dump

    Replace <mongo-container_name> with the current name of the MongoDB container.

  2. Enter the MongoDB container:

    podman exec -it  <mongo-container_name> bash

  3. Access the MongoDB shell:

    mongosh

  4. Once in the shell, switch to the database:

    use rocketchat

  5. Check the current Feature Compatibility Version:

    db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })

    The returned version should match your current MongoDB binary (for example, 8.2).

  6. Set the FCV to the version you intend to downgrade to:

    db.adminCommand({
  setFeatureCompatibilityVersion: "<version>",
  confirm: true
})

  7. Confirm that the FCV now matches the target version:

    db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })

  8. Exit the mongo shell and shut down the MongoDB container:

    podman-compose -f compose.database.yml -f compose.monitoring.yml -f compose.yml -f podman.yml down

  9. Set or modify the MONGODB_VERSION variable in the .env file to point to your desired MongoDB version:

    MONGODB_VERSION=<version>

    For example, MONGODB_VERSION=8.0 .

  10. Then, pull and start the database container:

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

  11. After a few minutes, confirm that the new MongoDB container is running:

    podman ps

    A new MongoDB container is now running with the updated version tag.

    You can also double-check the MongoDb version in the container with this command:

    podman exec -it <mongo-container_name> mongosh --eval "db.version()"

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

Additional operations

Back up and restore MongoDB data on Podman

Rocket.Chat stores all workspace data in MongoDB. Follow the steps in the commands below to back up and restore your database when running in Podman.

Back up your MongoDB database on Podman

  1. List all running Podman containers to find the name of your MongoDB service 

    podman ps -a

    Take note of your mongo container name (e.g., rocketchat-mongodb-1 )

  2. Run this command to dump the database into a binary file db.dump :

    podman exec <container_name> sh -c 'mongodump --archive' > db.dump

    When successful, you should see db.dump file in the current directory.

Restore MongoDB database backup on Podman

To restore the data, use mongorestore inside the MongoDB container, piping the data from your local db.dump file.

podman exec -i <container_name> sh -c 'mongorestore --archive' < db.dump

Export to an external database (e.g., MongoDB Atlas)

If you are migrating your data or performing an offline restore, you can use the local db.dump file directly with an external MongoDB connection string.

mongorestore --uri mongodb+srv://<user>:<password>@cluster0.w2btl.mongodb.net --archive=db.dump

Set Rocket.Chat deployment environment variable on Podman

Enviroment variables are additional settings that impacts your workspace deployment and configuration. Refer to the official documentation to learn more about Rocket.Chat deployment enviroment variables.

To set up an environment variable in Podman,

  1. Go to your Rocket.Chat directory and open your compose.yml file:

    nano compose.yml

  2. Add the environment variable under the environment section of the rocketchat service. For example, to override the SMTP Host setting, add:

    services:
  rocketchat:
    ...
    environment:
      ...
      OVERWRITE_SETTING_SMTP_Host: "my.smtp.server.com"

    Tip: This is the same section where ROOT_URL, MONGO_URL, etc is defined.

  3. Restart the Rocket.Chat container with the new version:

    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.

For a full list of available environment variables, refer to Deployment Environment Variables.

Monitoring and logging your deployment

Effective logging helps you monitor the health and status of your Rocket.Chat deployment. This section covers logging for Rocket.Chat, MongoDB, and reverse proxies like Traefik or Nginx.

To check the status and logs of your containers, follow these steps:

  1. Use one of the following commands to view containers in your Podman environment:

    podman ps           # Shows active containers
podman ps -a        # Shows all containers, including stopped ones
podman-compose ps   # Lists containers managed by your compose file

    These commands help you identify the containers running Rocket.Chat, MongoDB, Traefik, and related services.

  2. Once you identify the relevant container or service, use one of the following commands to inspect logs:

    podman-compose logs -f <service_name>  # Shows realtime logs for a service managed by Podman Compose  
podman logs <container_name>       # Displays logs for the specific container  
podman logs -f <container_name>    # Shows real-time logs for a container
podman logs --tail 10 <container_name> # Displays the last 10 lines of logs  

    • Replace <container_name> and <service_name> with the appropriate values.

    • Rocket.Chat logs to stdout, so there isn't a specific log file within the container. The Podman logging system captures these stdout logs, making them accessible through the podman logs command

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

    podman exec -it <mongodb_container_name> 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.

  4. If using Nginx as a reverse proxy, logs are stored inside the container at /var/log/nginx/. To view logs, run:

    sudo tail -f /var/log/nginx/access.log  # Access logs  
sudo tail -f /var/log/nginx/error.log   # Error logs  

Encountering issues with your deployment? See the Deployment FAQ for detailed troubleshooting assistance.

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.

Rocket.Chat versions receive support for six months after release. End-of-life for any version is the last day of the month when support ends.