Using the MongoDB MSI Installer with Windows Azure Virtual Machines

Recently I explored the topic of running the MongoDB NoSQL database using Windows Azure Worker roles -- in other words, taking a Platform as a Service (PaaS) approach to hosting. A few things have changed since then that present a new option for running MongoDB on Azure. First, Microsoft has released in preview form its Infrastructure as a Service (IaaS) offering, Azure Virtual Machines. Second, 10gen (the company behind MongoDB) has released a Windows (MSI) installer that automates the process of provisioning Azure Virtual Machines and configuring on them a replica set (similar to a cluster of nodes in traditional SQL Server databases) of MongoDB instances.

If you've been sitting on the sidelines waiting to play with your own MongoDB deployment on Azure, now is a great time to get in the game. In this article, I'll show you how to get started by using the MongoDB Installer for Windows Azure.

Get the Installer

To download the installer, point your browser to http://downloads.mongodb.org/azure/MongoDBInstVM.msi and save the file to your local drive. To use the installer, you run it on your local machine; the installer runs a set of Windows PowerShell and command scripts that perform the deployment to Azure and drive the subsequent configuration of the virtual machines (VMs). To run the installer, all you'll need is a 32-bit or 64-bit version of Windows 7 and an Administrator account on the machine where you'll run the installer.

With the installer downloaded, double-click the .msi file to run it and zoom through the wizard-driven installation, shown in Figure 1.


Figure 1: The MongoDB for Windows Azure Setup Wizard

The installation is simple; you just accept the terms and click Install. The end result of the installation will be a set of shortcuts on your Start menu, under All Programs, MongoDB Installer for Windows Azure, and a set of scripts installed under C:Program FilesMongoDBWindows AzureMongoDBInstVMAugust2012PowerShell.

Get Your Credentials

After you complete the installation, the first thing you need to do is get the credentials that the scripts will use in deploying to your Azure subscription. To do this, go to All Programs, MongoDB Installer for Windows Azure and click the Download PublishSettings shortcut. This shortcut will take you to a special area of the Windows Azure Portal that, after you've logged in, will provide you a file with a .publishsettings suffix to download. I recommend you save this file in the same folder in which the installer placed the scripts and name the file something simple like AzurePubSettings.publishsettings so that you can refer to it easily from a command-line parameter.

This file, shown in Listing 1, contains the names and certificates for all Azure subscriptions your account is configured to access. Obviously, you should treat this file with care because it literally holds the keys to your Azure kingdom.

          If you have multiple subscriptions, you'll want to pick the one you want the scripts to use by default. Otherwise, odds are good that you'll end up deploying to a subscription other than the one you intended and not notice until it's too late. An easy way to ensure that you use the correct subscription is to open the .publishsettings file in Notepad and delete the  elements pertaining to all but the subscription you want to use.Configure PrerequisitesThe great thing about the installer's script is that it will take care of downloading and installing any of the prerequisites it needs. All you need to worry about is that the script is executed in the appropriate environment. This means that the account you're running PowerShell under has administrative permissions; that your network -- selected from the Network and Sharing Center Control Panel applet -- is set to either Home or Work (i.e., not Public); and that your PowerShell environment is configured to allow execution of unsigned scripts.To configure PowerShell to allow execution of unsigned scripts, run the PowerShell console provided by the installer from the Start menu (All Programs, MongoDB Installer for Windows Azure). At the PowerShell command line, type the following command:set-executionpolicy remotesignedWhen promted by PowerShell, if you want to change the execution policy, type Y and press Enter. Now you're all set to run the deployment script.Run the Deployment ScriptWhen you run the PowerShell console, it will open already navigated to the directory where the installer placed all the script files and, hopefully, where you saved your publishsettings file. Listing 2 shows the command line for running the deployment PowerShell script..deploy-mongo.ps1         Let's look at the parameters in the command line. First, the numberOfInstances parameter defines how many Azure Virtual Machines are spun up to support the replica set, with a minimum value of 1 (which defines a standalone server that's not part of a replica set). You should typically set this parameter to 3. The hostedServiceName parameter is the name of the deployed hosted service and provides the DNS prefix to *.cloudapp.net that you'll use to connect to your replica set after it's deployed. The vhdFileName parameter parameter is the name of the image file as it will be created in blob storage.The rdpAdminPassword parameter is the password to the Administrator account that will be created on each VM and used to connect by RDP. Note that Windows password complexity is enforced, so make this password at least eight characters long and a mix of uppercase and lowercase letters, symbols, and numbers to avoid password-related delays at deployment time. The azureLocation parameter defines the geographic location of the Azure data center you want to deploy to (e.g., West US, East US). The pathToPubSettings parameter provides the path to the credentials file you downloaded. Finally, the nameOfReplicaSetToCreate parameter provides the name to use when initializing the replica set. Taking all these parameters together, a sample command line might look like this:.deploy-mongo.ps1 3 tn-mongoiaas2 tnmongoiaas2vhd  Abc!12345 "West US" .AzurePubSettings.publishsettings rsOnce you've built your command line, run it. Stick around for a few minutes while the command starts because it will prompt you to install Node.js and the Windows Azure SDK for Node.js if they aren't already installed on your machine (all you need to do is type Y, then click through the installation wizards as they appear). After those prerequisites are downloaded and installed, you'll be prompted one last time asking whether you want to create the VHD file in blob storage, to which you must also answer Y. After that, installation will proceed in cruise-control mode -- give it about 30 to 40 minutes, and you should have your replica set up and running in Azure!Connect to Your DeploymentWhen the script finishes, you should see the following lines at the end of its output:info: Done with setupinfo: Connection details of mongo instances, RDP and  remoting are stored in connectionString-tn-mongoiaas2.jsonThe .json file referenced will be named according to what you entered for the hostedServiceName parameter. This file is written in the same directory as the scripts. If you open this file, shown in Listing 3, you'll see a JavaScript Object Notation (JSON) document containing all you need to know to connect to your deployment (except the admin password that you typed at the command line).
 [{  "Credentials": [{    "info": {      "user": "Administrator",      "password": "******"    }  }]}, {  "RDP": [{    "info": {      "connectionUrl": ["tn-mongoiaas2.cloudapp.net:3391",        "tn-mongoiaas2.cloudapp.net:3390",        "tn-mongoiaas2.cloudapp.net:3389"]    }  }]}, {  "Mongo": [{    "info": {      "connectionUrl": ["tn-mongoiaas2.cloudapp.net:27019",        "tn-mongoiaas2.cloudapp.net:27018",        "tn-mongoiaas2.cloudapp.net:27017"],      "ReplicaSetUrl": "mongodb://tn-mongoiaas2.cloudapp.net:        27019, tn-mongoiaas2.cloudapp.net:27018,        tn-mongoiaas2.cloudapp.net:27017?replicaSet=rs",      "ReplicaSetName": "rs"    }  }]}, {  "Remoting": [{    "info": {      "connectionUrl": ["tn-mongoiaas2.cloudapp.net:5987",        "tn-mongoiaas2.cloudapp.net:5986",        "tn-mongoiaas2.cloudapp.net:5985"]    }  }]}]To connect to your replica set, simply fire up MongoDB, pointing it to the address of one of the members listed in the Mongo.info.connectionUrl property in the connection document. For example, the command line for the sample document shown might look like this:mongo tn-mongoiaas2.cloudapp.net:27017Get Going with MongoDB on AzureWith that, you are ready to start playing around with your own IaaS deployment of MongoDB on Windows Azure. For more information about the MongoDB Installer for Azure, check out the official "MongoDB on Azure Worker Roles" documentation . Have fun!