This is a simple Node.js web app using the Express framework and EJS templates.
The app has been designed with cloud native demos & containers in mind, in order to provide a real working application for deployment, something more than "hello-world" but with the minimum of pre-reqs. It is not intended as a complete example of a fully functioning architecture or complex software design.
Typical uses would be deployment to Kubernetes, demos of Docker, CI/CD (build pipelines are provided), deployment to cloud (Azure) monitoring, auto-scaling
The app has several basic pages accessed from the top navigation menu, some of which are only lit up when certain configuration variables are set (see 'Optional Features' below):
- 'Info' - Will show system & runtime information, and will also display if the app is running from within a Docker container and Kubernetes.
- 'Tools' - Some tools useful in demos, such a forcing CPU load (for autoscale demos), and error/exception pages for use with App Insights or other monitoring tool.
- 'Monitor' - Display realtime monitoring data, showing memory usage/total and process CPU load.
- 'Weather' - (Optional) Gets the location of the client page (with HTML5 Geolocation). The resulting location is used to fetch a weather forecast from the Dark Sky weather API
- 'Todo' - (Optional) This is a small todo/task-list app which uses MongoDB as a database.
- 'User Account' - (Optional) When configured with Azure AD (application client id and secret) user login button will be enabled, and an user-account details page enabled, which calls the Microsoft Graph API
Live instances:
- Be using Linux, WSL or MacOS, with bash, make etc
- Node.js - for running locally, linting, running tests etc
- Docker - for running as a container, or image build and push
- Azure CLI - for deployment to Azure
Clone the project to any directory where you do development work
git clone https://github.com/benc-uk/vuego-demoapp.git
A standard GNU Make file is provided to help with running and building locally.
$ make
help ๐ฌ This help message
lint ๐ Lint & format, will not fix but sets exit code on error
lint-fix ๐ Lint & format, will try to fix errors and modify code
image ๐จ Build container image from Dockerfile
push ๐ค Push container image to registry
run ๐ Run locally using Node.js
deploy ๐ Deploy to Azure Web App
undeploy ๐ Remove from Azure
test ๐ฏ Unit tests with Jest
test-report ๐คก Unit tests with Jest & Junit output
test-api ๐ฆ Run integration API tests, server must be running
clean ๐งน Clean up project
Make file variables and default values, pass these in when calling make
, e.g. make image IMAGE_REPO=blah/foo
Makefile Variable | Default |
---|---|
IMAGE_REG | ghcr.io |
IMAGE_REPO | benc-uk/nodejs-demoapp |
IMAGE_TAG | latest |
AZURE_RES_GROUP | temp-demoapps |
AZURE_REGION | uksouth |
AZURE_SITE_NAME | nodeapp-{git-sha} |
Web app will be listening on the usual Express port of 3000, but this can be changed by setting the PORT
environmental variable. Tested with Node v8.x, 10.x, 12.x and 14.x
Public container image is available on GitHub Container Registry.
Run in a container with:
docker run --rm -it -p 3000:3000 ghcr.io/benc-uk/nodejs-demoapp:latest
Should you want to build your own container, use make image
and the above variables to customise the name & tag.
The app can easily be deployed to Kubernetes using Helm, see deploy/kubernetes/readme.md for details
A working set of CI and CD release GitHub Actions workflows are provided .github/workflows/
, automated builds are run in GitHub hosted runners
The app will start up and run with zero configuration, however the only features that will be available will be the INFO and TOOLS views. The following optional features can be enabled:
Enable this by setting APPINSIGHTS_INSTRUMENTATIONKEY
The app has been instrumented with the Application Insights SDK, it will however need to be configured to point to your App Insights instance/workspace. All requests will be tracked, as well as dependant calls to MongoDB or other APIs (if configured), exceptions & error will also be logged
This article has more information on monitoring Node.js with App Insights
Enable this by setting WEATHER_API_KEY
This will require a API key from Dark Sky, you can sign up for free and get one here. The page uses a browser API for geolocation to fetch the user's location.
However, the geolocation.getCurrentPosition()
browser API will only work when the site is served via HTTPS or from localhost. As a fallback, weather for London, UK will be show if the current position can not be obtained
Enable this by setting AAD_APP_ID
, AAD_APP_SECRET
This uses Microsoft Authentication Library (MSAL) for Node to authenticate via MSAL with OIDC and OAuth 2.0. The flow it uses is the "OAuth 2.0 Authorization Code Grant", which is standard for server side (confidential) apps.
In addition the user account page shows details & photo retrieved from the Microsoft Graph API
You will need to register an app in your Azure AD tenant. See this guide. Add a secret to your app and use the app's ID & secret value in AAD_APP_ID
& AAD_APP_SECRET
AAD_REDIRECT_URL_BASE
should be the base URL of where your app is running, e.g. http://localhost:3000
or https://example.com
. It should start with http://
or https://
. This is used by the login flow to redirect back to the app, the path /redirect
will be appended to this value to form the complete redirect URL
Enable this by setting TODO_MONGO_CONNSTR
A mini todo & task tracking app can be enabled if a MongoDB backend is provided and a connection string to access it. This feature is primarily to show database dependency detection and tracking in App Insights
The default database name is todoDb
but you can change this by setting TODO_MONGO_DB
You can stand up MongoDB in a container instance or in Cosmos DB (using the Mongo API). Note. When using Cosmos DB and the per database provisioned RU/s option, you must manually create the collection called todos
in the relevant database and set the shard key to _id
The following configuration environmental variables are supported, however none are mandatory. These can be set directly or when running locally will be picked up from an .env
file if it is present. A sample .env
file called .env.sample
is provided for you to copy
If running in an Azure Web App, all of these values can be injected as application settings in Azure.
Environmental Variable | Default | Description |
---|---|---|
PORT | 3000 | Port the server will listen on |
TODO_MONGO_CONNSTR | none | Connect to specified MongoDB instance, when set the Todo feature will be enabled in the menu bar |
TODO_MONGO_DB | todoDb | Name of the database in MongoDB to use (optional) |
APPINSIGHTS_INSTRUMENTATIONKEY | none | Enable Application Insights monitoring |
WEATHER_API_KEY | none | DarkSky weather API key. Info here |
AAD_APP_ID | none | Application ID of app registered in Azure AD |
AAD_APP_SECRET | none | Secret / password of app registered in Azure AD |
AAD_REDIRECT_URL_BASE | none | Hostname/domain where app is running |
If you want to deploy to an Azure Web App as a container (aka Linux Web App), a Bicep template is provided in the deploy directory
For a super quick deployment, use make deploy
which will deploy to a resource group, temp-demoapps and use the git ref to create a unique site name
make deploy
You can also very quickly deploy to Azure App Service directly with the Azure CLI and az webapp up
. Note. <app-name>
must be globally unique. Change the sku to a larger size, e.g. P1V2
for a much faster deployment
cd src
az webapp up --sku F1 --name <app-name>
- Nov 2021 - Refresh packages and added make + bicep
- Nov 2020 - Switched to MSAL-Node library for authentication
- Oct 2020 - Added GitHub Actions pipelines and Bicep IaC
- Jan 2020 - Added monitor page and API
- Jun 2019 - Added Azure AD login and profile page, cleaned up Todo app MongoDB code
- Apr 2019 - Updated to latest App Insights SDK package, and moved to Bootstrap 4
- Dec 2018 - Modified weather to use client browser location, rather than use IP
- Jul 2018 - Switched todo app over to MongoDB, fixed weather
- Feb 2018 - Updated App Insights monitoring
- Nov 2017 - Update to use Node 8.9
- Oct 2017 - Updated App Insights, improved Dockerfile
- Sept 2017 - Added weather page
- Sept 2017 - Major revamp. Switched to EJS, added Bootstrap and App Insights
- Aug 2017 - Minor changes and fixes for CRLF stuff
- July 2017 - Updated Dockerfile to use super tiny Alpine Node 6 image
- June 2017 - Moved repo to Github