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:
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
Maybe in I’ll get to that in another tutorial…no promise though!
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.
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:
To go up a level in the directory, type:
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).
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.
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:
- Create an app folder
- Navigate to the folder using cmd
- Type into console
- Press ENTER until you see
entry point: (index.js)
Change it to
entry point: (app.js)
- Keep spamming ENTER until it’s over
- 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.
- Create app.js with the content according to Expressjs Hello World guide
- 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:
Second, follow this deployment guide here. Thanks God, there’s one using the GUI
You will need git, of course, download and install it here if you haven’t already.
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
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:
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:
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.
Now if you cannot push to server at all and you get git repo error, try the deployment steps again but this time,
- Clone a fork from the server first using
git clone <giturlfromportal>
- Overwrite the content of that clone repo folder with the content of your Hello World. Leave .git folder in those folders alone.
- Type the commands to add remote to the clone repo, just in case
git remote add azure <giturlfromportal>
- 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.