Beacons registration service

The Beacons registration service enables:

• 406Mhz beacon owners to register their details with the Maritime & Coastguard Agency
• Search and rescue Mission Control Centres to retrieve information about beacons during distress signal activations

It comprises three applications:

1. A public-facing frontend that uses NextJS and the [GOV.UK Design System] (https://design-system.service.gov.uk/).
   • Source code is in the webapp/ directory.
   • Application specific documentation is in the README.
2. An API that uses Spring Boot, Postgres and OpenSearch.
   • Source code is in the service/ directory.
   • Application specific documentation is in the README.
3. A backoffice single-page application (SPA) that uses React to allow users in MCA to query and perform operations on beacon registrations.
   • Source code is in service/src/main/backoffice.
   • The SPA is served by Spring Boot.
   • Application specific documentation is in the README.

Testing

Application specific tests are covered in the READMEs linked to above.

If you are working towards a release, look at the end-to-end and smoke test documentation.

Known issues and resolution for Unit, Integration and End-to-end testing are documented in the tests README.md file.

Architecture

Infrastructure-as-code remains the single source-of-truth for Beacons infrastructure! Always check terraform/ if unsure.

Local development

Before you start...

• Make sure you have the required versions of things installed

  • Install brew onto your laptop if you are using a Mac.
  • Install mise-en-place
  • Install Podman and podman-compose with brew install podman podman-compose, then create its VM with podman machine init --memory 4096 && podman machine start. You don't need this if you use ./scripts/dev.sh, which runs Podman inside its own VM.
  • See the .tool-versions if you want to manage them some other way.

• Copy webapp/.env.example as webapp/.env.local and populate it with the contents of the "/beacons/dev/webapp/env-local" secure note in AWS Parameter Store.

• Get the Microsoft Graph secrets into your environment variables from "/beacons/dev/microsoft-graph" from AWS Parameter Store to your terminal.

  • Please use direnv to manage this.
  • Save the .envrc.example file in the root of the repository as .envrc and populate the values with what's in "/beacons/dev/microsoft-graph" in AWS Parameter Store

• Install all the things, setup commit hooks etc.

  • # From the root of this repository
    make setup

• Start up the applications in development mode, with backing services

  • # From the root of this repository≠
    make serve

Local development without Azure

If you don't have the Azure and AWS secrets above, or want to work offline, you can run everything with a single local user instead.

To run it all in a Linux VM, with Homebrew as the only thing you install on your Mac, run ./scripts/dev.sh. It creates the VM, installs everything inside it and serves the app; run it with no arguments for the list of commands. node_modules is kept inside the VM, so install on your Mac too if you want your editor to resolve imports. To run natively instead:

1. Set BEACONS_LOCAL_AUTH=true in your .envrc (see .envrc.example) and run direnv allow.
2. Optionally, to change the defaults:
   • copy webapp/.env.local-auth.example as webapp/.env.local-auth for the webapp's settings, which need nothing from AWS. Without it, the example file is used.
   • export LOCAL_AUTH_EMAIL, LOCAL_AUTH_PASSWORD or LOCAL_AUTH_ROLES in your .envrc to change the local user's email, password or Backoffice roles.
3. make serve, then sign in to the webapp with dev@beacons.local / password. The Backoffice signs you in as the same user automatically.

Each mode uses its own env files, so you can switch by changing the flag and restarting make serve.

This is for local development only. Deployed environments run the default,migration Spring profiles (see terraform/*.tfvars) and never set BEACONS_LOCAL_AUTH. The service refuses to start if localauth is combined with default or migration, or runs without dev.

Infrastructure-as-code

The Terraform directory contains the Terraform code for managing the infrastructure for the Beacons registration service.

Deployment

Automated testing, building and deployment is performed using GitHub Actions with configuration held in .github/workflows.

Development environment

A build and deployment to the development environment is triggered on each push to main. Docker images are tagged with the hash of the triggering commit and published to AWS Elastic Container Registry. Images built and deployed to for the development environment are ephemeral and not used anywhere else.

Staging environment

Creating a pre-release triggers a versioned deployment to the staging environment of code at the HEAD of the main branch. Docker images are tagged with the version tag of the release. Version tags must match the pattern v*.*.

Production environment

Changing the status of a pre-release to release triggers a deployment to production of the images that were created for the staging environment. Environment protection is applied to the production environment such that another member of the development team is prompted to approve deployments to production.

Manual scenario testing that must be performed before and after each release is documented in tests/.

Architectural Decision Records (ADRs)

We use ADRs to document design choices that address functional and non-functional requirements that are architecturally significant to the Beacons Registration project. Please see this record for how and when to document ADRs for the project.

Secrets

Secrets are set in the Repository and injected during deployment.

License

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.