digital-waste-tracking-admin-ui

Core delivery platform Node.js Frontend Template.

• Requirements
  • Node.js
• Server-side Caching
• Redis
• Local Development
  • Setup
  • Development
  • Production
  • Npm scripts
  • Update dependencies
  • Formatting
    • Windows prettier issue
• Docker
  • Development image
  • Production image
  • Docker Compose
  • Dependabot
  • SonarCloud
• Licence
  • About the licence

Requirements

Node.js

Please install Node Version Manager nvm

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

cd digital-waste-tracking-admin-ui
nvm use

Server-side Caching

We use Catbox for server-side caching. By default the service will use CatboxRedis when deployed and CatboxMemory for local development. You can override the default behaviour by setting the SESSION_CACHE_ENGINE environment variable to either redis or memory.

Please note: CatboxMemory (memory) is not suitable for production use! The cache will not be shared between each instance of the service and it will not persist between restarts.

Redis

Redis is an in-memory key-value store. Every instance of a service has access to the same Redis key-value store similar to how services might have a database (or MongoDB). All frontend services are given access to a namespaced prefixed that matches the service name. e.g. my-service will have access to everything in Redis that is prefixed with my-service.

If your service does not require a session cache to be shared between instances or if you don't require Redis, you can disable setting SESSION_CACHE_ENGINE=false or changing the default value in src/config/index.js.

Proxy

We are using forward-proxy which is set up by default. To make use of this: import { fetch } from 'undici' then because of the setGlobalDispatcher(new ProxyAgent(proxyUrl)) calls will use the ProxyAgent Dispatcher

If you are not using Wreck, Axios or Undici or a similar http that uses Request. Then you may have to provide the proxy dispatcher:

To add the dispatcher to your own client:

import { ProxyAgent } from 'undici'

return await fetch(url, {
  dispatcher: new ProxyAgent({
    uri: proxyUrl,
    keepAliveTimeout: 10,
    keepAliveMaxTimeout: 10
  })
})

Local Development

Setup

Install application dependencies:

npm install

Git hooks

Install git hooks (optional)

npm run git:hooks

Development

To run the application in development mode run:

npm run dev

Production

To mimic the application running in production mode locally run:

npm start

Npm scripts

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

npm run

Update 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

Formatting

Windows prettier issue

If you are having issues with formatting of line breaks on Windows update your global git config by running:

git config --global core.autocrlf false

Docker

Development image

Tip

For Apple Silicon users, you may need to add --platform linux/amd64 to the docker run command to ensure compatibility fEx: docker build --platform=linux/arm64 --no-cache --tag digital-waste-tracking-admin-ui

Build:

docker build --target development --no-cache --tag digital-waste-tracking-admin-ui:development .

Run:

docker run -p 3000:3000 digital-waste-tracking-admin-ui:development

Production image

Build:

docker build --no-cache --tag digital-waste-tracking-admin-ui .

Run:

docker run -p 3000:3000 digital-waste-tracking-admin-ui

Docker Compose

The compose stack runs the admin UI with the services it calls: waste-organisation-backend (for the Reporting page) and dwt-client-sync (for the Software providers page), with their own dependencies. They come from the stack shared with the other DWT service repos, in digital-waste-tracking-uat, so docker compose needs network access to fetch it. Every credential in it is made up and local-only, so you don't need a .env for it.

There are two ways to run it. Either run everything in Docker, with the admin UI built from your checkout and src/ mounted so it reloads as you edit:

docker compose up --build -d digital-waste-tracking-admin-ui

Naming the service starts just it and the services it depends on. Plain docker compose up starts the whole shared stack, which you don't need here.

Mounting src/ covers code, templates and styles. After changing dependencies or config outside src/ (such as vite.config.js), rebuild with --build.

Or start just the backends in Docker and run the admin UI locally:

cp .env.example .env
npm run dev:deps
npm run dev

Either way, the admin UI is at http://localhost:3000 and you log in as local / local.

The Software providers page lists the three test clients the stack seeds. dwt-client-sync also starts a fake of the CDP API it manages clients through, so syncing, and creating, rotating and deleting clients, work too:

curl -X POST -u digital-waste-tracking-admin-ui:local-admin-ui localhost:3005/clients/sync

Building the admin UI's image needs Docker BuildKit (the Dockerfile uses COPY --chmod). If docker buildx version fails, install the buildx plugin, e.g. brew install docker-buildx with Colima.

To try changes to the shared stack, point SHARED_COMPOSE at your local checkout:

SHARED_COMPOSE=../digital-waste-tracking-uat/shared-compose/compose.yml docker compose up --build -d

Browser tests

The admin tool's browser tests, including its accessibility checks, live in digital-waste-tracking-fe-uat. They run in CI against this repo's compose stack, and you can run them locally against your working copy the same way.

Start the admin UI with a Chrome browser for the tests to drive, and load the organisations the report tests expect:

docker compose -f compose.yml -f compose.browser-tests.yml up --build -d digital-waste-tracking-admin-ui selenium-chrome
docker compose exec -T mongodb mongosh waste-organisation-backend --quiet < ../digital-waste-tracking-fe-uat/test/utils/test-data-organisations.js

Then, in your fe-uat checkout:

ENVIRONMENT=local adminUiPassword=local ADMIN_UI_BASE_URL=http://digital-waste-tracking-admin-ui:3000 npm run test:admin-tool

The browser reaches the admin UI by its service name, digital-waste-tracking-admin-ui, so vite.config.js allows that host, and the login cookie isn't Secure outside production.

Dependabot

We have added an example dependabot configuration file to the repository. You can enable it by renaming the .github/example.dependabot.yml to .github/dependabot.yml

SonarCloud

Instructions for setting up SonarCloud can be found in sonar-project.properties.

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.