--- title: "Deploy with Podman and Podman Compose" slug: "deploy-with-podman" description: "Learn how to deploy Rocket.Chat using Podman for container management. Get step-by-step setup instructions to ensure secure, efficient collaboration." updated: 2026-10-27T16:23:11Z published: 2026-10-27T16:23:11Z canonical: "docs.rocket.chat/deploy-with-podman" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # Deploy with Podman and Podman Compose > [!NOTE] > 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: - [Prepare a RHEL system for Podman-based deployment](/v1/docs/deploy-with-podman#preparing-a-rhel-system-for-podman-deployment) - [Install Git, Podman, and Podman Compose](/v1/docs/deploy-with-podman#step-1-install-git-podman-podman-compose) - [Deploy Rocket.Chat with Podman and Podman Compose](/v1/docs/deploy-with-podman#step-4-launch-the-rocketchat-deployment) - [Update Rocket.Chat to a new version on Podman](/v1/docs/deploy-with-podman#update-rocketchat-on-podman) - [Update MongoDB to a compatible version on Podman](/v1/docs/deploy-with-podman#update-mongodb-on-podman) - [Back up and restore your MongoDB database](/v1/docs/deploy-with-podman#back-up-and-restore-mongodb-data-on-podman) - [Set Rocket.Chat deployment environment variable on Podman](/v1/docs/deploy-with-podman#set-rocketchat-deployment-environment-variable-on-podman) 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 ## Prerequisites Before you begin, ensure the following requirements are met: - **System requirements**: Review the [System Requirements guide](/v1/docs/system-requirements) 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](/v1/docs/firewall-configuration) for the complete list of required URLs. - **Podman mode**: This guide uses **rootless** Podman, which is the recommended mode. Run every `podman` and `podman-compose` command as a regular user, not with `sudo`. If your environment requires rootful Podman, use `podman-rootful.yml` in place of `podman.yml` in every command in this guide. ## 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** > [!NOTE] > 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: ```bash sudo subscription-manager register ``` 2. Then enable the necessary software repositories: ```bash sudo subscription-manager repos \  --enable=rhel-8-for-x86_64-baseos-rpms \  --enable=rhel-8-for-x86_64-appstream-rpms ``` > [!NOTE] > 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: ```bash 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: ```bash sudo dnf clean all sudo dnf makecache ``` ## Step 1: Install Git, Podman, and 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: ```bash sudo dnf install git ``` 2. To confirm the installation, check the version: ```bash git -v ``` ### **Install Podman** 1. Podman is available in the default RHEL repositories. Install it using the following command: ```bash sudo dnf install -y podman ``` 2. Verify the installation by running: ```bash podman --version ``` ### **Install Podman Compose** Podman Compose is a lightweight tool that allows you to run Docker Compose files using Podman. Depending on your system, you can install it using `dnf` or `pip`. Select the tab for your preferred installation method: **dnf** To install `podman-compose` using `dnf`, run: ```bash sudo dnf install -y podman-compose ``` If the package is not available in your repositories, install it using `pip` instead. Select the **pip** tab for the instructions. **pip** If `podman-compose` is not available through `dnf`, you can install it using `pip`, Python's package manager. For better compatibility, use Python 3.8 or later. This example uses Python 3.12. 1. Install Python 3.12 and pip: ```bash sudo dnf install -y python3.12 python3.12-pip ``` 2. Install Podman Compose using pip: ```bash 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: ```bash echo 'export PATH=$HOME/.local/bin:$PATH' >> ~/.bashrc source ~/.bashrc ``` #### Verify Podman Compose installation To confirm that Podman Compose is installed correctly, run: ```bash podman-compose --version ``` ## Step 2: Clone the official Rocket.Chat configuration repository The official [rocketchat-compose repository](https://github.com/RocketChat/rocketchat-compose) 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: ```bash 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 environment 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: ```bash 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: ```bash 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](https://github.com/RocketChat/Rocket.Chat/releases). For example, to set Rocket.Chat 8.0.1: ```plaintext RELEASE=8.0.1 ``` > [!NOTE] > For production environments, it’s strongly recommended to specify a fixed version number (e.g., 8.0.1) instead of using `latest`. This prevents unexpected issues from automatic, breaking updates. ### 3b. Configure monitoring The [repository](https://github.com/RocketChat/rocketchat-compose) includes a ready-to-use observability stack: [Prometheus](https://prometheus.io/) collects metrics, [Loki](https://grafana.com/oss/loki/) aggregates logs, and [Grafana](https://grafana.com/) 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`). **Grafana via a path** 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`). ```plaintext GRAFANA_DOMAIN= GRAFANA_PATH=/grafana ``` 2. Set a strong password for the Grafana `admin` user by updating the `GRAFANA_ADMIN_PASSWORD` variable: ```plaintext GRAFANA_ADMIN_PASSWORD=your_secure_password ``` After deployment, Grafana will be available at `https://your-domain.com/grafana`. **Grafana via a subdomain** 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. ```plaintext 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: ```plaintext 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](https://github.com/RocketChat/rocketchat-compose) 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** 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` : ```plaintext DOMAIN=localhost ROOT_URL=http://localhost ``` 2. If you’re using rootless Podman with Traefik, you need to allow it bind to port 80: ```bash echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee -a /etc/sysctl.conf sudo sysctl -p ``` > [!WARNING] > ⚠️ This system-wide change allows any unprivileged user to listen on ports 80 and above. Be aware of this security implication. Once the deployment is running, your workspace is available at `http://localhost` through Traefik. Rocket.Chat also publishes port 3000 directly, so `http://localhost:3000` works as well. #### Production deployment > [!NOTE] > 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: ```plaintext 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: ```bash echo "net.ipv4.ip_unprivileged_port_start=80" | sudo tee -a /etc/sysctl.conf sudo sysctl -p ``` > [!WARNING] > ⚠️ This system-wide change allows any unprivileged user to listen on ports 80 and above. Be aware of this security implication. **Nginx** 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. > [!NOTE] > 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. #### 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: ```plaintext DOMAIN=localhost ROOT_URL=http://localhost LETSENCRYPT_ENABLED=false LETSENCRYPT_EMAIL=demo@email.com TRAEFIK_PROTOCOL=http ``` 2. Save the `.env` changes. #### 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](https://certbot.eff.org/instructions?ws=nginx&os=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: ```bash sudo certbot certonly --standalone --email -d -d ``` 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. 1. Replace `<emailaddress@email.com>` and `<domain.com>` with your actual email address and domain name for Rocket.Chat. 2. If you’re configuring [Grafana via subdomain](/v1/docs/deploy-with-podman#3b-configure-monitoring), replace `<subdomain.com>` with the Grafana subdomain (e.g., `grafana.your-domain.com`), otherwise remove it. #### 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: ```bash sudo dnf install -y nginx ``` 2. Create a new Nginx configuration file for your Rocket.Chat domain: ```bash 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](/v1/docs/deploy-with-podman#3b-configure-monitoring). If Grafana is configured via a URL path (e.g.,` https://your-domain.com/grafana`), paste the following into the file: ```nginx server {     listen 443 ssl;     server_name ;     ssl_certificate /etc/letsencrypt/live//fullchain.pem;     ssl_certificate_key /etc/letsencrypt/live//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 ;     return 301 https://$host$request_uri; } ``` If Grafana is configured via a subdomain (e.g.,` https://grafana.your-domain.com`), paste the following into the file: ```plaintext server {     listen 443 ssl;     server_name ;     ssl_certificate /etc/letsencrypt/live//fullchain.pem;     ssl_certificate_key /etc/letsencrypt/live//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 ;     ssl_certificate /etc/letsencrypt/live//fullchain.pem;     ssl_certificate_key /etc/letsencrypt/live//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 ;     return 301 https://$host$request_uri; } ``` 1. Replace `<ABC.DOMAIN.COM>` with your domain name. 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: ```bash 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](/v1/docs/deploy-with-podman#step-4-launch-the-rocketchat-deployment). 5. On RHEL-based systems, Nginx may be restricted from making outbound network connections. Run this command to allow it: ```bash sudo setsebool -P httpd_can_network_connect 1 ``` > [!WARNING] > 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: ```plaintext MONGO_URL=mongodb://:@host1:27017,host2:27017,host3:27017/?replicaSet=&ssl=true&authSource=admin ``` > [!WARNING] > 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](/v1/docs/register-your-workspace#obtain-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: ```plaintext REG_TOKEN=your_token_here ``` > [!NOTE] > This step is optional, as you can also register the workspace through the [setup wizard UI](/v1/docs/setup-your-workspace) 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](/v1/docs/deploy-with-podman#3c-configure-domain-and-reverse-proxy): **Traefik** 1. Verify that the podman user socket is active by removing any existing stale socket files before enabling the service: ```bash [ -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: ```bash podman-compose -f compose.database.yml -f compose.nats.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. 3. `compose.nats.yml`: Runs **NATS**, the message broker Rocket.Chat uses internally. Rocket.Chat is configured to reach a NATS service by default, so include this file unless you point the `NATS_URL` variable at an external NATS server. 4. `compose.monitoring.yml`: Enables monitoring with **Prometheus** (for collecting metrics), **Loki** (for collecting logs), and **Grafana** (for visualizing them in dashboards). 5. `compose.traefik.yml`: Manages the **Traefik** reverse proxy, which handles secure routing and automatic HTTPS certificate generation from Let's Encrypt. **Nginx** 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: ```bash [ -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: ```bash podman-compose -f compose.database.yml -f compose.nats.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. 3. `compose.nats.yml`: Runs **NATS**, the message broker Rocket.Chat uses internally. Rocket.Chat is configured to reach a NATS service by default, so include this file unless you point the `NATS_URL` variable at an external NATS server. 4. `compose.monitoring.yml`: Enables monitoring with **Prometheus** (for collecting metrics), **Loki** (for collecting logs), and **Grafana** (for visualizing them in dashboards). 4. Once the containers are up, restart Nginx to begin proxying traffic to Rocket.Chat: ```bash 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: ```bash podman-compose -f compose.database.yml -f compose.nats.yml -f compose.yml -f podman.yml up -d ``` To check that all services have successfully started, use this command to list all running containers: ```bash podman ps -a ``` All services should show a status of `Up` . Some minor MongoDB services may also have a status of `Exited (0)`. ### Keep your deployment running after a reboot > [!WARNING] > TODO (remove before publishing): test both commands below on RHEL 8.10 and RHEL 9, and confirm the rootful equivalent, before this section goes live. The compose files set a `restart: always` policy, but Podman applies that policy at boot only when the restart service is enabled. Without the steps below, your workspace stays down after the server restarts. 1. Enable the Podman restart service for your user: ```bash systemctl --user enable podman-restart.service ``` 2. Allow your user’s services to keep running when you are not logged in: ```bash loginctl enable-linger $USER ``` 3. Restart the server, then confirm the containers came back: ```bash podman ps ``` > [!NOTE] > If you are running rootful Podman, enable the system service instead: `sudo systemctl enable podman-restart.service`. Linger is not needed in that case. You now have a working Rocket.Chat workspace on Podman. If you encounter issues during deployment, refer to the following resources for logging and troubleshooting: - [Logging Rocket.Chat](/v1/docs/deploy-with-podman#monitoring-and-logging-your-deployment) - [Deployment FAQ](/v1/docs/docker-deployment-faq) - [MongoDB best practices](https://www.mongodb.com/docs/) ## 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`, or `http://localhost:3000` to reach Rocket.Chat directly. - **For production**: Navigate to the [domain](/v1/docs/deploy-with-podman#3c-configure-domain-and-reverse-proxy) you configured. 1. On first load, a [setup wizard](/v1/docs/setup-your-workspace) 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](/v1/docs/rocketchat-cloud) during this process. ### Access monitoring dashboard You can access the Grafana dashboard via the URL corresponding to your [configured access method](/v1/docs/deploy-with-podman#3b-configure-monitoring): - 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. > [!WARNING] > 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](https://grafana.com/docs/grafana/latest/administration/user-management/user-preferences/). For more details on how to monitor your workspace metrics and logs, refer to the [Monitor Workspace Logs and Metrics guide](/v1/docs/access-workspace-logs). ## 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](/v1/docs/file-upload#configure-amazon-s3-file-storage), [Google Cloud Storage (GCS)](/v1/docs/file-upload#configure-google-cloud-storage), or [MinIO](/v1/docs/minio). Refer to the [File Uploads guide](/v1/docs/file-upload) for detailed instructions on configuring your preferred file storage solution. ## Next steps You’ve created your Rocket.Chat workspace with Podman and logged in. Next, explore the following resources to continue using your new workspace: - [User Guides](/user-guides): Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users. - [Workspace Administration](/workspace-administration): Administrators and owners can set and manage various configurations. - [Marketplace](/rocketchat-marketplace): Explore the available apps to enhance your workspace. --- ## Update Rocket.Chat on Podman > [!WARNING] > 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**](/v1/docs/updating-rocketchat). To update your Rocket.Chat version: 1. Modify the `RELEASE` variable in the `.env` file to point to the [release tag](https://github.com/RocketChat/Rocket.Chat/releases) of new version: ```bash RELEASE= ``` For example, `RELEASE=8.2.0` . 2. Run the following command to pull the new version image and restart the containers: ```bash podman-compose -f compose.yml up -d ``` > [!NOTE] > For more details, see the [Rocket.Chat Docker images documentation](/v1/docs/deploy-with-docker-docker-compose#rocketchat-docker-images). 3. After a few seconds, check that the new container is running: ```bash 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](/v1/docs/subscription) to verify the updated Rocket.Chat version. --- ## Update MongoDB on Podman > [!WARNING] > Before you proceed, **consult the** [**general guidelines for updating MongoDB**](/v1/docs/guidelines-for-updating-rocketchat#3-review-and-update-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. **Upgrade MongoDB** > [!WARNING] > Before you proceed, **consult the** [**general guidelines for updating MongoDB**](/v1/docs/guidelines-for-updating-rocketchat#3-review-and-update-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](https://hub.docker.com/r/mongodb/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. ```bash MONGODB_VERSION= ``` For example, `MONGODB_VERSION=8.2`. To confirm which MongoDB version your Rocket.Chat release supports, see [Check Your Supported Node.js and MongoDB Versions](/v1/docs/check-your-supported-nodejs-and-mongodb-versions). 3. Run the following command to pull the new image and restart the MongoDB container: ```bash podman-compose -f compose.database.yml -f compose.nats.yml -f compose.yml -f podman.yml down podman-compose -f compose.database.yml -f compose.nats.yml -f compose.yml -f podman.yml up -d ``` 4. After a few minutes, check that the new container is running: ```bash podman ps ``` You should see a new MongoDB container running with the updated version tag. **Downgrade MongoDB** 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 you switch binaries causes MongoDB to exit with an error, and the container restarts repeatedly. > [!NOTE] > Before you proceed, ensure that the MongoDB image for the targeted version is available on Docker Hub under [mongodb-community-server](https://hub.docker.com/r/mongodb/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: ```bash podman exec sh -c 'mongodump --archive' > db.dump ``` Replace `<mongo-container_name>` with the current name of the MongoDB container. 2. Enter the MongoDB container: ```bash podman exec -it   bash ``` 3. Access the MongoDB shell: ```bash mongosh ``` 4. Once in the shell, switch to the database: ```bash use rocketchat ``` 5. Check the current Feature Compatibility Version: ```bash 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: ```bash db.adminCommand({  setFeatureCompatibilityVersion: "",  confirm: true }) ``` 7. Confirm that the FCV now matches the target version: ```bash db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 }) ``` 8. Exit the mongo shell and shut down the MongoDB container: ```bash podman-compose -f compose.database.yml -f compose.nats.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: ```bash MONGODB_VERSION= ``` For example, MONGODB_VERSION=8.0 . 10. Then, pull and start the database container: ```bash podman-compose -f compose.database.yml -f compose.nats.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: ```bash 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: ```bash podman exec -it mongosh --eval "db.version()" ``` > [!NOTE] > For additional details about available versions and image tags, refer to the official [Rocket.Chat Docker image documentation](https://docs.rocket.chat/v1/docs/deploy-with-docker-docker-compose#rocketchat-docker-images). --- ## 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 ```bash podman ps -a ``` > [!WARNING] > 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` : ```bash podman exec 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. ```bash podman exec -i 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. ```bash mongorestore --uri mongodb+srv://:@cluster0.w2btl.mongodb.net --archive=db.dump ``` --- ### Set Rocket.Chat deployment environment variable on Podman [Environment variables](/v1/docs/deployment-environment-variables) are additional settings that impacts your workspace deployment and configuration. Refer to [Deployment Environment Variables](/v1/docs/deployment-environment-variables) to learn more about Rocket.Chat deployment environment variables. To set up an environment variable in Podman, 1. Go to your Rocket.Chat directory and open your [compose.yml](https://github.com/RocketChat/Docker.Official.Image/blob/main/compose.yml#L14) file: ```bash nano compose.yml ``` 2. Add the environment variable under the `environment` section of the `rocketchat` service. For example, to override the [SMTP Host setting](/v1/docs/configure-email), add: ```yaml services:  rocketchat:    ...    environment:      ...      OVERWRITE_SETTING_SMTP_Host: "my.smtp.server.com" ``` > [!NOTE] > **Tip**: This is the same section where `ROOT_URL`, `MONGO_URL`, etc is defined. 3. Restart the Rocket.Chat container with the new version: ```bash podman stop podman rm 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](/v1/docs/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: ```bash 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: ```bash podman-compose logs -f  # Shows realtime logs for a service managed by Podman Compose   podman logs       # Displays logs for the specific container   podman logs -f    # Shows real-time logs for a container podman logs --tail 10 # Displays the last 10 lines of logs   ``` > [!NOTE] > - 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: ```bash podman exec -it mongosh --eval "db.runCommand({ serverStatus: 1 })" ``` This will return useful metrics such as memory usage, active connections, replication state, and other operational details. > [!NOTE] > - 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: ```bash 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](/v1/docs/docker-deployment-faq) for detailed troubleshooting assistance.