di-authentication-frontend

Clone the repo

Clone this repo to your local machine

git@github.com:alphagov/di-authentication-frontend.git

Clones the repository to the <your_folder_name directory.

Running the app

There are two different ways to run the app on a local machine:

• Everything running in Docker
• The frontend app running in a local node instance, with supporting services running in Docker

Before you can run the frontend app against the backend you will need to configure some environment variables.

Set the Environment variables

You will need a .env file. this can be generated by:

1. Log into the VPN
2. Run scripts/create-env-file.sh ${target_environment}, where ${target_environment} is the environment you wish to use for OIDC etc. build|sandpit|authdev# are supported.

If things stop working in future, this script can be rerun to update the variables sourced from AWS. All non-generated variables may be updated, and changes will persist through reruns.

UI_LOCALES can be used be the stub to request specific locales when authorising. Only 'en' and 'cy' are supported.

Starting all services in Docker

Run one of the following:

docker compose up

./startup.sh

Starting the frontend in node locally outside of Docker

In this case supporting services (redis and stubs) run in Docker but the frontend itself runs outside. Development can be quicker and more responsive if done in this way.

The startup script will do this for you so just run this command:

./startup.sh -l

General guidance on starting the application

When starting for the first time, or after a clean, the frontend will take a few minutes to start as node needs to install all the dependencies.

To find out if the application has started, open a console window on the frontend docker container and view the logs. If the server has started successfully you will see this message Server listening on port 3000. If this does not appear try forcing node to restart by updating one of the .njk files.

If things do not appear to be working it can be a good idea to start with a clean deployment:

yarn clean

Additionaly delete the Docker images for all the frontend services in docker-compose.yml.

There are two stub apps you can use to start a journey.

NB: ports 2000 and 5000 can be set in .env with DOCKER_STUB_DEFAULT_PORT=2000 and DOCKER_STUB_NO_MFA_PORT=5000. If you have changed these values in your .env file, use your value rather than the one stated below.

To start an auth only journey with MFA required ("Cm"), navigate to the stub app on port 2000 http://localhost:2000. This acts like a local client to create a backend session and redirect to the start page.

To start an auth only journey with no MFA ("Cl"), navigate to the stub app on port 5000 http://localhost:5000.

Changes made locally will automatically be deployed after a few seconds. You should check the docker console to check that your changes have been picked up by the restart.

Switching between different Vectors of Trust

You can further tweak the vector of trust (VTR) requested by the stub client on port 5000 (or $DOCKER_STUB_DEFAULT_PORT if modified in .env) by editing docker-compose.yml and changing the VTR environment variable for the di-auth-stub-no-mfa service:

  di-auth-stub-no-mfa:
    build:
      context: .
      dockerfile: Dockerfile-stub
    links:
      - di-auth-frontend
    ports:
      - "${STUB_NO_MFA_PORT:-5000}:${STUB_NO_MFA_PORT:-5000}"
    environment:
      - ENVIRONMENT=${ENVIRONMENT}
      - API_BASE_URL=${API_BASE_URL}
      - FRONTEND_API_BASE_URL=${FRONTEND_API_BASE_URL}
      - TEST_CLIENT_ID=${TEST_CLIENT_ID}
      - STUB_HOSTNAME=${STUB_HOSTNAME}
      - UI_LOCALES=${UI_LOCALES}
      - VTR=["Cl"] <== Edit this line
      - PORT=${STUB_NO_MFA_PORT:-5000}

You can also add an additional service with a different VTR by duplicating the di-auth-stub-no-mfa service, giving it a new name and amending the PORT and VTR environment variables. The ports entry, must reflect the port number in the PORT environment variable. Each service must have a unique port number.

Running the tests

The unit tests have been written with Mocha and Supertest.

If the app is run in a container then the tests are run there too:

docker exec -it di-authentication-frontend_di-auth-frontend /bin/sh

yarn run test:unit

Restarting the app

You can restart the app by re-running the startup.sh script, or restarting docker-compose.

For a clean start run ./startup.sh -c

Pre-flight checks

Before committing or creating a PR it is a good idea to run all checks and tests. The pre-commit script can be used to do this. It runs:

• All pre-commit checks defined in .pre-commit-config.yaml
• The app in Docker
• Unit tests
• Integration tests

Pre-commit checks include applying formatting, so after the script has run you may see files updated with formatting changes. Running pre-commit before every PR ensures that all files in the repo are formatted correctly.

./pre-commit.sh

You may need to install pre-commit for the script to work.

brew install pre-commit

Troubleshooting the local run

General steps to try first

If you're having problems running locally, try these steps first:

• Connect to the VPN
• Run ./shutdown.sh
• Delete your Docker Images (you can do this via Docker Desktop or with docker system prune --all)
• Run ./startup.sh -lc to do a cleanup before a local run
• Because things sometimes don't work first time round, a touch src/server.ts while the server is running might help

Getting past specific errors

`Error: secret option required for sessions`

1. stop the server with ./shutdown.sh
2. run ./startup.sh -l (there's no need for the -c flag)

Other useful yarn commands

Remember to run these commands in the docker container itself.

Documentation

Generate and view documentation of the user journey state machine

yarn dev:render-user-journey-documentation

Development

To run the app in development mode with nodemon watching the files

yarn dev

Starts a nodemon server serving the files from the dist/ directory.

Build

To build the app

yarn build

Start

To run the built app

yarn start

Starts a node server pointing to the entry point found in the build directory.

Unit tests

To run the unit tests

yarn test:unit

Runs all unit tests found in the tests/unit/ directory using mocha.

Integration tests

The application stack must be started before the integration tests can be run, either with frontend running in a docker container or on the local machine (./startup -l). In either case the command to run the integration tests is the same, but the tests usually run faster when frontend is started outside of docker.

In both cases frontend must have started successfully with the message 'Server listening on port 3000' before the tests can be run. If running frontend in a container check the actual container logs in docker desktop to make sure that frontend has started correctly, otherwise the test run will be invalid.

To run the integration tests

REDIS_PORT=6379 REDIS_HOST=localhost yarn test:integration

Install dependencies

To install dependencies, run yarn install

yarn install

Installs the dependencies required to run the application.

Coverage

To get a coverage report

yarn test:coverage

Linting

To run lint checks

yarn lint

Checks if the code conforms the linting standards.