Offline MongoDB Version Upgrade
This document explains how to upgrade replica-set MongoDB clusters running in air-gapped environments with no internet access to the next major version without service outage. Installation uses local RPM packages downloaded beforehand and copied to each server, not remote repositories.
You cannot skip major MongoDB versions; upgrade each major release in order: 4.4 → 5.0 → 6.0 → 7.0 → 8.0. The same method applies at each step: update secondary nodes one by one, step the primary down and upgrade it, then raise featureCompatibilityVersion (FCV).
Before you start, take a current mongodump backup and keep a copy of /etc/mongod.conf on every node. Download packages on an internet-connected machine and copy them to each node for the target version.
In the examples, <NODE_IP> is the node IP address, <PRIMARY_NODE_IP> is the primary node IP, and <paket-dizini> is the directory containing RPM files for that version. Commands target RHEL / Rocky / AlmaLinux with dnf. The default Apinizer MongoDB port is 25080.
MongoDB 4.4 to 5.0 Upgrade
1. Updating Secondary Nodes from MongoDB 4.4 to 5.0
Apply on each secondary node in sequence.
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
Do not upgrade the next secondary until the current one returns to SECONDARY with health: 1.
2. Stepping Down the Primary Node
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
Step down the primary:
rs.stepDown()
Verify that a new primary was elected:
rs.status()
3. Upgrading the Former Primary from MongoDB 4.4 to 5.0
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
4. MongoDB 5.0 Feature Compatibility (FCV) Update
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
use admin
Check current feature compatibility:
db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
Update feature compatibility:
db.adminCommand({ setFeatureCompatibilityVersion: "5.0" })
MongoDB 5.0 to 6.0 Upgrade
5. Updating Secondary Nodes from MongoDB 5.0 to 6.0
Apply on each secondary node in sequence.
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
6. Stepping Down the Primary Node
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
Step down the primary:
rs.stepDown()
Verify that a new primary was elected:
rs.status()
7. Upgrading the Former Primary from MongoDB 5.0 to 6.0
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
8. MongoDB 6.0 Feature Compatibility (FCV) Update
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
use admin
Check current feature compatibility:
db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
Update feature compatibility:
db.adminCommand({ setFeatureCompatibilityVersion: "6.0" })
MongoDB 6.0 to 7.0 Upgrade
In MongoDB 7.0 the storage.journal configuration key was removed entirely; journaling is always on. If /etc/mongod.conf still contains a journal block from 6.0, the 7.0 service will not start and reports Unrecognized option: storage.journal.enabled (status=2/INVALIDARGUMENT). Remove the entire journal block from the config before starting the service during this upgrade. Apply the fix on every node that still has the block.
9. Updating Secondary Nodes from MongoDB 6.0 to 7.0
Apply on each secondary node in sequence.
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Remove the journal block from the configuration:
sudo cp -a /etc/mongod.conf /etc/mongod.conf.bak
sudo sed -i '/^\s*journal:/,/^\s*enabled:/d' /etc/mongod.conf
sudo grep -n journal /etc/mongod.conf # output should be empty
Removing only the enabled: true line is not enough; the journal: key itself is invalid. Keep YAML indentation for storage: and dbPath: while editing.
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
10. Stepping Down the Primary Node
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
Step down the primary:
rs.stepDown()
Verify that a new primary was elected:
rs.status()
11. Upgrading the Former Primary from MongoDB 6.0 to 7.0
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Remove the journal block from the configuration:
sudo cp -a /etc/mongod.conf /etc/mongod.conf.bak
sudo sed -i '/^\s*journal:/,/^\s*enabled:/d' /etc/mongod.conf
sudo grep -n journal /etc/mongod.conf # output should be empty
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
12. MongoDB 7.0 Feature Compatibility (FCV) Update
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
use admin
Check current feature compatibility:
db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
Update feature compatibility:
db.adminCommand({ setFeatureCompatibilityVersion: "7.0", confirm: true })
MongoDB 7.0 to 8.0 Upgrade
13. Updating Secondary Nodes from MongoDB 7.0 to 8.0
Apply on each secondary node in sequence.
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
14. Stepping Down the Primary Node
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
Step down the primary:
rs.stepDown()
Verify that a new primary was elected:
rs.status()
15. Upgrading the Former Primary from MongoDB 7.0 to 8.0
Stop the MongoDB service:
sudo systemctl stop mongod
Install packages (offline, from a local directory):
cd <paket-dizini>
sudo dnf install -y ./*.rpm
Start the MongoDB service:
sudo systemctl start mongod
sudo systemctl status mongod
Check replica set status:
mongosh mongodb://<NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
rs.status()
16. MongoDB 8.0 Feature Compatibility (FCV) Update
Connect to the primary node:
mongosh mongodb://<PRIMARY_NODE_IP>:25080 --authenticationDatabase "admin" -u "apinizer" -p
use admin
Check current feature compatibility:
db.runCommand({ getParameter: 1, featureCompatibilityVersion: 1 })
Update feature compatibility:
db.adminCommand({ setFeatureCompatibilityVersion: "8.0", confirm: true })