Deploy with Podman & 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 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:

  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: Fetch the Rocket.Chat compose configuration

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 Traefik (for reverse proxy and HTTPS) and monitoring tools.

  2. To configure your deployment without editing the compose.yml, you’ll need a dedicated .env file. Copy the example file to start your customization:

    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.

Step 3: Configure Rocket.Chat

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

  1. Open the file with a text editor like nano:

    nano .env

  2. Modify the RELEASE variable to specify the exact version of Rocket.Chat you wish to deploy. Refer to the Rocket.Chat releases page for a list of available stable versions.

    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.

  3. The next step is to configure the ROOT_URL and DOMAIN. These variables determine how users will access your Rocket.Chat workspace. Configuration differs based on whether you are running a local test or a public production instance.

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

  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.

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.

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.

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

    Field

    Description

    Example

    DOMAIN

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

    chat.example.com

    ROOT_URL

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

    https://chat.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.

    [email protected]

    TRAEFIK_PROTOCOL

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

    https

    Here is an example of the configuration:

    DOMAIN=chat.example.com
ROOT_URL=https://chat.example.com
LETSENCRYPT_ENABLED=true
[email protected]
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.

Step 4: Enable monitoring

The rocketchat-compose repository includes Grafana (for visualization) and Prometheus (for data collection) to provide a powerful, out-of-the-box monitoring solution for your workspace. 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 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:

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

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

  1. Ensure your subdomain's A record is correctly pointing to your server's IP address in your DNS settings.

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

  3. 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 launching Rocket.Chat:

  1. External MongoDB connection: If you wish to use an existing or dedicated MongoDB instance (such as a managed service like MongoDB Atlas or a separately hosted deployment) instead of the bundled local database, 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 use, 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, proceed to remove the token from your .env file after the first successful deployment.

Step 6: Start Rocket.Chat

With your .env file configured and saved, you're ready to start your Rocket.Chat workspace.

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

    You can easily 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

  2. After running the command, check if all containers are running as expected:

    podman ps

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 7: 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 testing: Go to http://localhost:3000.

  • For production: Navigate to the ROOT_URL you configured in your .env file (e.g., https://your-domain.com).

  1. After the workspace loads, follow the on-screen prompts 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 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.

    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.

Step 8: 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

  • Before you proceed, consult the general guidelines for updating Rocket.Chat.

  • Updating the Rocket.Chat image will not affect your data, as it is stored persistently in the separate MongoDB service. Before updating to a new major Rocket.Chat release, confirm that your existing MongoDB version is compatible with the intended new release. See the MongoDB version requirements for more details.

To update your Rocket.Chat version, continue with the following steps:

  1. Modify the RELEASE variable in the .env file to point to the release tag of that version. Alternatively, you can edit the compose.yml file to point to the desired Rocket.Chat version.

    Changing version in .env

    In the .env file, change the RELEASE value to your specified version.

    RELEASE=<desired version>

    Changing version in compose.yml

    In the compose.yml file, change the rocketchat service image value to point to an image in the rocketchat registry image with a tag of your desired version.

    services:
  rocketchat:
    image:registry.rocket.chat/rocketchat/rocket.chat:<desired version>

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

  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.

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

  1. A public domain with an A record pointing to your Rocket.chat’s server IP.

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

  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, 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:

  1. Install Nginx using your package manager:

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

  4. Test the Nginx configuration to make sure there are no syntax errors:

    sudo nginx -t

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

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

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

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.