Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@tpmcgowan
tpmcgowan committed Sep 29, 2023
1 parent 8b1e6ff commit 177ba0e
Showing 1 changed file with 36 additions and 63 deletions.
99 changes: 36 additions & 63 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,78 +2,40 @@
[![repo standards badge](https://img.shields.io/badge/dynamic/json?color=blue&style=flat&logo=github&label=MoJ%20Compliant&query=%24.result&url=https%3A%2F%2Foperations-engineering-reports.cloud-platform.service.justice.gov.uk%2Fapi%2Fv1%2Fcompliant_public_repositories%2Fhmpps-book-a-prison-visit-ui)](https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-github-repositories.html#hmpps-book-a-prison-visit-ui "Link to report")
[![CircleCI](https://circleci.com/gh/ministryofjustice/hmpps-book-a-prison-visit-ui/tree/main.svg?style=svg)](https://circleci.com/gh/ministryofjustice/hmpps-book-a-prison-visit-ui)

Template github repo used for new Typescript based projects.
Public facing prison visits booking application.

# Instructions
## Running the app for development
The easiest way to run the app is to use docker compose to run Redis and then launch the app directly with Node.

If this is a HMPPS project then the project will be created as part of bootstrapping -
see https://github.com/ministryofjustice/dps-project-bootstrap. You are able to specify a template application using the `github_template_repo` attribute to clone without the need to manually do this yourself within GitHub.
```bash
docker-compose pull
docker-compose up redis-public-ui -d

This bootstrap is community managed by the mojdt `#typescript` slack channel.
Please raise any questions or queries there. Contributions welcome!
```

Our security policy is located [here](https://github.com/ministryofjustice/hmpps-book-a-prison-visit-ui/security/policy).
Install dependencies using `npm install`, ensuring you are using `node v18.x` and `npm v10.x`

More information about the template project including features can be found [here](https://dsdmoj.atlassian.net/wiki/spaces/NDSS/pages/3488677932/Typescript+template+project).

## Creating a Cloud Platform namespace

When deploying to a new namespace, you may wish to use this template typescript project namespace as the basis for your new namespace:

<https://github.com/ministryofjustice/cloud-platform-environments/tree/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-book-a-prison-visit-ui>

This template namespace includes an AWS elasticache setup - which is required by this template project.

Copy this folder, update all the existing namespace references, and submit a PR to the Cloud Platform team. Further instructions from the Cloud Platform team can be found here: <https://user-guide.cloud-platform.service.justice.gov.uk/#cloud-platform-user-guide>

## Renaming from HMPPS Template Typescript - github Actions

Once the new repository is deployed. Navigate to the repository in github, and select the `Actions` tab.
Click the link to `Enable Actions on this repository`.

Find the Action workflow named: `rename-project-create-pr` and click `Run workflow`. This workflow will
execute the `rename-project.bash` and create Pull Request for you to review. Review the PR and merge.

Note: ideally this workflow would run automatically however due to a recent change github Actions are not
enabled by default on newly created repos. There is no way to enable Actions other then to click the button in the UI.
If this situation changes we will update this project so that the workflow is triggered during the bootstrap project.
Further reading: <https://github.community/t/workflow-isnt-enabled-in-repos-generated-from-template/136421>

## Manually branding from template app
Run the `rename-project.bash` and create a PR.

The rename-project.bash script takes a single argument - the name of the project and calculates from it the project description
It then performs a search and replace and directory renames so the project is ready to be used.

## Ensuring slack notifications are raised correctly

To ensure notifications are routed to the correct slack channels, update the `alerts-slack-channel` and `releases-slack-channel` parameters in `.circle/config.yml` to an appropriate channel.

## Filling in the `productId`

To allow easy identification of an application, the product Id of the overall product should be set in `values.yaml`. The Service Catalogue contains a list of these IDs and is currently in development here https://developer-portal.hmpps.service.justice.gov.uk/products

## Running the app
The easiest way to run the app is to use docker compose to create the service and all dependencies.

`docker-compose pull`

`docker-compose up`

### Dependencies
The app requires:
* hmpps-auth - for authentication
* redis - session store and token caching
Note: Using `nvm` (or [fnm](https://github.com/Schniz/fnm)), run `nvm install --latest-npm` within the repository folder to use the correct version of node, and the latest version of npm. This matches the `engines` config in `package.json` and the CircleCI build config.

### Running the app for development
Using your personal client credentials, create a `.env` local settings file
```bash
REDIS_HOST=localhost
HMPPS_AUTH_URL=https://sign-in-dev.hmpps.service.justice.gov.uk/auth
NODE_ENV=development

To start the main services excluding the example typescript template app:
SYSTEM_CLIENT_ID="<system_client_id>"
SYSTEM_CLIENT_SECRET="<system_client_secret>"

`docker-compose up --scale=app=0`
ORCHESTRATION_API_URL="https://hmpps-manage-prison-visits-orchestration-dev.prison.service.justice.gov.uk"

Install dependencies using `npm install`, ensuring you are using `node v18.x` and `npm v9.x`
GOVUK_ONE_LOGIN_URL=https://oidc.integration.account.gov.uk
GOVUK_ONE_LOGIN_CLIENT_ID="<govuk_one_login_client_id>"
GOVUK_ONE_LOGIN_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
<private key contents>
-----END PRIVATE KEY-----"
```

Note: Using `nvm` (or [fnm](https://github.com/Schniz/fnm)), run `nvm install --latest-npm` within the repository folder to use the correct version of node, and the latest version of npm. This matches the `engines` config in `package.json` and the CircleCI build config.
To get some of these values, you will need to speak to a team member or look within the `hmpps-book-a-prison-visit-ui` and `govuk-one-login` secrets in the `visit-someone-in-prison-frontend-svc-dev` namespace.

And then, to build the assets and start the app with nodemon:

Expand Down Expand Up @@ -106,7 +68,18 @@ Or run tests with the cypress UI:
`npm run int-test-ui`


## Dependency Checks
### Dependency Checks

The template project has implemented some scheduled checks to ensure that key dependencies are kept up to date.
If these are not desired in the cloned project, remove references to `check_outdated` job from `.circleci/config.yml`

## GOV.UK One Login integration
The [GOV.UK One Login](https://www.sign-in.service.gov.uk) service is used to authenticate users. Refer to the [technical documentation](https://docs.sign-in.service.gov.uk) for more details.

When running this application locally or in development environments, the GOV.UK One Login integration environment is used. This is additionally secured by HTTP Basic Auth. Ask a team member for these credentials.

This application has several changes to core files inherited from the HMPPS TypeScript Template app in order to support GOV.UK One Login. These are:

* an additional Kubernetes secret `govuk-one-login` in the namespace to store the private key, etc.
* client and server public/private key pairs (in `./integration_tests/testKeys/`) for integration testing
* a new NPM task (`oidc-wiremock`) and customisations to `start-feature` and `watch-node-feature` that ensure the OIDC Discovery Endpoint mock and a private key is available before the application starts

0 comments on commit 177ba0e

Please sign in to comment.