Migrate from Bitnami MongoDB to the official MongoDB Image

This section covers migrating a Docker workspace from Bitnami MongoDB 6.0 to the official MongoDB 8.2 image.

This guide assumes you are using the official rocketchat-compose repository, 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

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:

   cd <path/to/rocketchat-compose>
   docker compose -f compose.database.yml -f compose.yml ps

   Replace <path/to/rocketchat-compose> with the path to your rocketchat-compose directory.

2. Create a backup directory:

   mkdir -p ./mongodb-backup

3. Dump the current database:

   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:

   ls -lh ./mongodb-backup/

Step 2: Stop the current deployment

Run this command to stop all the services:

docker compose -f compose.database.yml -f compose.yml down

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 :

git checkout main
git pull origin main

Alternatively, use the specific 2.0.0 tag:

git checkout 2.0.0

Step 4: Update enviroment configuration

1. Configure your .env file:

   nano .env

2. Add or verify these MongoDB settings:

   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:

   docker volume ls | grep rocketchat-compose

2. Rename the old MongoDB volume as backup

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

   mv mongodb_vol mongodb_vol_60_backup

Step 6: Start the new MongoDB 8.2

1. Start only the database services:

   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:

   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:

   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:

   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:

   docker compose -f compose.database.yml exec mongodb mongosh --eval "use rocketchat; db.stats()"

3. Check that collections were restored:

   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:

   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:

   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:

   docker compose logs -f rocketchat

   Look for the startup banner showing the Rocket.Chat and  MongoDB version:

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