aqie-maps-prototype

Node.js prototype template, using the GOV.UK Prototype Kit and the GOV.UK Frontend.

Basically the GOV.UK Prototype Kit and GOV.UK Frontend wrapped up and provided on the Core Delivery Platform

• Requirements
  • Node.js
• GOV.UK Prototype Kit and GOV.UK Frontend
• Using the refreshed GOV.UK brand
• Setting a password
• Setting multiple passwords
• Removing the need for a password
• Npm scripts
• Updating dependencies
• Environment Variables and Secrets
  • Local development
  • Environment Variables on CDP
  • Environment Variables in the GOV.UK Prototype Kit
  • Secrets
• Creating a secret
• aqie-back-end service
  • Running locally
  • Endpoints used
  • Deploying to CDP
• Docker
  • Docker Compose
  • Production image
  • Debug docker
• Licence
  • About the licence

Requirements

Node.js

Install Node.js >= v22 and npm >= v11. You will find it easier to use the Node Version Manager nvm

To use the correct version of Node.js for this application, via nvm:

cd aqie-maps-prototype
nvm use

GOV.UK Prototype Kit and GOV.UK Frontend

The GOV.UK Prototype Kit is a tool for building interactive prototypes that look like pages on GOV.UK, it provides components and styles from the GOV.UK Frontend. Both are provided by the Government Digital Service (GDS), this template provides both tools in a wrapper that runs on the Core Delivery Platform at Defra.

Note

The GOV.UK Prototype Kit is built with express.js. The Node.js applications cdp-node-frontend-template and cdp-node-backend-template at Defra are built with Hapi.js

• For information on the GOV.UK Prototype Kit see https://prototype-kit.service.gov.uk/docs/
• For tutorials on how to use the GOV.UK Prototype Kit see https://prototype-kit.service.gov.uk/docs/tutorials-and-guides
• For help with the underlying GOV.UK Frontend see:
  • https://design-system.service.gov.uk/
  • https://github.com/alphagov/govuk-frontend

Warning

The aqie-maps-prototype is not a production ready application, it is a tool for prototyping. It is not designed to be used in production or to be resilient, secure or performant, nor should it be. It is designed to be used for prototyping ideas and testing them with users. It's a great tool for prototyping GOV web applications.

Using the refreshed GOV.UK brand

The refreshed GOV.UK brand is available and turned on by default in the aqie-maps-prototype. To turn it off simply go to app/config.json and set the "rebrand" property to false. This will turn off the refreshed brand and use the legacy brand instead.

{
  "plugins": {
    "govuk-frontend": {
      "rebrand": true
    }
  }
}

Setting a password

Caution

Do not commit the .env file to GitHub, it is in the .gitignore file by default. Sensitive information such as a password can be provided to a prototype via the Secrets page of your prototype in the CDP Portal Frontend

Basic authentication is on by default in CDP environments for prototypes. This means you will need to set a password for your prototype. You can do this via your prototypes secrets tab in the Portal Frontend. For information on how to do this, follow these steps:

1. Read the Setting a password section on https://prototype-kit.service.gov.uk/docs/publishing
2. Go to the CDP Portal Frontend
3. Log in
4. Navigate to your prototype on the services list page
5. Navigate to your prototypes Secrets tab
6. Add a secret with a name PASSWORD and a value of your choosing
7. Re-deploy your prototype for the new secrets to be made available to it

Setting multiple passwords

The GOV.UK Prototype Kit has the ability to set up multiple passwords via secrets. For more information on how to do this read the If you want to create additional passwords section on https://prototype-kit.service.gov.uk/docs/publishing. To add a secret to an environment your prototype is running in see Creating a secret

Removing the need for a password

By default, the GOV.UK Prototype Kit requires a password has been set on your prototype when it has been deployed to an environment. If you would like to turn off this requirement you can do so by setting the following environment variable:

ENV USE_AUTH=false

This can be set in cdp-app-config for instructions on how to do so read Environment Variables on CDP.

Npm scripts

All available Npm scripts can be seen in package.json To view them in your command line run:

npm run

Updating dependencies

To update dependencies use npm-check-updates:

The following script is a good start. Check out all the options on the npm-check-updates

ncu --interactive --format group

Environment Variables and Secrets

Environment variables and Secrets are used to configure your prototype. Where you set them can be seen in the table below.

Type	Environment	Where to set them
Sensitive secrets and Non-sensitive environment variables	local	.env file
Sensitive secrets	CDP	CDP Portal Frontend services secrets page
Non-sensitive environment variables	CDP	CDP App Config repository by raising a pull request

Local development

Caution

Do not store passwords in GitHub. Sensitive information such as a password can be provided to a prototype via the secrets page in the CDP Portal Frontend. The .env file is for local development only.

To set environment variables and secrets locally copy the .env.template file to .env and add any environment variables or secrets your local environment needs.

Environment Variables on CDP

When your prototype is running on a CDP environment, E.g. dev or ext-test. You can set environment variables via a GitHub pull request.

To add environment variables read - https://github.com/DEFRA/cdp-documentation/blob/main/how-to/config.md. This will guide you to add non-sensitive environment variables to the https://github.com/DEFRA/cdp-app-config repository via a pull request.

Environment Variables in the GOV.UK Prototype Kit

The following environment variables are available in the GOV.UK Prototype Kit. For more information see their https://prototype-kit.service.gov.uk/docs/ or https://github.com/alphagov/govuk-prototype-kit.

Name	Value	Description
PASSWORD	string	Password for basic authentication
PASSWORD_KEYS	string	Comma-separated list of keys for password authentication

Secrets

To add sensitive environment variables know as secrets to your prototype. Add them via your prototypes secrets page on the CDP Portal.

Creating a secret

1. Go to the CDP Portal Frontend
2. Log in
3. Navigate to your prototype on the services list page
4. Navigate to your prototypes Secrets tab
5. Add a secret on your chosen environment with a name and value of your choosing
6. Re-deploy your prototype for the new secrets to be made available to it

aqie-back-end service

This prototype consumes data from the aqie-back-end service. You will need a running instance of it to see real data locally — without it the app will still load but the homepage will show a Not Connected banner.

Running locally

The easiest way to run aqie-back-end locally is via its own Docker Compose file. From the aqie-back-end directory:

docker compose up --build

This starts aqie-back-end on port 3001 and creates the shared cdp-tenant Docker network that this prototype also joins (see Docker Compose).

Once it is running, verify connectivity:

curl http://localhost:3001/health

When running both services via Docker Compose, AQIE_BACK_END_URL is automatically set to http://aqie-back-end:3001 using Docker's internal networking — no manual configuration needed.

Endpoints used

Endpoint	Description
GET /health	Health check — used by the homepage connectivity banner
GET /forecasts	Air quality forecasts stored in MongoDB (populated by cron 5–10am)
GET /measurements	Pollutant measurements stored in MongoDB
GET /monitoringStations	Cached monitoring station metadata from MongoDB (populated on startup, refreshed every 6 hours)

Deploying to CDP

When this prototype is deployed to a CDP environment the AQIE_BACK_END_URL environment variable must be set to the internal URL of the aqie-back-end service running in that environment (e.g. http://aqie-back-end).

Add the variable via a pull request to the cdp-app-config repository. See Environment Variables on CDP for step-by-step guidance.

Docker

For the most part you will not need to be concerned with docker when running this prototype. Everything is set up and your docker will automatically be built, published and pushed when you deploy a new version of your prototype via the UI in the CDP Portal.

Docker Compose

The recommended way to run this prototype locally alongside aqie-back-end. Both services join the shared cdp-tenant Docker network, so they can reach each other by service name.

Important

Start aqie-back-end first (via docker compose up --build in its directory) so the cdp-tenant network exists before this prototype starts.

Build and start:

docker compose up --build

Stop:

docker compose down

The AQIE_BACK_END_URL is automatically set to http://aqie-back-end:3001 inside the container. Other variables (e.g. PASSWORD) are loaded from your .env file — copy .env.template to .env if you haven't already.

Production image

Build:

docker build --no-cache --tag aqie-maps-prototype .

Run:

Update the password field to your password. On Linux, --add-host is required so the container can reach aqie-back-end running on your host machine.

docker run \
  --add-host=host.docker.internal:host-gateway \
  -e PASSWORD=beepBoopBeep \
  -e PORT=3000 \
  -e AQIE_BACK_END_URL=http://host.docker.internal:3001 \
  -p 3000:3000 \
  aqie-maps-prototype

Debug docker

To debug issues in docker and to have a look at the built docker container in the same way as when it runs on CDP. You can run an interactive shell:

Build:

docker build --no-cache --tag aqie-maps-prototype .

Run:

docker run -it --entrypoint /bin/ash aqie-maps-prototype

Licence

THIS INFORMATION IS LICENSED UNDER THE CONDITIONS OF THE OPEN GOVERNMENT LICENCE found at:

http://www.nationalarchives.gov.uk/doc/open-government-licence/version/3

The following attribution statement MUST be cited in your products and applications when using this information.

Contains public sector information licensed under the Open Government license v3

About the licence

The Open Government Licence (OGL) was developed by the Controller of Her Majesty's Stationery Office (HMSO) to enable information providers in the public sector to license the use and re-use of their information under a common open licence.

It is designed to encourage use and re-use of information freely and flexibly, with only a few conditions.