Azure Web App Deployment with Aurelia and GitHub
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.
- Publish via `git push` to an Azure Web App in one step.
- 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.
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.
- Git installed locally.
- NPM install locally.
- An account at GitHub.
- 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.
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 firstname.lastname@example.org: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.
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.
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.