Manual Database Installation

This guide will cover the basic steps required for you to manually download and install the MongoDB Database. Note that it is possible for the Deadline Repository Installer to automatically download and install the database, but an internet connection is required. In addition, only specific operating systems are supported. If an internet connection isn’t available, or the current operating system you are using isn’t supported, you can follow this guide to install the Database manually.

Manually installing the MongoDB database might also be preferable for some because it gives you greater control over things like authentication, and allows you to create sharded clusters or replica sets for backup. More information on these advanced topics can be found at the bottom of this guide.

If you’re installing the MongoDB database on a machine running Linux or Mac OS X, you also have the option to download and install MongoDB through their associated package manager such as yum, apt, or homebrew. Just make sure the MongoDB version is minimum 3.2.12 and maximum 3.2.18. For the purposes of this guide though, we will assume you’ve downloaded MongoDB manually.

Download and Install MongoDB

You can download the version of MongoDB that corresponds to your operating system from the MongoDB Downloads Page. Note that the MongoDB version must be minimum 3.2.12 and maximum 3.2.18, and we strongly recommend downloading a version with SSL support.

Once the download is finished, you’ll want to extract the compressed file (.tgz or .zip), rename the resulting folder to something readable (this guide will assume you chose application), and delete the compressed file. For example, mongodb-linux-x86_64-debian81.tgz decompresses to mongodb-linux-x86_64-debian81, and then can be renamed to application.

Next you’ll need to create a location to store the installation of the database. For the purpose of these instructions, we’re assuming these are the paths you’ll create:

  • Windows

    C:\DeadlineDatabase[VERSION]\mongo
    
  • Mac OS X

    /Applications/Thinkbox/DeadlineDatabase[VERSION]/mongo
    
  • Linux

    /opt/Thinkbox/DeadlineDatabase[VERSION]/mongo
    

Where [VERSION] is replaced with the major version of Deadline, such as: 10. Follow this up by moving your application folder into this directory. Finally, create a data folder alongside the application folder.

Database Configuration

Before you run MongoDB, some configuration is required. First, a configuration file needs to be created, and then MongoDB should be configured to run as a service or daemon.

Configuration File (All Platforms)

A database configuration file has to be created in the data folder that you created above. For the purposes of this guide, this configuration file will be called config.conf. After creating the file, copy and paste the contents below into it. Before saving the file, be sure to make the following changes:

  • [PathToMongoDB] should be replaced with the path to the folder that contains the application and data folders you created earlier. If you’ve been following the instructions, that value will be C:\DeadlineDatabase[VERSION]\mongo, where [VERSION] is the major version of Deadline, such as: 10.
#MongoDB config file

systemLog:
  destination: file
  # Mongo DB's output will be logged here.
  path: [PathToMongoDB]/data/logs/log.txt
  # Default to quiet mode to limit log output size. Set to 'false' when debugging.
  quiet: true
  # Increase verbosity level for more debug messages (0-5)
  verbosity: <integer>

net:
  # Port MongoDB will listen on for incoming connections
  port: [DB_PORT]
  ipv6: true
  ssl:
    # SSL/TLS options
    mode: disabled
    # If enabling TLS, the below options need to be set:
    #PEMKeyFile:
    #CAFile:
  http:
    # Set to 'true' to enable REST interface
    RESTInterfaceEnabled: false

storage:
  # Database files will be stored here
  dbPath: [PathToMongoDB]/data
  engine: mmapv1

# Enable sharding
#sharding:
  #clusterRole:
  #configDB:

# Setup replica set with given replica set name
#replication:
  #replSetName:

security:
  authorization: disabled

These are the key settings defined in this file.

  • systemLog: path: This is where MongoDB will write its log to.
  • net: port: This is the port [DB_PORT] that MongoDB will listen on, such as: 27100
  • net: ssl: mode: This setting can be used to enable TLS/SSL authentication. The sample configuration above has this option disabled, but we recommend Configuring MongoDB for TLS/SSL Authentication.
  • storage: dbPath: This is where MongoDB will save its data.

See the MongoDB Configuration File Options for more information on the available options. Note that if you change this file later, and MongoDB is already running, then you’ll need to restart the database service for the changes to go into effect.

Create Windows Service (Windows)

To have MongoDB run as a service on Windows, you’ll have to manually create the service. This can be done by launching a command prompt as an Administrator and running the following command. Before running the command, please make the following changes:

  • [VERSION] should be replaced with Deadline’s major version, such as: 10
  • [PathToMongoInstall] should be replaced with the location of Deadline’s MongoDB folder. If you’ve been following the instructions, that value will be C:\DeadlineDatabase[VERSION]\mongo.
sc create Deadline[VERSION]DatabaseService binPath= "\"[PathToMongoInstall]\application\bin\mongod.exe\" --config \"[PathToMongoInstall]\data\config.conf\" --service" start= auto depend= TCPIP DisplayName= "Deadline [VERSION] Database Service"

Database Property List File (Mac OS X)

For Mac OS X, a plist file needs to be created to allow MongoDB to run as a daemon. For the purposes of this guide, this plist file will be called org.mongodb.mongod_Deadline[VERSION]DatabaseService.plist, where [VERSION] is the major version of Deadline. Create this file in a temporary location, and then copy and paste the contents below into it. Before saving the file, be sure to make the following changes:

  • [VERSION] should be replaced with Deadline’s major version, such as: 10
  • [ReplaceWithServiceName] should be replaced with the name of the service. For example, Deadline[VERSION]DatabaseService.
  • [ReplaceWithMongoInstallPath] should be replaced with the path to Deadline’s MongoDB database. For example, /Applications/Thinkbox/DeadlineDatabase[VERSION].
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>org.mongodb.mongod_[ReplaceWithServiceName]</string>
  <key>ProgramArguments</key>
  <array>
        <string>[ReplaceWithMongoInstallPath]/mongo/application/bin/mongod</string>
        <string>run</string>
        <string>--config</string>
        <string>[ReplaceWithMongoInstallPath]/mongo/data/config.conf</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>WorkingDirectory</key>
  <string>[ReplaceWithMongoInstallPath]/mongo/application/bin</string>
  <key>StandardErrorPath</key>
  <string>/var/log/mongo/output.txt</string>
  <key>StandardOutPath</key>
  <string>/var/log/mongo/output.txt</string>
  <key>HardResourceLimits</key>
  <dict>
        <key>NumberOfFiles</key>
        <integer>10000</integer>
  </dict>
  <key>SoftResourceLimits</key>
  <dict>
        <key>NumberOfFiles</key>
        <integer>10000</integer>
  </dict>
</dict>
</plist>

After saving the file, copy it to /Library/LaunchDaemons/.

Finally, the permissions will have to be set on the file to allow reading and writing, which can be done with the following command from a terminal. Before running the command, please make the following changes:

  • [VERSION] should be replaced with Deadline’s major version, such as: 10.
sudo chmod 644 /Library/LaunchDaemons/org.mongodb.mongod_Deadline[VERSION]DatabaseService.plist

Database Script File (Linux)

For Linux, an executable script file needs to be created to allow MongoDB to run as a service. For the purposes of this guide, this file will be called Deadline[VERSION]db, where [VERSION] is the major version of Deadline. Create this file in a temporary location, and then copy and paste the contents below into it. Before saving the file, be sure to make the following changes:

  • [VERSION] should be replaced with Deadline’s major version.
  • [PathToMongoDBBin] should be replaced with the path to MongoDB’s bin folder. Installer’s default path is /opt/Thinkbox/DeadlineDatabase[VERSION]/mongo/application/bin.
  • [PathToMongoDBData] should be replaced with the path to MongoDB’s data folder. Installer’s default path is /opt/Thinkbox/DeadlineDatabase[VERSION]/mongo/data.
#!/bin/bash
#
# mongodb Startup script for Mongo DB
#
# chkconfig: - 20 80
# description: MongoDB (from "humongous") is a scalable, high-performance, open$

### BEGIN INIT INFO
# Provides: Deadline[VERSION]db
# Default-Start: 2 3 5
# Default-Stop:  0 1 4 6
# Required-Start: $network $local_fs $remote_fs
# Required-Stop: $network $local_fs $remote_fs
# Short-Description: Mongo DB NoSQL Database.
# Description: MongoDB (from "humongous") is a scalable, high-performance, open$
### END INIT INFO

# Source function library. (Supported only on Red Hat distributions.
( . /etc/rc.d/init.d/functions > /dev/null 2>&1 )

DEADLINEVERSION=[VERSION]
MONGODBBIN=[PathToMongoDBBin]
MONGODBDATA=[PathToMongoDBData]
MONGOSERVICEFILENAME="mongodb"
MONGOLOCK="/var/lock/subsys/deadline$DEADLINEVERSION$MONGOSERVICEFILENAME"
LOGFILE="/var/log/deadline$DEADLINEVERSION$MONGOSERVICEFILENAME.log"
PIDFILE="/var/run/deadline$DEADLINEVERSION$MONGOSERVICEFILENAME.pid"
RUNNING=0 # Is the process in our PID file running?
PID=-1    # What is the process ID?
ULIMITSETTING=64000 # Open file descriptor limit (64000 is recommended amount)

LONGNAME="MongoDB Service For Deadline ${DEADLINEVERSION}"

service_is_running() {
        # Note that this only checks to see if there's a process running
        # that was started from this init script.
        if [ -e "${PIDFILE}" ]; then
                PID=`cat ${PIDFILE}`
                ps -p $PID >/dev/null 2>&1
                if [ $? -eq 0 ]; then
                        return 0
                else
                        rm -f "${PIDFILE}" >/dev/null 2>&1
                        rm -f "${MONGOLOCK}" >/dev/null 2>&1
                fi
        fi

        PID=-1
        return 1
}

log_event() {
        if [ $# -gt 0 ]; then
                date "+%F %T: $1" >> "${LOGFILE}"

                if [ $# -gt 1 ] && [ $2 = true ]; then
                        echo $1
                fi
        fi
}

start () {
        if service_is_running; then
                log_event "The ${LONGNAME} is already running (PID ${PID})." true

                return 0
        else
                # Start the service
                if [ -e "${MONGODBBIN}/mongod" ]; then
                        if [ -x "${MONGODBBIN}/mongod" ]; then
                                # Increase file descriptors limit
                                if [ "$(ulimit -n)" -lt "$ULIMITSETTING" ]; then
                                        ulimit -n "$ULIMITSETTING"
                                fi

                                # Start the service
                                ("$MONGODBBIN/mongod" --config "$MONGODBDATA/config.conf") &

                                # Log the PID and create the LOCK file
                                echo $! > "${PIDFILE}"
                                touch "${MONGOLOCK}" 2> /dev/null

                                if service_is_running; then
                                        log_event "The ${LONGNAME} has been started." true
                                        log_event "Full log can be found in ${MONGODBDATA}/logs/log.txt"

                                        return 0
                                else
                                        log_event "The ${LONGNAME} failed to start." true
                                        return 7
                                fi
                        else
                                log_event "'${MONGODBBIN}/mongod' is lacking execute permissions for the current user." true
                                return 4
                        fi
                else
                        log_event "'mongod' was not found at the expected location (${MONGODBBIN})" true
                        return 5
                fi
        fi
}

stop () {
        if ! service_is_running; then
                log_event "The ${LONGNAME} is not currently running." true
                return 0
        else
                log_event "Shutting down the ${LONGNAME}..." true
                kill -QUIT $PID

                COUNTER=0
                while kill -0 $PID >/dev/null 2>&1; do
                        COUNTER=$((COUNTER+1))

                        if [ "$COUNTER" -gt 10 ]; then
                                break
                        fi

                        sleep 0.5
                done

                if service_is_running; then
                        # Time to bring out the big guns
                        kill -KILL $PID

                        sleep 0.5

                        if service_is_running; then
                                log_event "Failed to stop the ${LONGNAME}." true
                                return 1
                        fi
                fi
        fi

        log_event "The ${LONGNAME} has been stopped gracefully." true

        return 0
}

restart() {
        stop
        start

        return $?
}

rh_status(){
        if [ -e "${PIDFILE}" ]; then
                PID=`cat ${PIDFILE}`

                if ps -p $PID >/dev/null 2>&1; then
                        log_event "The ${LONGNAME} is running with PID $PID." true
                        return 0
                else
                        log_event "The ${LONGNAME} exited prematurely." true
                        return 1
                fi
        elif [ -e "${MONGOLOCK}" ]; then
                log_event "The ${LONGNAME} exited prematurely." true
                return 2
        else
                log_event "The ${LONGNAME} is not currently running." true
                return 3
        fi
}

rh_status_q(){
        rh_status >/dev/null 2>&1

        return $?
}
log_event "'$1' invoked..."

EXIT_CODE=1
# See how we were called.
case "$1" in
        start)
                start

                EXIT_CODE=$?
                ;;
        stop)
                stop

                EXIT_CODE=$?
                ;;
        restart|force-reload)
                restart

                EXIT_CODE=$?
                ;;
        status)
                rh_status

                EXIT_CODE=$?
                ;;
        condrestart|try-restart)
                if ! rh_status_q; then
                        log_event "The ${LONGNAME} is not currently running; restart will not be performed." true

                        EXIT_CODE=0
                else
                        restart

                        EXIT_CODE=$?
                fi
                ;;
        *)
                log_event "Usage: $0 {start|stop|status|restart|condrestart|try-restart|force-reload}" true
                EXIT_CODE=3
esac

log_event "'$1' operation finished with exit code '$EXIT_CODE'."
exit $EXIT_CODE

After saving the file, copy it to /etc/init.d/.

Finally, the permissions will have to be set on the file to allow reading, writing, and execution, which can be done with the following command from a terminal. Before running the command, please make the following changes:

  • [VERSION] should be replaced with Deadline’s major version, such as: 10
sudo chmod 755 /etc/init.d/Deadline[VERSION]db

Start Database Service

Now that MongoDB is installed and configured, it’s time is to start your MongoDB service or daemon. This can be done by executing the following command from a command prompt or terminal. Just replace [VERSION] with Deadline’s major version:

  • Windows (as Administrator):

    sc start Deadline[VERSION]DatabaseService
    
  • Mac OS X:

    launchctl load /Library/LaunchDaemons/org.mongodb_Deadline[VERSION]DatabaseService.plist
    
  • Linux:

    sudo service deadline[VERSION]db start
    

Confirm that MongoDB is Running

For the final step, you’ll want to confirm that the MongoDB service or daemon is running. The command for each output can be found below, followed by an example of what the output looks like. Just replace [VERSION] with Deadline’s major version, such as: 10:

  • Windows:

    sc query Deadline[VERSION]DatabaseService
    
        SERVICE_NAME: Deadline[VERSION]DatabaseService
        TYPE        : 10  WIN32_OWN_PROCESS
        STATE       : 4   RUNNING
        ...
    
  • Mac OS X:

    ps aux | grep mongo
    
        root ... /Applications/Thinkbox/DeadlineDatabase[VERSION]/mongo/application/bin/mongod --config /Applications/Thinkbox/DeadlineDatabase[VERSION]/mongo/data/config.conf
    
  • Linux:

    ps aux | grep mongo
    
        root ... /opt/Thinkbox/DeadlineDatabase[VERSION]/mongo/application/bin/mongod --config /opt/Thinkbox/DeadlineDatabase[VERSION]/mongo/data/config.conf
    

Additional Information

If you’re looking for more information, here are some helpful links for manually installing the MongoDB database:

MongoDB also has a management system called Cloud Manager. It’s a cloud service that makes it easy to provision, monitor, backup, and scale your MongoDB database. Here are some helpful links for setting up and using Cloud Manager:

The Automation Agent mentioned above makes it possible to setup your MongoDB database from a web interface, and easily configure which MongoDB servers are replica sets or shards. It also allows you to easily upgrade the version of your MongoDB database. Here are some additional links for how you can use the Automation Agent:

Mongo and MongoDB are registered trademarks of MongoDB, Inc.