aurelia

Azure Web App Deployment with Aurelia and GitHub

Goal

It’s import to publish (to an Azure Web App) in a single step. In fact, I would add that to the Joel Test. This can be tricky with Aurelia because it uses `gulp` and `jspm` to build, and we want to keep the output of those from polluting our Git repository. How do we tell the deployment tooling to take the necessary steps? This tutorial shows how and uses the Aurelia Navigation Skeleton as the application. Here are the two goals of this tutorial.

  1. Publish via `git push` to an Azure Web App in one step.
  2. Keep only our app’s source code in the repositories (i.e. no build results or packages.)

I am happy to say that we succeeded. This is the final product: http://webnotwar2.azurewebsites.net/ and this is its GitHub repository: https://github.com/bigfont/webnotwar02

Prerequisites

Here are the tools and technologies that you need to have installed to work thru this tutorial. It would also be helpful to have a general working knowledge of how each works.

  1. Git installed locally.
  2. NPM install locally.
  3. An account at GitHub.
  4. An account with Azure.

Run Locally before Deploying to Azure

Download the Aurelia navigation skeleton sample. Extract it. Copy the content of `skeleton-typescript` into an empty directory. Then initialize a Git repository (`git init`) in that directory. We can now test the site locally by running the following commands. They install the node and jspm packages and start a nodeJS development server for us.

PS> npm install
PS> jspm install -y
PS> gulp watch

 

You will see something like this if you browse to `localhost:9000` in a web browser. Good stuff. The site works locally and we can now prepare the publish.

Aurelia on an Azure Web App.

Create an Azure Web App deployment Script

To publish this beauty, the Azure deployment tool called Kudu will need instructions on what to deploy and how to deploy it. This will include:

  • Installing JSPM packages.
  • Using gulp to bundle the resource for performance.

Here is how to create the deployment script. First install the Azure Command Line Interface. Then create a deployment script for a basic website. Doing so will add two files to the root of our repository: `.deployment` and `deploy.cmd`. Here is how to install the Azure Command Line Interface and to create the deployment script.

PS> npm install azure -g
PS> azure config mode asm
PS> azure site deploymentscript --basic

 

The out-of-the-box `deploy.cmd` file verifies that Node.js and KuduSync are installed and copies our site’s files to the deployment target. We can ignore most of what it does. We need only to modify its Deployment section. This is the final `Deployment` section after we have modified it.

:: Deployment
:: ----------

echo Handling Aurelia App deployment.

:: 1. Install JSPM packages and then bundle resources.
pushd "%DEPLOYMENT_SOURCE%"
call npm install
call jspm install -y
call gulp bundle
popd

:: 2. Set files for Kudu not to copy to the Azure Web App.
SET KUDU_IGNORE=.deployment;.editorconfig;.gitignore;.npmignore;build;custom_typings;doc;node_modules;test;typings;aurelia.protractor.js;deploy.cmd;gulpfile.js;karma.conf.js;package.json;protractor.conf.js;README.md;tsconfig.json;tslint.json;typings.json;wallaby.js

:: 3. KuduSync
IF /I "%IN_PLACE_DEPLOYMENT%" NEQ "1" (
  call :ExecuteCmd "%KUDU_SYNC_CMD%" -v 50 -f "%DEPLOYMENT_SOURCE%" -t "%DEPLOYMENT_TARGET%" -n "%NEXT_MANIFEST_PATH%" -p "%PREVIOUS_MANIFEST_PATH%" -i "%KUDU_IGNORE%"
  IF !ERRORLEVEL! NEQ 0 goto error
)

 

What we did was to install our npm and jspm dependencies, and then run the gulp bundle command. We also told Kudu to ignore a bunch of files when it copies our project to the target.

We can test the `deploy.cmd` locally by running it. It will publish in `..\artifacts`, so make sure that directory exists! Here is the result of running our `deploy.cmd` file. That looks about right.

PS> .\deploy.cmd
# output hidden for clarity
# install jspm packages, bundle resources...
# copy files to deployment target
PS> dir ..\artifacts\wwwroot\ -name
dist           
jspm_packages  
src            
styles         
config.js      
favicon.ico    
index.html     
index.js       

 

That’s great. We’ve published locally. If we want to do a thorough test, we can point IIS at the `..\artifacts\wwwroot` directory and make sure that the Aurilia app runs locally. We won’t do that now. Instead, let’s deploy to Azure… but first.

Push to GitHub

Create a GitHub repository and add it as the remote. E.g.

PS> git remote add origin git@github.com:bigfont/WebNotWar02.git
PS> git branch --set-upstream-to=origin/master master
PS> git pull
PS> git add -A
PS> git commit -m "Ready for deployment to Azure Web App."
PS> git push

 

This is an image of the repository to which we pushed. You can see that there are lots of files there and that NONE of them are build output. I.e. there is no node_modules, jspm_packages, nor dist directory there because we do not want build output nor packages polluting our repository.

The GitHub repository that we're deploying to the Azure Web App.

Integrate GitHub with the Azure Web App

Let’s get this deployed already! In the Azure portal (portal.azure.com), create a new Web App: `New > Web + Mobile > Web App > Et Cetera`.  Once Azure has deployed the web app, open the App’s Settings and choose Deployment Source. Here is an example setup that points it at the GitHub repo that we created.

Our Azure Web App's deployment source settings.

After hitting OK, Azure will automatically sync with the GitHub repository and run the `deploy.cmd` script that we composed. It will install all the node modules and jspm modules, and then bundle it all up with gulp. Now each `git push` to `master` deploys in one step. Down the road, its worth tweaking which node modules we install in production.

If you have any questions, let me know @dicshaunary on Twitter.