NDS Labs Project: QMCDB

Launching and Initializing the MongoDB Server

The MongoDB Server runs as a Docker container in a virtual machine on the NDS Labs (nebula) !OpenStack cluster. This document describes how to bring up the machine from scratch, initialize the MongoDB database, and launch it for use external by external clients.

This process engages scripts and python code from our QMCDB software package. The latest development versions of the server setup can be found in the "setup" branch of Ray's development fork.

Prepping and Launching the VM

This section discusses how to take a generic CoreOS machine image in !OpenStack and ready it for use as a host for the MongoDB Docker container. Much of this is done through the !OpenStack portal on nebula, and the steps for doing it are described only at a high level here; consult RaysNotesUsingLabs for details about what buttons to push.

1. Make sure you have created your SSH key pair.
   • download it to your $HOME/.ssh directory on the machine that you will log in from
2. Create necessary Security Groups that open the machine's firewall, where needed.
   • Make sure there is a group that allows SSH logins
   • Create a group that opens port 27017 (TCP, Ingress) for connecting to the MongoDB server
3. Reserve a floating IP address.
4. Create and launch a machine instance from the CoreOS image. We're currently using the "m1.small", but the "m1.tiny" might suffice in the future. Attach the above mentioned security groups to it.
5. Create a storage volume. This provides persistent storage that won't disappear if the machine instance disappears.
   • We're currently using a 4 GB volume--plenty for holding MongoDB data
   • If we plan to also store simnulation datasets here as well, a larger or additional volume may be needed.
6. Attach the volume to your machine instance.
   • Note the device name that it gets assigned (e.g. /dev/vdb)

7. Log into the machine as user, "core", via SSH using the IP address assign to it; use the SSH key created earlier.

   ssh -i ~/.ssh/labs_key core@141.142.XXX.XXX

   You can save yourself some typing by adding the following to your {{~/.ssh/config}} file.  

   ~/.ssh/config

   Host 141.142.XXX.XXX
     IdentityFile ~/.ssh/labs-default
     User core

   This allows you to log in with just the following:

   ssh 141.142.XXX.XXX

8. Partition and format the volume.

   • To partition, type sudo fdisk /dev/vdb and use the interactive menu to create a partition table.

   • create one partition spanning the whole disk
   • To format, type sudo mkfs -t ext4
   • CoreOS uses systemd (instead of fstab) to mount files. See these details on how to configure automounting. Mount the new drive (/dev/vdb1) as /data

9. Create MongoDB's the data directory

   sudo chown core:core /data
   mkdir qmcdb

Initialize and Launch MongoDB

Initializing MongoDB is handled by the QMCDB package, so that needs to be installed on the CoreOS host. Currently, installation is simple:

1. On the machine create the installation location:

    sudo mkdir -p /app/QMCDB && sudo chown -R core:core /app

2. Retrieve a copy of the QMCDB package from GitHub, and copy the contents of the directory in /app/QMCDB.
   The /app/QMCDB directory should then contain qmcdb, scripts, docker, etc.
   
   

3. Create the specialized MongoDB client container used to configure MongoDB; type:

   docker build -t qmcdb/mdbclient:latest

   
   You next need to configure the user accounts via a file called /app/QMCDB/conf/userinit.json:
   
   

4. Create the /app/QMCDB/conf/userinit.json file by copying /app/QMCD/conf/userinit.json_template.
   
   
5. In this file, substitute the occurrences of the word "password" with the desired passwords for each of the accounts to be created. Additional accounts can be added; see the explanation of the syntax below.

Now you are ready to configure the MongoDB server; type:

/app/QMCDB/scripts/labs-mongo-init.sh 

The output should look like this if everything went correctly:

Added admin: admin
Added developers: dev
Added managers: mgr
Initialized the qmcdb database.
Initialized the qmcdb_dev database.
Stopped server container.
Restarting MongoDB server...

If there are errors, try running it again.

The server should now be ready to except client connections.

Stopping and Starting MongoDB

The script /app/QMCDB/scripts/labs-mongo-ctl.sh (which must be run on the CoreOS machine hosting the Docker containers) can be used to start, stop, or get the status of the MongoDB server daemon:

 Usage: /app/QMCDB/scripts/labs-mongo-ctl.sh start|stop|status

That is, to stop the server, type:

/app/QMCDB/scripts/labs-mongo-ctl.sh stop

Use the start argument to restart it. (labs-mongo-init.sh should not be re-run.) This script tries to be smart about doing the right thing regardless of the state of the daemon.

QMCDB Configuration Details

This section explains how to change configuration details that set up the MongoDB server.

mongod.conf

This file is the standard MongoDB configuration file which is explained in the MongoDB documentation.

userinit.json

This file is used to create the initial set of user accounts. The QMCDB package contains a templated form of this file which looks like this:

{
    "admin": {
        "authdb": ["admin"],
        "roles": [ { "role": "root", "db": "admin" } ],
        "users": [ { "username": "admin", "pw": "password" } ] 
    },
    "managers": {
        "authdb": ["qmcdb_dev"],
        "roles": [ { "role": "dbOwner", "db": "qmcdb_dev" },
                   { "role": "dbOwner", "db": "qmcdb" } ],
        "users": [ { "username": "dev", "pw": "password" } ] 
    }
}

The outer-most set of keys ("admin" and "managers") name classes of users that will all be given the same roles or access rights. Each class has three data items with required names as follows:

authdb

The name of the database to add users to. (Note that MongoDB allows each database to have its own set of defined users.)

users

A list of username-passwords to be created. Each list item is a JSON object that must contain a "username" field and a "pw" field (containing the password).

roles

A list of access rights to be given to the user. Each item is a JSON object that must include a "role" giving the name of role (see the MongoDB Manual for pre-defined roles) and a "db" giving the name of the database that the role is granted for.

You must change the passwords from the template; the initialization script will not accept "password" as a password.

dbinit.json

This file, conf/dbinit.json, is used to preload data into databases. The default looks like this:

{
    "qmcdb": {
        "about": {
            "description":  "This database contains the production QMCDB data"
        }
    },

    "qmcdb_dev": {
        "about": {
            "description": "This database represents a development version of the QMCDB database"
        }
    }
}

The outer-most fields name databases that will receive the initial data. Each database object contains fields that name the collections within the data base to be initialized. The collection object is either a single document or a list of documents to be inserted into that collection.

labs-config.sh

This file, scripts/labs-config.sh, controls how MongoDB and other QMCDB components are deployed as Docker containers.