[ACTION REQUIRED] Docker Compose Moving from Bitnami to Official MongoDB Image

Announcements
1

Upgrading Rocket.Chat Docker Compose to MongoDB 8.2

This guide explains how to migrate from the current Bitnami MongoDB 6.0 deployment to the official MongoDB 8.2 image.

Background & Why This Upgrade Is Necessary

Over the past several years, Bitnami has been the go-to provider for MongoDB images in our Docker Compose deployments. However, significant changes in the community have necessitated a shift in strategy:

Recent Events:

  1. Bitnami Acquisition Impact: Bitnami was acquired by VMware (which itself was previously acquired by Broadcom). Following this acquisition, the decision was made to discontinue support for their legacy images and charts that have been the foundation for countless deployments in the community. Rather than continue community support, users are now directed to paid enterprise solutions.

  2. MongoDB CVE & Lack of Updates: A critical security vulnerability (CVE) was recently discovered in MongoDB. With Bitnami no longer publishing updated images, we face an impossible situation: we cannot recommend users simply update their image to patch the vulnerability, as Bitnami will not be releasing any new images.

  3. MongoDB EOL Versions: MongoDB ends support for older versions, so Rocket.Chat needs to keep updating which versions we support. MongoDB 7 and 8 are not present and will not be released by Bitnami.

The Solution: To ensure security, continued support, and access to updated MongoDB versions, we are migrating to the official MongoDB Docker images published by MongoDB. These images are actively maintained by MongoDB and receive regular security updates and feature enhancements. We’re upgrading to MongoDB 8.2, the latest version, which includes the latest security patches and performance improvements.

Important Notes Before You Begin

:warning: Please read carefully:

  • If you’re already using an external MongoDB instance (not running MongoDB via the Docker Compose setup), you are not affected by this change. You can skip this migration.

  • Data backup is critical. Migrating to MongoDB 8.2 with different volume paths requires careful data handling. A backup is essential before proceeding.

  • After this migration: You’ll be running the official MongoDB Community Server image with modern volume paths and proper initialization, ensuring you receive security updates and can upgrade to future MongoDB versions.

What’s Changing

The latest version of our compose (2.0.0) introduces several important changes:

  1. MongoDB Image: Switches from bitnami/mongodb:6.0 to official mongodb/mongodb-community-server:8.2-ubi8

  2. MongoDB Version: Upgrades from MongoDB 6.0.x to 8.2.x

  3. Volume Path: Changes from /bitnami/mongodb to /data/db (standard MongoDB path)

  4. Initialization: Adds explicit replica set initialization and permission fixing containers

  5. Healthchecks: Enables proper MongoDB healthchecks for better orchestration

Prerequisites

Before starting the upgrade:

  1. Stop all incoming traffic to your Rocket.Chat instance

  2. Backup your current deployment (see backup section below)

  3. Ensure you have enough disk space for both the backup and the new data

  4. Have at least 30 minutes of downtime window

Migration Strategy

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

First, ensure your current deployment is running:


cd /path/to/rocketchat-compose

docker compose -f compose.database.yml -f compose.yml ps

Create a backup directory and dump the current database:


# Create backup directory

mkdir -p ./mongodb-backup

# Run mongodump from the running MongoDB container

docker compose -f compose.database.yml exec mongodb mongodump \

--out=/tmp/backup \

--db=rocketchat

# Copy the backup from container to host

docker compose -f compose.database.yml cp mongodb:/tmp/backup ./mongodb-backup/

Verify the backup was created:


ls -lh ./mongodb-backup/backup/rocketchat/

You should see .bson and .metadata.json files for all collections.

Step 2: Stop Current Deployment

Stop all services:


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

Important: Do NOT use -v flag, as this would delete your volumes. We want to keep them as a safety backup.

Step 3: Update Repository

Pull the latest changes:


# Update to the latest main branch

git checkout main

git pull origin main

# Or use the specific 2.0.0 tag

git checkout 2.0.0

Step 4: Update Environment Configuration

The new version adds MongoDB-specific variables. Update your .env file:


# Edit .env file

nano .env

Add or verify these MongoDB settings:


# MongoDB version (new in fix-dir-ownership branch)

MONGODB_VERSION=8.2

# MongoDB user ID for file permissions

MONGODB_USER_ID=1001

# MongoDB replica set name

MONGODB_REPLICA_SET_NAME=rs0

# MongoDB hostname

MONGODB_ADVERTISED_HOSTNAME=mongodb

Step 5: Rename or Archive Old Volume

To ensure a clean migration, we’ll use a fresh volume for MongoDB 8.2:


# List current volumes

docker volume ls | grep rocketchat-compose

# 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 alpine sh -c "cp -av /from/. /to/"

Alternatively, if using a local directory path (HOST_PATH):


# If you were using MONGODB_HOST_PATH

mv mongodb_vol mongodb_vol_60_backup

Step 6: Start New MongoDB 8.2

Start only the database services:


docker compose -f compose.database.yml up -d

This will:

  1. Start the permission fixing container

  2. Initialize the MongoDB 8.2 replica set

  3. Start MongoDB with proper healthchecks

Check the logs to ensure everything starts correctly:


# Watch MongoDB startup

docker compose -f compose.database.yml logs -f mongodb

# Check init container

docker compose -f compose.database.yml logs mongodb-init-container

Wait for MongoDB to be healthy:


docker compose -f compose.database.yml ps

Step 7: Restore Data to MongoDB 8.2

Copy your backup into the new MongoDB container and restore:


# Copy backup to new container

docker compose -f compose.database.yml cp ./mongodb-backup/backup mongodb:/tmp/

# Restore the data

docker compose -f compose.database.yml exec mongodb mongorestore \

--db=rocketchat \

/tmp/backup/rocketchat/

# Verify the restore

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

Check that collections were restored:


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

Step 8: Start Rocket.Chat

Now start the full stack:


docker compose -f compose.database.yml -f compose.yml up -d

Monitor the Rocket.Chat logs:


docker compose logs -f rocketchat

Look for the startup banner showing MongoDB version 8.2:


+----------------------------------------------+

| SERVER RUNNING |

+----------------------------------------------+

| Rocket.Chat Version: 7.5.0 |

| MongoDB Version: 8.2.x |

+----------------------------------------------+

Step 9: Verify Deployment

  1. Access your workspace: Open http://localhost:3000 (or your configured URL)

  2. Check basic functionality:

  • Login with your admin account

  • Send a test message

  • Check that channels and users appear correctly

  • Verify uploaded files are accessible

  1. Check containers:

docker compose ps

All containers should show “Up” status.

Step 10: Cleanup (After Verification)

Once you’ve verified everything works (wait at least 24-48 hours):


# Remove old volume backup (only after thorough testing!)

docker volume rm rocketchat-compose_mongodb_data_60_backup

# Or if using local directory

rm -rf mongodb_vol_60_backup

# Remove backup files

rm -rf ./mongodb-backup

Rollback Procedure

If you encounter issues and need to rollback:

Quick Rollback (if you haven’t deleted old volumes)


# Stop new deployment

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

# Switch back to 1.0.0 (old version with bitnami image)

git checkout 1.0.0

# Restore old volume

docker volume rm rocketchat-compose_mongodb_data

docker run --rm -v rocketchat-compose_mongodb_data_60_backup:/from -v rocketchat-compose_mongodb_data:/to alpine sh -c "cp -av /from/. /to/"

# Start old deployment

docker compose -f compose.database.yml -f compose.yml up -d

Troubleshooting

Permission Issues

If you see permission errors in MongoDB logs:


# Check ownership

docker compose exec mongodb stat -c "%u %g %n" /data/db

# The fix-permission container should handle this, but you can manually fix:

docker compose run --rm --user root mongodb chown -R 1001:1001 /data/db

Replica Set Not Initialized

If Rocket.Chat can’t connect because replica set isn’t initialized:


# Manually initialize

docker compose exec mongodb mongosh --eval "rs.initiate({_id: 'rs0', members: [{_id: 0, host: 'mongodb:27017'}]})"

MongoDB Won’t Start

Check the logs:


docker compose logs mongodb

docker compose logs mongodb-init-container

docker compose logs mongodb-fix-permission-container

Common issues:

  • Volume permission problems (should be auto-fixed by fix-permission container)

  • Port conflicts (check if 27017 is available)

  • Memory issues (MongoDB 8.2 may need more RAM)

Restore Fails

If mongorestore fails:


# Try with --drop to replace existing data

docker compose exec mongodb mongorestore --drop --db=rocketchat /tmp/backup/rocketchat/

# Or restore specific collections

docker compose exec mongodb mongorestore --db=rocketchat --collection=users /tmp/backup/rocketchat/users.bson

Alternative: Fresh Install Migration

If you prefer a cleaner approach:

  1. Deploy a fresh MongoDB 8.2 instance on the new branch

  2. Use mongodump/mongorestore to migrate data

  3. Update your .env with new configuration

  4. Keep old deployment as backup until verified

Notes

  • Downtime: Expect 15-30 minutes of downtime for the migration

  • Testing: Test the upgrade in a staging environment first if possible

  • Backups: Keep backups for at least a week after upgrade

  • MongoDB 8.2: Requires MongoDB driver compatibility - ensure your Rocket.Chat version supports it

  • Volume Changes: The volume path change (/bitnami/mongodb → /data/db) requires data migration, you cannot simply reuse the old volume

Post-Upgrade Checklist

  • All users can login successfully

  • Messages are visible and can be sent

  • File uploads work correctly

  • Integrations and webhooks function properly

  • Federation (if used) is operational

  • Mobile app push notifications work

  • Monitoring shows healthy metrics

  • Backup process is updated for new paths

  • Old volume backup is safely stored

[ACTION REQUIRED] Helm Chart Moving from Bitnami to Official MongoDB Chart