--- title: "Migrate from Bitnami MongoDB to the official MongoDB Image" slug: "migrate-from-bitnami-mongodb-to-the-official-mongodb-image" updated: 2026-10-20T14:57:07Z published: 2026-10-20T14:57:07Z canonical: "docs.rocket.chat/migrate-from-bitnami-mongodb-to-the-official-mongodb-image" --- > ## 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. # Migrate from Bitnami MongoDB to the official MongoDB Image Bitnami MongoDB images are no longer maintained, leaving deployments without critical security updates or access to newer MongoDB versions. To address this, Rocket.Chat is migrating to the official MongoDB images, starting with MongoDB 8.0 for continued support and security. This guide explains how to migrate from an existing Bitnami MongoDB 6.0 deployment to the official MongoDB 8.x image required for Rocket.Chat 8.0 and above. ## Before you begin - If you’re using an external MongoDB instance (not via Docker Compose), this migration does not apply to you. - Before starting this migration, it’s important to back up your data as it may involve changes to volume paths. - Ensure you have enough disk space for both the backup and the new data. - Communicate at least 30 minutes of downtime window to your users. - After migration, you’ll be running the official MongoDB Community Server image. Select your current deployment method that uses Bitnami MongoDB setup below and follow the appropriate migration steps: **Docker** This section covers migrating a Docker workspace from Bitnami MongoDB 6.0 to the official MongoDB 8.2 image. > [!NOTE] > This guide assumes you are using the official [rocketchat-compose repository](https://github.com/RocketChat/rocketchat-compose/tree/main), which splits services across multiple compose files (`compose.yml`, `compose.database.yml`, `compose.traefik.yml`, etc.). If you are using a different setup, your steps may differ slightly. The latest version of our compose (2.0.0) introduces several important changes: - **MongoDB image**: Switches from bitnami/mongodb:6.0 to official mongodb/mongodb-community-server:8.2-ubi8. - **MongoDB version**: Upgrades from MongoDB 6.0.x to 8.2.x - **Volume path**: Changes from /bitnami/mongodb to /data/db which is the standard MongoDB path. - **Initialization**: Adds explicit replica set initialization and permission fixing containers. - **Healthchecks**: Enables proper MongoDB healthchecks for better orchestration. ## Moving your Docker workspace from Bitnami to the official MongoDB image > [!NOTE] > The following `docker compose` commands are interchangeable to `podman-compose`. Since MongoDB 6.0 and 8.2 have different data formats and the volume paths are changing, the safest approach is to use `mongodump` and `mongorestore`. ### Step 1: Backup current MongoDB data 1. Go to your `rocketchat-compose` directory and confirm that your current deployment is running: ```bash cd docker compose -f compose.database.yml -f compose.yml ps ``` Replace with the path to your `rocketchat-compose` directory. 2. Create a backup directory: ```bash mkdir -p ./mongodb-backup ``` 3. Dump the current database: ```bash docker compose -f compose.database.yml exec -T mongodb mongodump --uri='mongodb://localhost:27017/?directConnection=true' \ --archive --gzip \ --db=rocketchat > mongodb-backup/backup.gz ``` 4. Verify the backup was created: ```bash ls -lh ./mongodb-backup/ ``` ### Step 2: Stop the current deployment Run this command to stop all the services: ```bash docker compose -f compose.database.yml -f compose.yml down ``` > [!NOTE] > Avoid using `-v` flag, as this would delete your volumes. You have to keep them as a safety backup. ### Step 3: Update the rocketchat-compose directory Pull the latest changes for the rocketchat-compose directory : ```bash git checkout main git pull origin main ``` Alternatively, use the specific 2.0.0 tag: ```bash git checkout 2.0.0 ``` ### Step 4: Update enviroment configuration 1. Configure your .env file: ```bash nano .env ``` 2. Add or verify these MongoDB settings: ```bash MONGODB_VERSION=8.2 MONGODB_USER_ID=1001 MONGODB_REPLICA_SET_NAME=rs0 MONGODB_ADVERTISED_HOSTNAME=mongodb ``` ### Step 5: Rename or archive old volume To ensure a clean migration, you’ll need a fresh volume for MongoDB 8.2: 1. List the current volumes: ```bash docker volume ls | grep rocketchat-compose ``` 2. Rename the old MongoDB volume as backup ```bash docker volume create rocketchat-compose_mongodb_data_60_backup docker run --rm -v rocketchat-compose_mongodb_data:/from -v rocketchat-compose_mongodb_data_60_backup:/to docker.io/alpine sh -c "cp -av /from/. /to/" ``` Alternatively, if using a local directory path (MONGODB_HOST_PATH): ```bash mv mongodb_vol mongodb_vol_60_backup ``` ### Step 6: Start the new MongoDB 8.2 1. Start only the database services: ```bash docker compose -f compose.database.yml up -d ``` This will start the permission fixing container, initialize the MongoDB 8.2 replica set, and start MongoDB with proper healthchecks. 2. Check the logs to ensure everything starts correctly: ```bash docker compose -f compose.database.yml logs -f mongodb docker compose -f compose.database.yml logs mongodb-init-container ``` 3. Wait for MongoDB to be healthy: ```bash docker compose -f compose.database.yml ps ``` ### Step 7: Restore data to the new MongoDB 8.2 container 1. Copy your backup into the new MongoDB container and restore: ```bash cat mongodb-backup/backup.gz | docker compose -f compose.database.yml exec -T mongodb mongorestore --uri='mongodb://localhost:27017/?directConnection=true' --archive --gzip ``` 2. Verify the restore: ```bash docker compose -f compose.database.yml exec mongodb mongosh --eval "use rocketchat; db.stats()" ``` 3. Check that collections were restored: ```bash docker compose -f compose.database.yml exec mongodb mongosh --eval "use rocketchat; db.getCollectionNames()" ``` ### Step 8: Start the workspace 1. Once the database restore is verified, start all other services required for Rocket.Chat: ```bash docker compose -f compose.monitoring.yml -f compose.traefik.yml -f compose.yml -f docker.yml up -d ``` 2. To check that all services have successfully started, use this command to list all running containers: ```bash docker ps ``` All services should show a status of Up . Some minor MongoDB services may also have a status of Exited (0). 3. Monitor the Rocket.Chat logs: ```bash docker compose logs -f rocketchat ``` Look for the startup banner showing the Rocket.Chat and MongoDB version: ```bash +----------------------------------------------+ | SERVER RUNNING | +----------------------------------------------+ ``` ### Step 9: Verify your deployment To confirm that the migration was succesful, 1. Visit your workspace URL and login with your admin account. 2. Verify channels, users, messages, and uploaded files are intact. 3. Send a test message. For troubleshooting, rollback, and cleanup, refer to the [Docker Compose Moving from Bitnami to Official MongoDB Image forum](https://forums.rocket.chat/t/action-required-docker-compose-moving-from-bitnami-to-official-mongodb-image/22693). **Snaps** This section covers migrating from a Rocket.Chat Snap installation which bundles its own bitnami MongoDB internally to the Docker Compose deployment running the official MongoDB 8.0 image. > [!NOTE] > The Snap installation may name its database based on your server configuration (not necessarily `rocketchat`), so a key part of this guide is identifying and correctly remapping your database name during restore. ## Step 1: Install Docker, Docker Compose, and Git [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 for setting up Docker deployments. 1. 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 proceed with the migration. ## Step 2: Back up your Snap workspace 1. Create the Snap database backup: ```bash sudo snap run rocketchat-server.backupdb ``` The output will show the backup file location similar to `/var/snap/rocketchat-server/common/backup/rocketchat_backup_YYYYMMDD.HHMM.tar.gz` . 2. Copy the backup filename similar to `rocketchat_backup_YYYYMMDD.HHMM.tar.gz` and save for later. 3. Stop all the Snap services: ```bash sudo snap stop rocketchat-server ``` ## Step 3: Extract the Snap backup 1. Navigate to the backup directory: ```bash cd /var/snap/rocketchat-server/common/backup/ ``` 2. Extract the backup using the exact database backup filename: ```bash sudo tar xzvf rocketchat_backup_YYYYMMDD.HHMM.tar.gz ``` Replace `rocketchat_backup_YYYYMMDD.HHMM.tar.gz` with the exact filename you copied earlier. 3. Verify the dump came out and copy the database folder name inside: ```bash ls dump/ ``` The folder name inside `dump/` is your actual Snap database name. It may be `rocketchat`, `parties`, or something else entirely based on your server's configuration. ## Step 4: Deploy Rocket.Chat with Docker To get foundational understanding on Rocket.Chat Docker deployment, visit [Deploy with Docker and Docker Compose](/v1/docs/deploy-with-docker-docker-compose). 1. Clone the official [rocketchat-compose repository](https://github.com/RocketChat/rocketchat-compose) in your preferred working directory using Git and navigate to the cloned directory: ```bash git clone --depth 1 https://github.com/RocketChat/rocketchat-compose.git cd rocketchat-compose ``` 2. Copy the example environment file to `.env`: ```bash cp .env.example .env ``` 3. Configure your `.env` file: ```bash nano .env ``` 1. Update these variables: | **Field** | Description | Example | | --- | --- | --- | | **RELEASE** | The 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). | In this migration guide, we are deploying `8.2.0`. | | **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 | For example, ```plaintext RELEASE=8.2.0 ROOT_URL=https://example.com LETSENCRYPT_ENABLED=true LETSENCRYPT_EMAIL=demo@email.com TRAEFIK_PROTOCOL=https ``` 2. Add or update these MongoDB settings: ```bash MONGODB_VERSION=8.0 MONGODB_USER_ID=1001 MONGODB_REPLICA_SET_NAME=rs0 MONGODB_ADVERTISED_HOSTNAME=mongodb ``` ## Step 5: Start MongoDB 1. Start the database service to run MongoDB 8.0: ```bash docker compose -f compose.database.yml up -d ``` 2. Wait until MongoDB is fully healthy before proceeding: ```bash docker compose -f compose.database.yml ps ``` 3. Copy the mongodb container name and save for later. You’ll need it in step 6. All database containers should show healthy or up status before continuing. ## Step 6: Copy and restore the Snap backup to Docker 1. Copy the extracted dump folder into the MongoDB container: ```bash docker cp /var/snap/rocketchat-server/common/backup/dump//. \  rocketchat-compose-mongodb-1:/tmp/dbrestore/ ``` Replace `<your-db-name>` with the database folder name you noted in Step 3. 2. Now restore directly into the rocketchat database: ```bash docker exec -e HOME=/tmp rocketchat-compose-mongodb-1 mongorestore \  --uri='mongodb://localhost:27017/?directConnection=true' \  --dir=/tmp/dbrestore \  --db=rocketchat ``` 3. To verify the restore, enter mongosh: ```bash docker exec -it mongosh ``` Replace `<mongodb-container>` with the actual container name. 4. Then once inside the mongosh terminal, run these commands one at a time: ```bash use rocketchat db.users.countDocuments() db.getCollectionNames().length ``` You should see the same number of users previously on your snap workspace. If the numbers don’t look right, re-examine the dump folder contents and retry the restore. 5. Exit the mongosh container: ```bash exit ``` ## Step 7: Start the workspace 1. Once the database restore is verified, go to the rocketchat-compose directory and start all other services required for Rocket.Chat: ```bash docker compose -f compose.monitoring.yml -f compose.traefik.yml -f compose.yml -f docker.yml up -d ``` 2. 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). 3. Monitor the Rocket.Chat logs: ```bash docker compose logs -f rocketchat ``` Look for the startup banner showing the Rocket.Chat and MongoDB version: ```bash +----------------------------------------------+ | SERVER RUNNING | +----------------------------------------------+ | Rocket.Chat Version: 8.2.0 | | MongoDB Version: 8.0.x | +----------------------------------------------+ ``` ## Step 8: Verify your deployment To confirm that the migration was succesful, 1. Visit your workspace URL and login with your admin account. 2. Verify channels, users, messages, and uploaded files are intact. 3. Send a test message.