Prerequisites

  • Administrative rights on the host where the Cortex web app is installed
  • Administrative rights on the host where MongoDB is installed
  • The MongoDB installer


Overall upgrade steps

  1. Stop the Eos Cortex website.
  2. Backup the MongoDB database(s).
  3. Backup the MongoDB configuration settings.
  4. Stop the MongoDB service.
  5. Download and install the newer MongoDB application.
  6. Create a MongoDBA user.
  7. Create a MongoDB user.
  8. Download and install MongoDB tools.
  9. Restore the MongoDB database(s).
  10. Start the Eos Cortex website.
  11. Test and confirm.
  12. Cleanup any upgrade files and remove the old(er) MongoDB installation.


1. Stop the Eos Cortex website

  • On the web application server, open IIS Manager and stop the Eos Cortex web site.


2. Backup the MongoDB database(s)

  • On the server hosting the MongoDB database, backup the database via the 'mongodump' command.
  • Open a Command prompt as an Administrator.
  • Change directories to the MongoDB > Server > %versionNumber% > bin... folder
    ex: C:\Program Files\MongoDB\Server\4.2\bin\
  • Enter the following command. (modifying the highlighted values as required)
    mongodump.exe /host localhost:27017 --archive=%path_to_name.archive% /db %DBNAME% /u %Username% /p %UserPassword% --authenticationDatabase %AuthDBNAME% --gzip

    Parameters:
    - localhost:27017 = the local machine and the port MongoDB has been deployed to
    - %path_to_name.archive% = the path and name of the .archive file
    - %DBNAME% = the MongoDB name to backup
    - %Username% = the MongoDB username that will be used to authenticate
    - %UserPassword% = the MongoDB user password that will be used to authenticate
    - %AuthDBNAME% = the MongoDB authentication database name that will be used to authenticate

    ex: (the following is one long line of text)
    mongodump.exe /host localhost:27017 --archive=c:\Temp\EosCortexCLI01.20201117121314.archive /db EosCortexCLI01 /u EosCortexCLI01 /p S0m3Pa55w0rd! --authenticationDatabase EosCortexCLI01 --gzip

Note: If you have multiple MongoDB databases, backup each before proceeding to the next steps.


3. Backup the MongoDB configuration settings.

  • On the server hosting the MongoDB database, backup the configuration file.
    ex: mongodb.config, mongo.conf, or mongod.cfg
  • They are typically located in the same bin folder (as referenced above).
    ex: C:\Program Files\MongoDB\Server\4.2\bin\
  • Open the config file in a text editor and make note of the existing directories.
    ex: data or 'storage' (dbpath) and log or 'systemLog' (path) directories


4. Stop the MongoDB service.

  • On the server hosting the MongoDB database, stop the MongoDB service
    ex:
    ~ From an elevated Command Prompt:
    C:\>net stop MongoDB
    ~ From the Services.msc (management console):
    Stop the  MongoDB service


5. Download and install the newer MongoDB application.

Download

Install

  • Launch the MongoDB installation wizard.
  • At the Choose Setup Type dialog, select 'Complete'...
  • At the Service Configuration dialog...
    • select 'Install MongoDB as a Service'
    • Enter a Service Name
      ex: MongoDB
    • Enter the Data Directory
      ex: C:\Program Files\MongoDB\Server\4.4\data\
    • Enter the Log Directory
      ex: C:\Program Files\MongoDB\Server\4.4\log\


Note: Typically the MongoDB Data and Log Directories are on a drive other than the root system drive for Eos Cortex deployments.


  • At the Install MongoDB Compass dialog, check the Install MongoDB Compass check box.


6. Create a MongoDBA user.

Run mongod.exe with authorization disabled

Note: After installation from step 5 above, the service should already be running with authorization disabled, so you may skip this step, but this command line may prove convenient later for additional security operations deviating from this outline.

  • Open a Command prompt as an Administrator.
  • Change directories to the MongoDB > Server > %versionNumber% > bin... folder
    ex: C:\Program Files\MongoDB\Server\4.4\bin\
  • Enter the following command.
    mongod --noauth

Create a .js file to use in creating the MongoDBA user

  • In a text editor, add the content of the following: (modifying the highlighted items as required)

db.createUser( {
user: "MongoDBA",
pwd: "Pa55w0rd!",
roles: [ { role: "root", db: "admin" } ],
mechanisms: [ "SCRAM-SHA-256" ]
}
);

  • Save the text file as 'CphMongoSec.dba.js' in a temp folder or the root drive (i.e. C:\Temp).
    Note the.js extension.

Create the MongoDBA user

  • Open a second Command prompt as an Administrator
  • Change directories to the MongoDB > Server > %versionNumber% > bin... folder
    ex: C:\Program Files\MongoDB\Server\4.4\bin\
  • Enter the following command.
    mongo localhost:27017/admin c:\Temp\CphMongoSec.dba.js


Stop the mongod.exe service

  • In the first 'Command Prompt' window opened in step 6 above, stop mongod.exe by enters CTRL+C


Enable Authorization in the new service

Note: You should NOT use the same path/location for the data and log files as was used for the previous version of MongoDB. If you intend to use the same location, rename the old folder and files, and then you can continue to use the original paths.

  • With a text editor, open the mongo.cfg (MongoDB Configuration) file. This file is located in the previously identified 'bin' folder.
    ex: C:\Program Files\MongoDB\Server\4.4\bin\ 
  • Edit the config file as follows (see highlighted items below).

# mongod.conf

# for documentation of all options, see:

# http://docs.mongodb.org/manual/reference/configuration-options/

# Where and how to store data.
storage:
  dbPath: f:\MongoData\db
  journal:
    enabled: true
#  engine:
#  mmapv1:
#  wiredTiger:

# where to write logging data.
systemLog:
  destination: file
  logAppend: true
  path:  f:\MongoData\log\mongod.log
  verbosity: 0

# network interfacesnet:
  port: 27017
  bindIp: 127.0.0.1

security:
  authorization: enabled

setParameter:   
  authenticationMechanisms: "SCRAM-SHA-256"


Start the MongoDB service

  • In the second 'Command Prompt' window opened in step 6 above, start the new service.
    ex: C:\>net start MongoDB
    From the Services.msc (management console):
    Start the MongoDB service


7. Create a MongoDB user.

Create a .js file to use in creating the Mongo user

  • In a text editor, add the content of the following: (modifying the highlighted items as required)

// config begininstance = 'EosCortexCLI01';
userName = instance;
password = 'Pa55w0rd!';
// config end


// the action begindb = db.getSiblingDB(instance);
db.dropUser(userName);
db.dummyCollection.insert({dummydoc:"prime the pump"});
db.createUser(
  {
    user: userName,
    pwd: password,
    roles: [{role: 'readWrite', db: instance}, {role: 'dbAdmin', db: instance}, {role: 'backup', db: 'admin'}, {role: 'restore', db: 'admin'} ],
    mechanisms: [ "SCRAM-SHA-256" ]
  }
)
db.dummyCollection.remove({dummydoc:"prime the pump"});
db.dummyCollection.drop();


  • Save the text file as 'CphMongoSec.CLI.js' in a temp folder or the root drive (i.e. C:\Temp).
    Note the.js extension.

  • Create the Mongo user

    • In the second Command prompt window opened in step 6 above, change directories to the MongoDB > Server > %versionNumber% > bin... folder
      ex: C:\Program Files\MongoDB\Server\4.4\bin\
    • Enter the following command. (modifying the highlighted values as required)
      mongo localhost:27017/admin c:\Temp\CphMongoSec.CLI.js -u MongoDBA -p Pa55w0rd!


8. Download and install MongoDB tools.

Note: Starting in MongoDB 4.4, the tools required to backup and restore are no longer included in the MongoDB installer.

Download

Install (copy the eight .exe files)

  • From the unzip location, copy the eight (8) .exe files to the MongoDB > Server > %versionNumber% > bin... folder.
    ex: C:\Program Files\MongoDB\Server\4.4\bin\


9. Restore the MongoDB database(s).

  • In the second Command prompt window opened in step 6 above, change directories to the MongoDB > Server > %versionNumber% > bin... folder
    ex: C:\Program Files\MongoDB\Server\4.4\bin\
  • Enter the following command. (modifying the highlighted values as required)
    mongorestore.exe /host localhost:27017 --archive=%path_to_name.archive% --gzip /u %Username% /p %UserPassword%

    Parameters:
    - localhost:27017 = the local machine and the port MongoDB has been deployed to
    - %path_to_name.archive% = the path and name of the .archive file
    - %Username% = the MongoDBA username that will be used to authenticate
    - %UserPassword% = the MongoDBA user password that will be used to authenticate

    ex: (the following is one long line of text)
    mongorestore.exe /host localhost:27017 --archive=c:\Temp\EosCortexCLI01.20201117121314.archive --gzip /u MongoDBA /p Pa55w0rd! 

Note: If you have multiple MongoDB databases, backup each before proceeding to the next steps.


10. Start the Eos Cortex website.

  • On the web application server, open IIS Manager and start the Eos Cortex web site.


11. Test and confirm.

  • With a browser, navigate to the Eos Cortex website and confirm you can:
    • Successfully authenticate
    • Retrieve element and item data


12. Cleanup any upgrade files and remove the old(er) MongoDB installation.

  • Delete the old installation files.
    ex: C:\Program Files\MongoDB\Server\4.2\bin\
  • Delete the old data and log directories
  • Delete the old service if necessary
    ex: From a Command Prompt opened as an Administrator, enter: (Where "MongoDB Server" is the old service name.)
    C:\>sc delete "MongoDB Server"


The End.