Know the limits first

• cPanel does not manage MongoDB. cPanel supports MySQL and MariaDB only. There is no MongoDB interface in cPanel, and cPanel support gives very limited help with it.
• JetBackup already runs MongoDB. On servers with JetBackup, a service called jetmongod is part of JetBackup. Do not stop, change or reuse it. Your own MongoDB install runs separately.
• Updates are your job. MongoDB updates come from the MongoDB repository, not from cPanel updates.
• Consider a separate server. For production databases, a dedicated VPS for MongoDB keeps it apart from the web server and makes resources easier to plan.

Before you start

• ✓ Root SSH access to a cPanel server on AlmaLinux, Rocky Linux or CloudLinux 8 or 9.
• ✓ A recent backup of the server.
• ✓ The current supported MongoDB version, from the MongoDB installation documentation.
• ✓ Port 27017 closed in the firewall. MongoDB should only be reached from the server itself unless you plan otherwise.

Step 1: add the MongoDB repository

Create the repository file. This example uses MongoDB 8.0. Replace 8.0 in both lines if a newer release is current.

cat > /etc/yum.repos.d/mongodb-org-8.0.repo <<'EOF'
[mongodb-org-8.0]
name=MongoDB Repository
baseurl=https://repo.mongodb.org/yum/redhat/$releasever/mongodb-org/8.0/x86_64/
gpgcheck=1
enabled=1
gpgkey=https://pgp.mongodb.com/server-8.0.asc
EOF

Step 2: install and start MongoDB

dnf install -y mongodb-org
systemctl enable --now mongod
systemctl status mongod --no-pager

The mongodb-org package installs the server (mongod), the router (mongos), the shell (mongosh) and the database tools.

Step 3: keep MongoDB private

Open /etc/mongod.conf and check the network section. By default MongoDB listens on localhost only, which is what you want when the database runs on the same server as the website.

net:
  port: 27017
  bindIp: 127.0.0.1

Make sure port 27017 is not open in the firewall. With CSF, check that 27017 is not listed in TCP_IN in /etc/csf/csf.conf.

Step 4: turn on authentication

Create an admin user first, then enable authorisation. Use your own user name and a strong password.

mongosh
use admin
db.createUser({ user: "dbadmin", pwd: passwordPrompt(), roles: [ { role: "userAdminAnyDatabase", db: "admin" }, "readWriteAnyDatabase" ] })
exit

Then add this to /etc/mongod.conf and restart MongoDB:

security:
  authorization: enabled

systemctl restart mongod

Create a separate user for each application, with access only to its own database.

Step 5: add the PHP mongodb extension

PHP applications connect to MongoDB through the mongodb PECL extension. On cPanel, install it through WHM so it is tracked for each PHP version:

1. In WHM, open Software > Module Installers.
2. Next to PHP PECL, click Manage.
3. Select the PHP version your site uses.
4. Search for mongodb, then install it.
5. Repeat for each PHP version that needs it.

Most PHP projects also use the MongoDB PHP library, installed in the application with Composer: composer require mongodb/mongodb.

Step 6: check that everything works

# MongoDB answers on localhost
mongosh --quiet --eval 'db.runCommand({ ping: 1 })'

# The PHP extension is loaded (PHP 8.3 example)
/opt/cpanel/ea-php83/root/usr/bin/php -m | grep -i mongodb

Connect from PHP

With the extension and the Composer library installed, a minimal connection looks like this. Keep the password in an environment variable or a config file outside the web root, not in the code.

<?php
require 'vendor/autoload.php';

$client = new MongoDB\Client('mongodb://appuser:' . getenv('MONGO_PASS') . '@127.0.0.1:27017/appdb?authSource=appdb');
$collection = $client->appdb->orders;
$result = $collection->insertOne(['item' => 'test', 'created' => new MongoDB\BSON\UTCDateTime()]);
echo 'Inserted ' . $result->getInsertedId();

If another server must connect

Sometimes an application on a second server needs the database. Open access only as far as you need:

1. Add the server’s private or public IP address to bindIp, keeping 127.0.0.1 as well.
2. Allow port 27017 in the firewall for that one IP address only. With CSF, use csf -a with a port rule rather than opening the port to everyone.
3. Keep authentication on, and give the remote application its own user.
4. Turn on TLS for the connection if the traffic crosses the public internet.

Upgrade MongoDB safely

MongoDB major versions must be upgraded one step at a time, for example 7.0 to 8.0, not across several versions at once. Before each upgrade, back up with mongodump, read the release notes, and check the feature compatibility version:

mongosh --quiet --eval 'db.adminCommand({ getParameter: 1, featureCompatibilityVersion: 1 })'

Change the version number in the repository file, run dnf upgrade mongodb-org, restart mongod, and check your application before you raise the feature compatibility version.

Back up MongoDB

cPanel account backups do not include MongoDB data. Back it up separately with mongodump, and copy the backups off the server.

mongodump --uri="mongodb://dbadmin@127.0.0.1:27017/?authSource=admin" --out=/backup/mongodb-$(date +%F)

Test a restore with mongorestore on a test server before you rely on the backups. Our off-site backup guide covers where to keep copies.

Keep an eye on MongoDB

A few quick checks tell you whether the database is healthy:

# Open connections and uptime
mongosh --quiet --eval 'const s = db.serverStatus(); printjson({ uptime: s.uptime, connections: s.connections })'

# Disk space used by the data folder
du -sh /var/lib/mongo

Watch the disk space in particular. MongoDB stops writing when the disk fills up, and the log file in /var/log/mongodb/ grows over time, so rotate it.

Troubleshooting

For other software on cPanel, see our guides to installing PHP extensions with EasyApache 4 and installing FFmpeg.