--- title: "Deploy with Docker and Docker Compose" slug: "deploy-with-docker-docker-compose" description: "Set up Rocket Chat using Docker and Docker Compose. Ensure secure communication, operational resilience, and scalable collaboration on self-hosted servers." status: "update" updated: 2026-09-08T18:40:41Z published: 2026-09-08T18:40:41Z canonical: "docs.rocket.chat/deploy-with-docker-docker-compose" --- > ## 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 Docker and Docker Compose > [!NOTE] > **Each Rocket.Chat version is supported for six months post-release.** Deploying Rocket.Chat using Docker and Docker Compose is a highly recommended deployment method for running Rocket.Chat due to its simplicity and flexibility. In this guide, you'll learn how to: - [Deploy Rocket.Chat using Docker Compose](/v1/docs/deploy-with-docker-docker-compose#step-1-install-docker-docker-compose-and-git) - [Update Rocket.Chat to a newer version](/v1/docs/deploy-with-docker-docker-compose#update-rocketchat-on-docker) - [Update MongoDB to a compatible version on Docker](/v1/docs/deploy-with-docker-docker-compose#update-mongodb-on-docker) - [Back up and restore your MongoDB database](/v1/docs/deploy-with-docker-docker-compose#back-up-and-restore-mongodb-data-on-docker) - [Configure Rocket.Chat using environment variables on Docker](/v1/docs/deploy-with-docker-docker-compose#set-rocketchat-deployment-environment-variable-on-docker) 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 > [!TIP] > - For organizations that require FIPS compliance, visit the [FIPS Compliance Guide](/v1/docs/fips-compliance-guide) for more details. > - If you’re using the built in Bitnami MongoDB images, refer to this [forum post](https://forums.rocket.chat/t/action-required-docker-compose-moving-from-bitnami-to-official-mongodb-image/22693) to upgrade to the official MongoDB 8.0 image required for Rocket.Chat 8.0. ## 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 Docker. - **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. ## Step 1: Install Docker, Docker Compose, and Git This guide is intended for Linux users. For other OS or alternative installation methods, refer to the official [Docker documentation](https://docs.docker.com/compose/install/) and [Git documentation](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git). 1. [Docker](https://docs.docker.com/install), [Docker Compose](https://docs.docker.com/compose/install/) (Docker Compose v2) and [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) are required. If you don't have them installed, you can conveniently set them up in Linux distributions with the command below: ```bash curl -L https://get.docker.com | sh # Install Docker sudo apt install git # Install Git ``` 2. To run Docker commands without using `sudo`, add your current user to the Docker group. 1. Find your current username with this command: ```bash whoami ``` 2. Add your user to the docker group, substituting $USER with your username if needed: ```bash sudo usermod -aG docker $USER ``` 3. Reboot for the change to take effect: ```bash sudo reboot ``` With Docker and Git in place, you are ready to fetch the Rocket.Chat configuration files. ## 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 Docker 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 Docker 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 the exact version of Rocket.Chat you wish to deploy. A full list of available stable releases is on the [Rocket.Chat release notes](https://github.com/RocketChat/Rocket.Chat/releases). For example, to set Rocket.Chat 8.8.0: ```plaintext RELEASE=8.8.0 ``` > [!NOTE] > For production environments, it’s strongly recommended to specify a fixed version number (e.g., 8.8.0) instead of using `latest`. This prevents unexpected issues from automatic, breaking updates. > [!WARNING] > MongoDB 8.x may fail to start on Ubuntu 26.04 due to an upstream MongoDB compatibility issue. For now, use Ubuntu 24.04 LTS or another supported Ubuntu version instead. See the [MongoDB note](https://www.mongodb.com/docs/manual/release-notes/8.2/#mongodb-8-0-and-newer-are-incompatible-with-kernel-6-19) for more details. ### 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 pathGrafana via a subdomain 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`. 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 Docker 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, use the default values for these variables in the `.env` : ```plaintext DOMAIN=localhost ROOT_URL=http://localhost ``` Your workspace will be accessible at `http://localhost:3000` once successfully deployed. ### 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 Docker. Traefik cannot provision a certificate for a domain it cannot reach. For a publicly accessible and secure production deployment, 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 ``` Once these variables are set, you can proceed to adding [optional configurations](/v1/docs/deploy-with-docker-docker-compose#3d-optional-configurations) as required. **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 Docker. #### 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: ```plaintext 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. Install Certbot, the Let's Encrypt certificate client. For Debian-based distributions such as Debian and Ubuntu use : ```bash sudo apt update sudo apt install certbot ``` For RPM-based distributions such as Redhat and Centos, use: ```bash sudo yum install yum-utils sudo yum install certbot ``` > Installation commands may vary depending on your Linux distribution and version. 2. 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-docker-docker-compose#3b-configure-monitoring), replace `<subdomain.com>` with the Grafana subdomain (e.g., `grafana.your-domain.com`), otherwise remove it. #### 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: ```bash sudo apt-get install nginx ``` 2. Backup the default config file for reference: ```bash cd /etc/nginx/sites-available sudo mv default default.reference ``` 3. Create a new site configuration for Rocket.Chat: ```bash sudo nano /etc/nginx/sites-available/default ``` 4. Add your Nginx configuration to the file: The configuration you choose depends on how you configured Grafana during [monitoring](/v1/docs/deploy-with-docker-docker-compose#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: ```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;     } } 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. 5. 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-docker-docker-compose#step-4-launch-the-rocketchat-deployment). > [!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] > When using an external MongoDB instance, do not include `compose.database.yml` in your Docker Compose command, as it starts the bundled MongoDB container. Add `compose.nats.yml` to the command to start NATS separately. > > For full setup steps, including replica set requirements, connection string examples, and how to adjust the Compose command, see [Configure External MongoDB for Rocket.Chat.](/v1/docs/configure-external-mongodb-for-rocket-chat) 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-docker-docker-compose#3c-configure-domain-and-reverse-proxy): **Traefik** 1. Run the following command to download all the required Docker images (Rocket.Chat, MongoDB, Traefik, etc.) and start the containers in the background: ```bash docker compose \  -f compose.monitoring.yml \  -f compose.traefik.yml \  -f compose.database.yml \  -f compose.yml \  -f compose.nats.yml \  -f docker.yml \  up -d ``` Here’s a brief summary of what each file in the command does: a. `compose.yml`: Starts the Rocket.Chat application. b. `compose.database.yml`: Starts and manages the bundled MongoDB database that Rocket.Chat relies on by default. c. `compose.monitoring.yml`: Enables monitoring with **Prometheus** for collecting metrics, **Loki** for collecting logs, and **Grafana** for visualizing them in dashboards. d. `compose.traefik.yml`: Manages the **Traefik** reverse proxy, which handles routing and automatic HTTPS certificate generation from Let's Encrypt. e. `compose.nats.yml`: Starts NATS, the internal message broker used for communication between Rocket.Chat services. f. `docker.yml`: Provides Docker-specific configuration required to run the deployment with Docker Compose. **Nginx** 1. Navigate back to the cloned Rocket.Chat directory where you have the compose files. 2. Download the required Docker images and start your Rocket.Chat services, explicitly omitting the Traefik configuration file (compose.traefik.yml): ```bash docker compose \  -f compose.monitoring.yml \  -f compose.database.yml \  -f compose.yml \  -f compose.nats.yml \  -f docker.yml \  up -d ``` Here’s a brief summary of what each file in the command does: a. `compose.yml`: Starts the Rocket.Chat application. b. `compose.database.yml`: Starts and manages the bundled MongoDB database that Rocket.Chat relies on by default. c. `compose.monitoring.yml`: Enables monitoring with **Prometheus** for collecting metrics, **Loki** for collecting logs, and **Grafana** for visualizing them in dashboards. d. `compose.nats.yml`: Starts NATS, the internal message broker used for communication between Rocket.Chat services. e. `docker.yml`: Provides Docker-specific configuration required to run the deployment with Docker Compose. 3. 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 docker compose -f compose.database.yml -f compose.yml -f compose.nats.yml up -d ``` To check that all services have successfully started, use this command to list all running containers: ```bash docker ps -a ``` All services should show a status of `Up`. Some minor MongoDB services may also have a status of `Exited (0)`. If you encounter issues during deployment, refer to the following resources for logging and troubleshooting: - [Logging Rocket.Chat](/v1/docs/deploy-with-docker-docker-compose#back-up-and-restore-mongodb-data-on-docker) - [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:3000`. - **For production**: Navigate to the [domain](/v1/docs/deploy-with-docker-docker-compose#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-docker-docker-compose#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. --- ## Update Rocket.Chat on Docker > [!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/guidelines-for-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.6.0`. 2. From your deployment directory (the folder containing your compose files and .env), run the same set of compose files you originally deployed with to pull the new image and restart the Rocket.Chat container. For example: ```bash docker compose -f compose.database.yml -f compose.yml up -d ``` Include every compose file used in your original deployment command (for example, monitoring or Traefik files), otherwise those services are dropped from the project definition. > [!NOTE] > Refer to [the official documentation](/v1/docs/deploy-with-docker-docker-compose#rocketchat-docker-images) for more details on Rocket.Chat Docker images. 3. After a few minutes, check that the new container is running: ```bash docker ps ``` You should see a new Rocket.Chat container running with the updated version tag. 4. Go to **Manage** > **Workspace** to verify the updated Rocket.Chat version and its support window. --- ## Update MongoDB on Docker > [!TIP] > If you’re using the built in Bitnami MongoDB images, refer to this [forum post](https://forums.rocket.chat/t/action-required-docker-compose-moving-from-bitnami-to-official-mongodb-image/22693) to upgrade to the official MongoDB 8.0 image required for Rocket.Chat 8.0. 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 Docker, 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.0`. 3. Run the following command to pull the new image and restart the MongoDB container: ```bash docker compose -f  compose.database.yml up -d ``` > [!NOTE] > Refer to [the official documentation](/v1/docs/deploy-with-docker-docker-compose#rocketchat-docker-images) for more details on Rocket.Chat Docker images. 4. After a few minutes, check that the new container is running: ```bash docker 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 switching binaries will cause MongoDB to exit with an error and the container will repeatedly restart. > [!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 docker 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 docker 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 docker compose -f compose.database.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 docker compose -f  compose.database.yml up -d ``` 11. After a few minutes, confirm that the new MongoDB container is running: ```bash docker 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 docker exec -it mongosh --eval "db.version()" ``` --- ## Set Rocket.Chat deployment environment variable on Docker [Environment variables](/v1/docs/deployment-environment-variables) are additional settings that impact your workspace deployment and configuration. Refer to the [official documentation](/v1/docs/deployment-environment-variables) to learn more about Rocket.Chat deployment environment variables. To set up an environment variable in Docker, 1. Go to your Rocket.Chat directory and open your `compose.yml` 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. are defined. 3. Restart your Rocket.Chat container to apply the changes: ```bash docker compose stop rocketchat docker compose rm rocketchat docker compose up -d rocketchat ``` For a full list of available environment variables, refer to [Deployment Environment Variables](/v1/docs/deployment-environment-variables). --- ## Additional operations ### Back up and restore MongoDB data on Docker 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 Docker. #### Back up your MongoDB database on Docker 1. List all running Docker containers to find the name of your MongoDB service ```bash docker 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 docker exec sh -c 'mongodump --archive' > db.dump ``` When successful, you should see `db.dump` file in the current directory. #### Restore MongoDB database backup on Docker To restore the data, use mongorestore inside the MongoDB container, piping the data from your local db.dump file. ```bash docker 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 ``` --- ### Rocket.Chat Docker images Rocket.Chat provides an [official Docker image repository](https://hub.docker.com/r/rocketchat/rocket.chat/tags) maintained by the Rocket.Chat team. When setting up your deployment, you specify which Rocket.Chat version to use by adding the image tag. The base image path is: `registry.rocket.chat/rocketchat/rocket.chat:<tag>`. Here are the available image tags: 1. **Specific release tags** (recommended for production): You can lock your workspace to a specific Rocket.Chat version using a fixed version tag. This is the best practice for production environments because it prevents unexpected major updates and ensures you only upgrade when you are ready to perform backups and check database compatibility. For example, `registry.rocket.chat/rocketchat/rocket.chat:6.6.0`. Check out the [release notes](https://github.com/RocketChat/Rocket.Chat/releases) or [Docker Hub tags](https://hub.docker.com/r/rocketchat/rocket.chat/tags/) for the various Rocket.Chat releases. 2. **Latest** **tag**: The `latest` tag points to the most recent Rocket.Chat build available in the registry. This may include recent changes and is useful for testing newer versions. Using this tag for production deployments is not recommended. 3. **Develop** **build**: The `develop` tag tracks the develop branch and includes the newest, untested changes. This tag is intended for development and experimentation only and should not be used in production. --- ### 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 Docker environment: ```bash docker ps        # Shows currently running containers with details like ID, status, and ports   docker ps -a     # Lists all containers, including stopped ones   docker compose ps  # Lists services managed by Docker Compose   ``` 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 docker compose logs -f  # Shows realtime logs for a service managed by Docker Compose   docker logs       # Displays logs for the specific container   docker logs -f    # Shows real-time logs for a container docker 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 Docker logging system captures these stdout logs, making them accessible through the docker logs command 3. To inspect MongoDB’s health, run: ```bash docker exec -it mongosh --eval "db.runCommand({ serverStatus: 1 })" ``` This command returns detailed MongoDB server status information. > [!NOTE] > Replace `<mongodb_container_name>` with your MongoDB container name. 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/deployment-faq) for detailed troubleshooting assistance. To configure your workspace and onboard your team, see [Accessing your workspace](/v1/docs/accessing-your-workspace). --- ## Next steps Explore the following resources to continue setting up your workspace: - [User Guides](/v1/docs/user-guides): Learn the basics of your Rocket.Chat account, the types of rooms, and how to communicate with your workspace users. - [Workspace Administration](/v1/docs/workspace-administration): Administrators and owners can set and manage various configurations. - [Marketplace](/v1/docs/rocketchat-marketplace): Explore the available apps to enhance your workspace.