Deploy a Nodejs app to Microsoft Azure

This tutorial is provided as a newbie-friendly version of the official document provided by Microsoft. If you prefer the formal technical writing style (no first or second person pronouns, etc.), please refer to the the original tutorial here:

https://azure.microsoft.com/en-us/documentation/articles/app-service-web-nodejs-get-started/

Unlike MS tutorial, I’ll be using Expressjs’s bare-bone Hello World app without view engine and using more graphical interfaces (and fewer command lines). Plus, I’ll include a bunch explanations on some web development concepts that might be alien to the average Joe in Layman’s terms. Hopefully, you’ll find these extra bits helpful.

UNDERSTANDING WEB APPS AND NODEJS

What is Nodejs? Well, Nodejs is a server-side scripting engine that crunches files written in javascript (which is a client-side web language originally) and turns them into web apps.

So how do you know if an application is client-side or server-side? Load the webpage and disconnect from the internet. Whichever function still works offline is client-side. Client-side apps generally consist of a html + css webfront and inline javascript and/or included javascript files you can download and use offline. The clients can download your source code and use it elsewhere; this characteristic makes client-side apps unsecured and unsuitable for multi-tenant sync operations.

Nodejs works with a bundle of software packages (written in .js) called “node modules“. Both Nodejs and node modules must be installed on the server for them to work. In server-side apps, you don’t let the client download javascript files and run on browser, you upload the javascript files to the server and ask Nodejs to run them. The client only gets the outputting result of the javascript source and never the source itself. This makes your web app…server-side. Easy, right?

Not quite. There are non-trivial differences between programming for client-side and programming for server-side. Unfortunately, this guide will only help you use Azure cloud service, which will only help you with the “Install Nodejs on the server”, “Upload javascript files to the server” and “Ask Nodejs to run them” parts. I’m afraid you’ll have to figure the programming out yourselves.

Maybe in I’ll get to that in another tutorial…no promise though!

GETTING NODEJS

Don’t worry, I’ll still help you get the tools and provide some helpful links for getting started with Nodejs in this tutorial. To start developing in Nodejs, you must first download Nodejs software and use your PC as a local server. Go ahead and get the software package here.

https://nodejs.org/en/

Nodejs comes with a node package manager (NPM). If you’ve used LaTeX’s package manager, Linux’s Software Center, Visual Studio’s NuGet package manager or even Arduino’s board manager before, you’ll find many similarities between these systems and npm. The idea is the same: “an application to manage other applications”.

NPM doesn’t have a graphic user interface (GUI). You’ll need to use cmd or powershell (or Bash/Terminal if you’re on Linux). Ugh, command lines…I know right? Well, for Windows users, here are a few basic commands to navigate in cmd

To access a folder at <path>, type:

cd "<path>"

To go up a level in the directory, type:

cd ..

And to switch drive, type C: or D: (or whatever character your drive is) and then cd to the folder you need. Folder creation, exploration, deletion and such, you can use Windows explorer if you don’t know what you’re doing (you’re welcome to mkdir, dir or rm your way through).

INSTALLING EXPRESSJS AND CREATING HELLO WORLD APP

Okay, so you have the npm installed, go ahead and follow this guide from expressjs (or jump to the end of this section for a quick guide).

https://expressjs.com/en/starter/hello-world.html

Expressjs is a node module, you use npm to install it. Installing node modules is a bit different from installing a Windows application; node modules are project-specific dependencies. You install an instance of the package to your project folder and that package can only be used inside that one project. If you have another project, you will have to install another instance of the package to that project folder if you want to use it.

There’s the -g flag you can set to install the package globally so that it is accessible in all nodejs apps on your local computer.

http://stackoverflow.com/questions/13167588/what-does-the-g-flag-do-in-the-command-npm-install-g-something

Bear in mind that if you change computer (or move to web server), that new computer will need to have that node module package installed as well or your app will fail. They’re kinda like NET. Framework or DirectX requirements for some Windows games.

Step-by-step quick guide:

  1. Create an app folder
  2. Navigate to the folder using cmd
  3. Type into console
    npm init
  4. Press ENTER until you see
    entry point: (index.js)

    Change it to

    entry point: (app.js)
  5. Keep spamming ENTER until it’s over
  6. Type into console
    npm install express --save

    The command with –save flag add the node module to dependency listing in package.json file in the root folder. Feel free to take a look at it.

  7. Create app.js with the content according to Expressjs Hello World guide
  8. Change port 3000 to port 1337

Note the last step, Azure web apps run on port 1337, not 3000.

PREPARING FOR AZURE CLOUD

Before you deploy to server, there’s one more thing you need to do. You need to install Azure SDK node package using npm. Without it, your Azure app won’t be able to run on Azure cloud. Back to your console screen and type in:

npm install azure

This one is sort of like a compiler and debugger for Azure apps, you don’t need it in dependencies list (package.json) so no need to set –save flag.

If you were following the MS tutorial, you would notice they relied on Azure CLI and more command lines to create web apps and link git repositories. “Ugh…more command lines, ” you must be grunting right now. Well, I understand, let’s do the same tasks the GUI way. First, you need an Azure account, go ahead and sign up a free account here:

https://azure.microsoft.com/en-us/free/

Second, follow this deployment guide here. Thanks God, there’s one using the GUI

https://azure.microsoft.com/en-us/documentation/articles/app-service-web-get-started/

You will need git, of course, download and install it here if you haven’t already.

https://www.git-scm.com/downloads

The above tutorial set up a git repository on Azure server, you can then push your application to that git repo. Just follow the deploy tutorial to create the app and stop at git clone step, I’ll explain the rest.

DEPLOYING TO AZURE CLOUD

Ok, so you have two repo: one is the Hello World app you created using Expressjs and the other is the git repo on the server. It would save you a lot of troubles if you started the development on the git clone of the server directly, but since you didn’t, you need a few extra steps to “overwrite” that repo with Hello World app.

First, rename your app folder to your Azure app name. Don’t know for sure? git clone it and take a look. Either ways, you’ll need to initialize git version control and turn your app folder into a git repo. To do that, type into your console

git init

You’ll see a hidden folder named .git was added to the folder.

Next, link this local git repo to the server by typing:

git remote add azure <giturlfromportal>

You get that giturlfromportal from here, under GIT URL field:

properties blade for your first web app in Azure
Screenshot shamelessly taken from the other tutorial, okay…

Now if you don’t know what git is…I know it’s a bit too late to mention it now but just in case you really don’t. Git is a version control software and it has some basic functions you will be using all over again. For this tutorial, I’ve used:

git init
git remote add <repo> <url>
git add <file>
git commit -m "<comment>"
git push <repo> master

Parameter “.” represents all files. The following command…

git add .

means “add all file that have been changed to this commit”, you can, of course, add a single file you’ve just changed to save time.

After the initialization and first commit, you can change to GitHub GUI software. It will create commits automatically for you and show historical changes graphically! Get GitHub GUI here:

https://desktop.github.com/

Now if you use “git push azure master” and you don’t get the “Deployment Successful” message at the end, read the next section. Otherwise, congratulation! You did it! Your very first Nodejs webapp on Azure cloud is live!

What’s next? Go ahead and explore Azure portal. There are a ton of tools to test and monitor your web app. Try out Visual Studio Code (or WebMatrix) for further Nodejs development. It has built-in git functionalities, syntax highlighting and it automatically sets up debug server in one click.

COMMON DEPLOYMENT ISSUES

You deployed the app and it didn’t work? Well damn!

First, check if your entry point is “app.js” or “server.js” file or not. Trust me, Azure iisnode engine is dumb, it can only detect nodejs app if you name your entry point “app.js” or “server.js”.

Next, if you get a deployment error related to version (of either nodejs itself or one of the package), change the version in package.json to one of the supported versions on Azure server. In the case of nodejs version, you always get a list of available versions at the end of each deployment.

deployment
The server checks for entry file and node js version even in successful deployment

Now if you cannot push to server at all and you get git repo error, try the deployment steps again but this time,

  1. Clone a fork from the server first using
    git clone <giturlfromportal>
  2. Overwrite the content of that clone repo folder with the content of your Hello World. Leave .git folder in those folders alone.
  3. Type the commands to add remote to the clone repo, just in case
    git remote add azure <giturlfromportal>
  4. Follow the usual commit procedure and push to server
    git add .
    git commit -m "<comment>"
    git push azure master

Still need help? Leave a comment below.

EXTRA: MORE ABOUT AZURE CLOUD

When you push a new commit to the server repo, a software engine called “iisnode” commands the Nodejs instance available on the server to compile your source code. It first reads your package.json file and installs the specified dependencies. Then, it proceeds to your application entry point “app.js” file and starts a web app server on port 1337.

This mirrors the process of local testing; Azure cloud is your PC, iisnode engine is you, the developer, and package.json is the list of “npm install…” commands you type into the console. See? Nothing complicated about this.

Advertisements

Published by

fujihita

Self-learner, designer, author and programmer.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s