search

MongoDB Update

Starting with Helmut4 v4.12, it is now possible to upgrade the internal MongoDB database from version 3.4 to a current supported version (8.2).

circle-exclamation

This is a major database upgrade. The procedure modifies the storage layer and must be performed carefully. An incorrect execution may result in an unusable or lost database.

Please read the following instructions completely before starting and ensure you understand every step.

circle-info

hashtag
MongoDB update support

Our support team can perform the migration together with you. We strongly recommend scheduling an appointment.

Remote access will be required (SSH access to the server and a Windows or macOS client for coordination).

hashtag
Step 0 – Maintenance Window

Perform the upgrade during a dedicated maintenance window.

The migration itself typically takes ~30 minutes, however you should reserve at least 1 hour to allow for verification and unexpected delays.

hashtag
Step 1 – Backups (Required)

Before continuing, create two independent backups and store them outside your normal backup directories.

Create:

  1. A Helmut4 configuration backup via the Preferences tab in the Helmut4 UI

  2. A database backup using the mongodb_backup container

circle-exclamation

Do not proceed unless both backups were successfully created and verified.

hashtag
Step 2 – Stop the System

Stop the Helmut4 stack and wait until all containers are fully stopped.

Then open Portainer → Volumes and locate:

helmut4_mcc_mongodb

triangle-exclamation

hashtag
🚨 This is the point of no return. 🚨

Only continue if your backups exist and are accessible.

Delete the volume.

If you are running a cluster environment, repeat this step on every worker node.

hashtag
Step 3 – Update Container Images

Go to Portainer → Stacks and edit the helmut4 stack.

Locate the following services:

  • mongodb or mongodbrs

  • mongodb_backup

  • mongoadmin (to be replaced by mongo-express)

Update all image versions to the versions listed in the Docker Image Version History under the snapshot tag mongodb8.

For mongoadmin, follow the instructions on the Mongo Express documentation page.

circle-info

We also recommend reviewing the section “Limit Docker Container RAM Usage” to verify that the configured memory limits are still appropriate for your system, especially for the new mongodb/rs containers!

After updating the image tags, save the stack configuration and click "Update the stack".

If you are running a single-server installation, continue with Step 5. If you are running a cluster installation, proceed with Step 4.

hashtag
Step 4 – Rebuild the MongoDB Replica Set (Cluster only)

If you are running a cluster environment, the MongoDB replica set must be rebuilt after all mongodbrs containers have started successfully.

Detailed instructions can be found in the Helmut4 Cluster System documentation. However, one important change applies to this upgrade:

MongoDB now uses mongosh instead of the legacy mongo shell.

To connect to the mongodbrs container, run:

After connecting, rebuild the replica set as described in the cluster documentation.

Once the replica set is operating correctly, continue with Step 5.

hashtag
Step 5 – Restore the Backup

After the new MongoDB container(s) are running, the database backup must be restored.

Open a terminal session inside the mongodb_backup container. Instructions on how to open a console session can be found in the documentation section Restore mongodb_backup.

Inside the container, execute the following command and wait until the message “Backup restored” appears:

Do not interrupt this process. Depending on the database size, the restore may take several minutes.

Once the restore has completed, restart the Helmut4 stack. This restart is required so all services reload and correctly initialize using the restored database.

hashtag
Step 6 – Verify the System

Helmut4 is now running with the MongoDB v8 database.

Before ending the maintenance window, perform functional checks to confirm the system is operating correctly. We recommend verifying at least the following:

  • User login and panel access

  • Opening an existing project

  • Asset visibility in Cosmo

  • Workflow execution (e.g. a small test job or import)

  • New assets being created and indexed

If any issues occur, do not resume production work.

Please contact support while the maintenance window is still active so the system can be checked and, if necessary, reverted to its previous state.

Last updated