Tutorial – Building a Multi-Tier Windows Azure Web application use Cloudant’s Couchdb-as-a-Service, node.js, CORS, and Grunt

About this tutorial

In this tutorial, we will show you how to build and deploy a multi-tier web application on Windows Azure, highlighting how easy it is to use Cloudant’s CouchDB Azure service in an Azure-based web application.

Prerequisites

This tutorial requires a Windows Azure subscription. If you don’t have a subscription, you can sign up for a free trial subscription on WindowsAzure.com. You will also need a free Cloudant account/subscription, but we’ll cover the steps for setting that up later in the tutorial.

About the sample application

This tutorial uses a sample application written by Parashuram Narasimhan. The application is used to share conference schedules, sessions, and speakers for a demo conference. It allows users to rate sessions, mark favorites and write notes for various sessions. Further, it works in an offline mode and syncs session and user data when back online.

Application Architecture

The application uses a variety of web technologies including IndexedDB, AppCache, and Apache CouchDB (via the Cloudant CouchDB-as-a-Service offering) for remote syncing. The multi-tier cloud application has three main components:

1. A CouchDB database running on Cloudant’s Azure service.

2. A Node.js application to forward CouchDB database requests

3. An HTML and Javascript application hosted on a web server

Here’s an overview of the application Architecture:

Application Deployment

The application uses Grunt, a Javascript Task Runner, for managing deployment and starting a CORS server. Grunt deploys various .htm, .css files as well as .js files. It also concatenates multiple .js files into one .js file. These files are placed on a windows Azure Web Sites instance used to access the application. Grunt also starts a CORS proxy which is used to forward database requests to the Cloudant service, which does not currently support CORS.

Here are the steps in deploying this sample application to Windows Azure (we’ll cover each step as we go.)

1. Create a Windows Azure Virtual Machine

2. Download the application and its pre-requisites

3. Subscribe to Cloudant on Windows Azure and initialize databases

4. Create a Windows Azure website

5. Customize the application configuration

6. Deploy and Start a CORS-proxy on the Windows Azure VM

7. Deploy the front-end application to the Windows Azure website

Create a Windows Azure Virtual Machine

The first step in setting up this tutorial is to create a Windows Azure virtual machine (VM) running Windows Server. An extensive tutorial can be found here, but below are the steps needed to set up the server for use with this tutorial.

Sign into your Windows Azure Management Portal, then select New on the command bar at the bottom of the page:

Click Compute followed by Virtual Machine. Click From Gallery to open the Virtual machine configuration page.

Click Platform Images and select Window Server 2012 Datacenter. Note that you could also use a virtual machine with Windows Server 2008 R2 Sp1.

Click the arrow at the bottom right of the page to go to page 2 of the virtual machine configuration.

Select the latest date for Version release date. Give your virtual machine a unique name such as <yourusername>CouchTutorial. Select the size in the Size dropbox. An ‘Extra small’ machine should suffice for this tutorial.

Insert a username and a strong password of your choice. Make a note of both.

Continue by clicking on the right arrow at the bottom right of the page.

Select Create a new cloud service in the Cloud Service dropdown if not already selected.

Other settings:

· Enter a unique name such as “<yourUserName>CouchTutorial” in Cloud Service DNS Name.

· If the DNS name you select is already taken, you will need to select another DNS name.

· Select a region in the Region/Affinity Group/Virtual Network dropdown.

· Select Use an automatically generated storage account in the storage account dropdown.

· Keep the availability set as (None) since this is a sample application. For a real application, you may want to use availability set by deploying group of virtual machines.

Click the arrow at the bottom right of the page to continue

On the Endpoint settings page keep the default values, as Remote Desktop and Powershell settings use these ports as default.

Click the check mark at the bottom of the dialog to complete the Virtual machine configuration.

The new virtual machine should show up in the list of virtual machines:

Virtual machine provisioning should take around 15 minutes. The virtual machine status should change from Starting (Provisiong) to Running (Provisioning) and finally to Running.

Next, we connect to the new virtual server. Select the VM once the status is Running and press Connect on the lower bar. This will download a RDP (Remote Desktop Protocol) file with connection strings and credentials to connect to the virtual server remotely.

Select the downloaded .rdp file and double click it to start the Remote Desktop Connection.

Click Connect in the Remote Desktop Connection dialog.

If it fails to connect, make sure that the virtual machine is in a running state, and that remote access to the virtual machine is enabled from the local computer.

Once connected, enter the user name (e.g. CouchAdmin) and the password you chose earlier and click OK. In the Remote Desktop Connection dialog shown below, click Yes.

You should now be logged into the virtual machine just created.

Setting up Node on the Virtual Machine

Next, we will download and install node.js on the new virtual server. First we are going to turn off the Internet Explorer Enhanced Security configuration (IEESC) in case we are prevented from downloading files.

On the virtual machine, open Server Manager and select Configure this local server:

In the Properties section, click On next to IE Enhanced Security Information.

In the Internet Explorer Enhanced Security Configuration dialog, select Off for Administrators and click OK. Alternately, you can add necessary sites in your list of safe websites in Internet Explorer.

Open Internet Explorer on the virtual machine and navigate to http://nodejs.org/dist/v0.10.15/x64/node-v0.10.15-x64.msi. (This may involve you adding nodejs.org to your list of safe websites.)

This will download an .msi file for node setup. You may run the downloaded .msi file or save it locally and run it later.

After running a security scan, the .msi installer will start node.js setup.

Select all default values in node.js setup panels and select accept with the terms in the End User License Agreement license terms to install node.js on the virtual machine.

Downloading the application files from GitHub

On your local machine, navigate to https://github.com/MSOpenTech/WACloudantTutorial. Select the “Download ZIP” button option.

Use RDP to transfer the file to the virtual machine. Place the file in the C:\ directory.

Right click the zip file on the virtual machine and choose extract all files. In the Extract Compressed (Zipped) Folder dialog.

Leave the files there for now, we’ll place them where they should be later.

Subscribe to the Cloudant CouchDB-as-a-Service on Windows Azure and initialize databases

This application uses CouchDB for storing data remotely. In this case we are using Cloudant’s CouchDB-as-a-Service offering on Windows Azure.

Go to http://cloudant.com/ to setup the account and create necessary databases.

Select Sign Up on the main page.

Fill in the information for your new account. Make a note of your username which will be part of the Cloudant database URL. Later, we will configure our application to direct database requests to this URL/database.

Create Cloudant application databases

Next we create application databases and set their permissions. Instead of using the admin account created earlier as the application account, we will create and use another restricted account, and provide minimal permissions to the new restricted account to improve application security. The Cloudant API Key provides restricted read and write permissions – have a look at Cloudant’s security overview for more information on API keys and other security features built-in to Cloudant’s service.

Open the Dashboard, and click New Database. Enter ‘sessions’ in New database and click Create:

Next, create another database called ‘userprefs’. Now you should have two databases, as shown here:

Now let’s create the API Key. Click sessions followed by Permissions:

Click Generate API Key:

Make a note of the API key and password because we will use them both in the future.

For the sessions database, click the Read checkbox for newly created API key as shown below. Since the application will only read the conference session data, we need not give any other privileges to the API key.

Now return to the Dashboard and select userprefs followed by Permissions.

Under Share Database, type in the API Key you just used for the ‘Sessions’ database.

Click Grant Rights.

Under Permissions, select Read, Create, and Write as shown below. Since we will save user preferences, we need to provide Read, Write and Create permissions to the API Key.

Configuring CORS-proxy

On the Virtual Machine, open GruntFile.js with Notepad. Look for the following lines:

'cors-server': {

base:'https://[api_username]:[api_password]@[username].cloudant.com',

dns: 'http://[Virutal Machine DNS Name].cloudapp.net',

port: 2020

},

Replace [api_username] with the API key of your Cloudant application and [api_password] with the API password you created earlier. Replace [username] with the username of your Cloudant account.

Replace the [Virtual Machine DNS Name] with the DNS of the Virtual Machine. You can get the DNS name from the Windows Azure Management Portal in the Dashboard tab of your VM.

Your gruntfile should look something like this:

'cors-server': {

base:'https://misagedstionsio:5M8V8SEQKVIKapb@mycloudant.cloudant.com',

dns: 'http://couchtutorialtest.cloudapp.net',

port: 2020

},

Next, on the Virtual Machine, open up config.js located in the src directory. Look for the following lines:

remote: {

sessions: "http://[VM DNS Name].cloudapp.net:2020/sessions",

userprefs: "http://[VM DNS Name].cloudapp.net:2020/userprefs",

Replace both [Virtual Machine DNS Name] entries with the same Virtual Machine DNS Name.

When done it should look like this:

remote: {

sessions: "http://couchtutorial.cloudapp.net:2020/sessions",

userprefs: "http://couchtutorial.cloudapp.net:2020/userprefs",

},

Setting up the Firewall and Endpoints

Next, we need to grant access to transfer data over TCP in both the Firewall and the Endpoints of the Virtual Machine.

From the Virtual Server’s Start Menu, select Windows Firewall with Advanced Security.

Right click Inbound Rules in the left column and then select New Rule:

Select Port and press Next.

Under Specific Local Ports, type 2020:

Select the defaults for the next two screens and provide the name CORS.

Using Internet explorer, navigate to the Windows Azure Management Portal.

Select the Virtual Machine tab and then the Virtual Machine we created. Click on the virtual machine name and select the Endpoints tab.

Click Add from the lower toolbar and then select Add Endpoint, if not already selected, and navigate to next tab using right arrow at the bottom right of the page.

Name the endpoint, select TCP as the protocol, and set both the public and private port to 2020. Select the check mark at the bottom right of the page to save the rule.

The endpoint configuration should look like this:

Creating the Data for the Application

Our database is now set up but it’s empty. We can load sample data for a demo conference using a simple node.js application with sample data in JSON format.

The sample file should be located on your VM at <zip file extraction location>\upoad\upload.js.

If you open the .js file, you can see the stored data and a small script to upload the values the Cloudant database.

Open the upload.js. file and look for the following code near the bottom:

request({

uri: "https://[username]:[password]@[username].cloudant.com/sessions",

method: "POST",

json: interior

});

Replace [username] with your Cloudant username and every [password] with your Cloudant password.

Open a Command Prompt and run the following:

C:\users\CouchAdmin> cd C:\upload

C:\upload> npm install request –l

C:\upload> node upload.js

Once completed, the command prompt should indicate that 24 documents were uploaded.

Install the CORS-proxy

As mentioned in the introduction, we’re going to use Grunt to create the files for the website as well as start the CORS-proxy on the virtual machine. First, we need to install Grunt’s Command Line Interface (CLI).

In the Azure virtual machine, open up a Command Prompt as an Administrator. Type the following commands to install Grunt:

C:\> cd C:\conference
C:\conference> npm install –g grunt-cli
C:\conference> npm install -l

Start the CORS-proxy

Next, we tell Grunt to start CORS-proxy and create files for the web site. Enter the following command in the command window:

C:\conference>grunt

Running "copy:html" (copy) task

Copied 4 files

Running "copy:pages" (copy) task

Copied 10 files

Running "copy:lib" (copy) task

Created 5 directories, copied 18 files

Running "concat:dist/main.js" (concat) task

File "dist/main.js" created.

Running "less:development" (less) task

File dist/main.css created.

Running "cors-server" task

Starting CORS server http://couchtutorial.cloudapp.net:2020/ => https://misa

gedstionsioncesparch:5M8V8SEQKVIKapb8IwQ8Tquc@mycloudant.cloudant.com/

Running "connect:server" (connect) task

Started connect web server on localhost:8080.

Running "watch" task

Waiting...

In addition to starting the CORS proxy, grunt also produces the HTML files that we need. They will be located at C:\conference\dist .

Setting up the Website

Next, we create and configure a web site using Windows Azure Web Sites (WAWS). Then we will move the contents of c:\conference\dist to the new Web site.

Return to the Windows Azure Management Portal. On the command bar select New at the bottom of the page:

Select Web Site then Quick Create, enter a unique URL and select the local region:

Select Create Website.

Next, open a browser on the virtual machine and connect to the Windows Azure Management Portal and login. Select the Dashboard of the website we just created.

Click Reset your deployment credentials on the right hand side. Enter a user name and password. Click check mark:

Find the FTP Host Name located in the right column of the dashboard and click that link to open the following dialog:

Enter the user name and the password you created for the Virtual Machine.

You should now see the following:

Press the Alt key to activate the menu on the VM:

Select View and then Open FTP Site in File Explorer:

If you see another Password Prompt, enter the VM username and password you entered earlier. In the file explorer, click site, then wwwroot. You should see the following:

Delete the file ‘hostingstart.html’.

Open files from “C:\conference\dist” and drag and drop those files into FTP File Explorer. Files should now look like this:

We have now successfully created and configured our web site and it should be completely operational!

Testing the Application

In a browser, go to [Your Windows Azure Website Name].azurewebsites.net. You should now see the application running in the browser:

To test the functionality, try the ‘Like’ and ‘Dislike’ buttons on some of the sessions, and add comments. Click the green button on the top toolbar to synchronize user preferences with the remote database.

You can see changes to the data on the back-end via the Cloudant portal as well. Check the stdocuments in the sessions or userprefs database for changes.

Conclusion

Congratulations! At this point your multi-tier web application is set up in the cloud on Windows Azure. You have assembled a Cloudant instance as a data repository, a virtual machine to manage conference sessions and users, and a Web client to display the conference data.

Please let us know what you think! Add your suggestions, responses, questions, or anything else in the comments below.

The post Tutorial – Building a Multi-Tier Windows Azure Web application use Cloudant’s Couchdb-as-a-Service, node.js, CORS, and Grunt appeared first on MS OpenTech.