btms-portal-frontend

The BTMS Portal Frontend provides search for DEFRA Import Notifications (IPAFFS) and HMRC Customs Declarations (CDS) showing the relationships between them.

• Prerequisites
• Local development
  • Setup
  • Development
  • Production
  • Npm scripts
  • Authentication
  • Update dependencies
  • Environment variables
  • Formatting
    • Windows Prettier issue
• Server-side caching
• Redis
• Docker
  • Development image
  • Production image
  • Docker Compose
  • Dependabot
  • SonarCloud
• Licence
  • About the licence

Prerequisites

• Node.js >= v22
• npm >= v10.5.1 (installed with Node.js)
• Docker

You may find it easier to manage Node.js versions using a version manager such as nvm or n. From within the project folder you can then either run nvm use or n auto to install the required version.

Local development

Setup

Install application dependencies:

npm install

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

Authentication

For local authentication, we use the cdp-defra-id-stub. If you run this as within Docker you will also get an instance of Redis, which can be used for session caching. You should also delete the reference to localstack within the stubs compose.yml file.

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

Environment variables

For local development some environment variables can to be added to a .env.local file at the root of the project, (this will be ignored by Git). These will then be picked up by Convict in src/config/config.js when you start the app using npm run dev

Variables needed for local development

Ask a member of the team to provide you with values.

name	purpose
BTMS_API_BASE_URL	Search queries use this API for results
BTMS_API_USERNAME	Username for calls to search API
BTMS_API_PASSWORD	Password for calls to search API
BTMS_REPORTING_API_BASE_URL	Reporting section use this API for reporting data
BTMS_REPORTING_API_USERNAME	Username for calls to reporting API
BTMS_REPORTING_API_PASSWORD	Password for calls to reporting API
BTMS_IMPORTS_PROCESSOR_BASE_URL	Specify the base URL to retrieve raw IPAFFS/CDS messages
BTMS_IMPORTS_PROCESSOR_USERNAME	Auth username for the imports processor endpoint(s)
BTMS_IMPORTS_PROCESSOR_PASSWORD	Auth password for the imports processor endpoint(s)
AUTH_DEFRA_ID_OIDC_CONFIGURATION_URL	Configuration URL for DefraId
AUTH_DEFRA_ID_CLIENT_SECRET	Secret for DefraId
AUTH_DEFRA_ID_ORGANISATIONS	List of DefraId organisations with access to the service
AUTH_DEFRA_ID_ACCOUNT_MANAGEMENT_URL	DefraId (Gov Gateway) account management URL
AUTH_ENTRA_ID_OIDC_CONFIGURATION_URL	Configuration URL for EntraId
AUTH_ENTRA_ID_CLIENT_ID	Client ID for EntraId
AUTH_ENTRA_ID_CLIENT_SECRET	Secret for EntraId
SESSION_CACHE_ENGINE	Location of session storage ('redis' or 'memory')
IPAFFS_URL	URL for links out to IPAFFS from notifications
TZ	Europe/London

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

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 access Redis keys that are namespaced using the service name (e.g. 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 Redis be setting SESSION_CACHE_ENGINE=memory.

Docker

Development image

Build:

docker build --target development --no-cache --tag btms-portal-frontend:development .

Run:

docker run -p 3000:3000 btms-portal-frontend:development

Production image

Build:

docker build --no-cache --tag btms-portal-frontend .

Run:

docker run -p 3000:3000 btms-portal-frontend

Docker Compose

A local environment with:

• Localstack for AWS services (S3, SQS)
• Redis
• MongoDB
• This service
• A commented out backend example

docker compose up --build -d

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.