generated from ministryofjustice/hmpps-template-kotlin
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update readMe to include setup information (#25)
* update readMe to include setup information * fix formatting * update packagename in authUserRepo
- Loading branch information
1 parent
bb3346d
commit 105757c
Showing
5 changed files
with
56 additions
and
108 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,131 +1,79 @@ | ||
# hmpps-template-kotlin | ||
# Find and Refer an Intervention Service | ||
|
||
[![repo standards badge](https://img.shields.io/badge/endpoint.svg?&style=flat&logo=github&url=https%3A%2F%2Foperations-engineering-reports.cloud-platform.service.justice.gov.uk%2Fapi%2Fv1%2Fcompliant_public_repositories%2Fhmpps-template-kotlin)](https://operations-engineering-reports.cloud-platform.service.justice.gov.uk/public-report/hmpps-template-kotlin "Link to report") | ||
[![CircleCI](https://circleci.com/gh/ministryofjustice/hmpps-template-kotlin/tree/main.svg?style=svg)](https://circleci.com/gh/ministryofjustice/hmpps-template-kotlin) | ||
[![Docker Repository on Quay](https://img.shields.io/badge/quay.io-repository-2496ED.svg?logo=docker)](https://quay.io/repository/hmpps/hmpps-template-kotlin) | ||
[![API docs](https://img.shields.io/badge/API_docs_-view-85EA2D.svg?logo=swagger)](https://hmpps-template-kotlin-dev.hmpps.service.justice.gov.uk/webjars/swagger-ui/index.html?configUrl=/v3/api-docs) | ||
|
||
Template github repo used for new Kotlin based projects. | ||
This repository contains the service code for the `Find and Refer an Intervention service`. | ||
|
||
# Instructions | ||
## Required software | ||
|
||
If this is a HMPPS project then the project will be created as part of bootstrapping - | ||
see [dps-project-bootstrap](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. | ||
Most software can be installed using [homebrew](https://brew.sh/). | ||
|
||
This project is community managed by the mojdt `#kotlin-dev` slack channel. | ||
Please raise any questions or queries there. Contributions welcome! | ||
* Docker | ||
* Java SDK (OpenJDK 21) | ||
|
||
Our security policy is located [here](https://github.com/ministryofjustice/hmpps-template-kotlin/security/policy). | ||
|
||
## Creating a Cloud Platform namespace | ||
|
||
When deploying to a new namespace, you may wish to use the | ||
[templates project namespace](https://github.com/ministryofjustice/cloud-platform-environments/tree/main/namespaces/live.cloud-platform.service.justice.gov.uk/hmpps-templates-dev) | ||
as the basis for your new namespace. This namespace contains both the kotlin and typescript template projects, which | ||
is the usual way that projects are setup. | ||
|
||
Copy this folder and update all the existing namespace references. If you only need the kotlin configuration then remove | ||
all typescript references and remove the elasticache configuration. Submit a PR to the Cloud Platform team in | ||
#ask-cloud-platform. Further instructions from the Cloud Platform team can be found in | ||
the [Cloud Platform User Guide](https://user-guide.cloud-platform.service.justice.gov.uk/#cloud-platform-user-guide) | ||
|
||
## Renaming from HMPPS Template Kotlin - 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> | ||
|
||
The script takes six arguments: | ||
|
||
### New project name | ||
|
||
This should start with `hmpps-` e.g. `hmpps-prison-visits` so that it can be easily distinguished in github from | ||
other departments projects. Try to avoid using abbreviations so that others can understand easily what your project is. | ||
|
||
### Slack channel for release notifications | ||
|
||
By default, release notifications are only enabled for production. The circleci configuration can be amended to send | ||
release notifications for deployments to other environments if required. Note that if the configuration is amended, | ||
the slack channel should then be amended to your own team's channel as `dps-releases` is strictly for production release | ||
notifications. If the slack channel is set to something other than `dps-releases`, production release notifications | ||
will still automatically go to `dps-releases` as well. This is configured by `releases-slack-channel` in | ||
`.circleci/config.yml`. | ||
|
||
### Slack channel for pipeline security notifications | ||
|
||
Ths channel should be specific to your team and is for daily / weekly security scanning job results. It is your team's | ||
responsibility to keep up-to-date with security issues and update your application so that these jobs pass. You will | ||
only be notified if the jobs fail. The scan results can always be found in circleci for your project. This is | ||
configured by `alerts-slack-channel` in `.circleci/config.yml`. | ||
|
||
### Non production kubernetes alerts | ||
|
||
By default Prometheus alerts are created in the application namespaces to monitor your application e.g. if your | ||
application is crash looping, there are a significant number of errors from the ingress. Since Prometheus runs in | ||
cloud platform AlertManager needs to be setup first with your channel. Please see | ||
[Create your own custom alerts](https://user-guide.cloud-platform.service.justice.gov.uk/documentation/monitoring-an-app/how-to-create-alarms.html) | ||
in the Cloud Platform user guide. Once that is setup then the `custom severity label` can be used for | ||
`alertSeverity` in the `helm_deploy/values-*.yaml` configuration. | ||
|
||
Normally it is worth setting up two separate labels and therefore two separate slack channels - one for your production | ||
alerts and one for your non-production alerts. Using the same channel can mean that production alerts are sometimes | ||
lost within non-production issues. | ||
## Running the application locally | ||
|
||
### Production kubernetes alerts | ||
The application comes with a `local` spring profile that includes default settings for running locally. This is not | ||
necessary when deploying to kubernetes as these values are included in the helm configuration templates - | ||
e.g. `values-dev.yaml`. This run configuration is included in the | ||
project [local run configuration](./.run/Local.run.xml) | ||
and can be accessed using the run options in the top right of the window in IntelliJ. | ||
|
||
This is the severity label for production, determined by the `custom severity label`. See the above | ||
#non-production-kubernetes-alerts for more information. This is configured in `helm_deploy/values-prod.yaml`. | ||
There is also a `docker-compose.yml` that can be used to run a local instance of the template in docker and also an | ||
instance of HMPPS Auth. | ||
|
||
### Product ID | ||
Run the following command to pull the relevant dependencies for the project. | ||
|
||
This is so that we can link a component to a product and thus provide team and product information in the Developer | ||
Portal. Refer to the developer portal at https://developer-portal.hmpps.service.justice.gov.uk/products to find your | ||
product id. This is configured in `helm_deploy/<project_name>/values.yaml`. | ||
```bash | ||
docker-compose pull | ||
``` | ||
|
||
## Manually branding from template app | ||
and then the following command to run the containers. | ||
|
||
Run the `rename-project.bash` without any arguments. This will prompt for the six required parameters and create a PR. | ||
The script requires a recent version of `bash` to be installed, as well as GNU `sed` in the path. | ||
```bash | ||
docker-compose up | ||
``` | ||
|
||
## TODOs and Examples | ||
can optionally be run in detached mode in order to retain terminal use | ||
|
||
We have tried to provide some examples of best practice in the application - so there are lots of TODOs in the code | ||
where changes are required to meet your requirements. There is an `ExampleResource` that includes best practice and also | ||
serve as spring security examples. The template typescript project has a demonstration that calls this endpoint as well. | ||
```bash | ||
docker-compose up -d | ||
``` | ||
|
||
For the demonstration, rather than introducing a dependency on a different service, this application calls out to | ||
itself. This is only to show a service calling out to another service and is certainly not recommended! | ||
### Connecting to local database | ||
|
||
## Running the application locally | ||
The service uses a postgres database alongside flyaway migrations to create and populate the database. To connect to the | ||
database locally in your preferred database | ||
client ([IntelliJ Ultimate](https://www.jetbrains.com/help/idea/database-tool-window.html), [Dbeaver](https://dbeaver.io/), | ||
[Pgadmin](https://www.pgadmin.org/), etc). | ||
|
||
The application comes with a `dev` spring profile that includes default settings for running locally. This is not | ||
necessary when deploying to kubernetes as these values are included in the helm configuration templates - | ||
e.g. `values-dev.yaml`. | ||
Create new connection using local database credentials; | ||
|
||
There is also a `docker-compose.yml` that can be used to run a local instance of the template in docker and also an | ||
instance of HMPPS Auth (required if your service calls out to other services using a token). | ||
| Variable | Value | | ||
|----------|----------| | ||
| Port | 5432 | | ||
| Username | postgres | | ||
| Password | password | | ||
|
||
```bash | ||
docker compose pull && docker compose up | ||
``` | ||
### Authorization | ||
|
||
will build the application and run it and HMPPS Auth within a local docker instance. | ||
The service uses an Oauth 2.0 setup managed through the Hmpps Auth project. To call any endpoints locally a bearer token | ||
must be generated. This can be done through calling the auth endpoint in the Hmpps-auth service. | ||
|
||
### Running the application in Intellij | ||
| Variable | Value | | ||
|------------------|-----------------------------------------| | ||
| Grant type | Client credentials | | ||
| Access token URL | http://hmpps-auth:8090/auth/oauth/token | | ||
| Client ID | ----- | | ||
| Client Secret | ----- | | ||
| Scope | Read | | ||
|
||
```bash | ||
docker compose pull && docker compose up --scale hmpps-template-kotlin=0 | ||
``` | ||
For Client ID and Secret refer to the relevant credentials for the Find and Refer Project. | ||
|
||
will just start a docker instance of HMPPS Auth. The application should then be started with a `dev` active profile | ||
in Intellij. | ||
## Troubleshooting | ||
|
||
For any issues please reach out to the Find and Refer Interventions team in | ||
slack [#find-refer-interventions-team](https://moj.enterprise.slack.com/archives/C06MPNK0AD6) |
2 changes: 1 addition & 1 deletion
2
.../justice/digital/hmpps/findandreferanintervention/authorization/ClientApiAccessChecker.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
4 changes: 2 additions & 2 deletions
4
...otlin/uk/gov/justice/digital/hmpps/findandreferanintervention/authorization/UserMapper.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
.../uk/gov/justice/digital/hmpps/findandreferanintervention/authorization/UserTypeChecker.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
2 changes: 1 addition & 1 deletion
2
...gov/justice/digital/hmpps/findandreferanintervention/jpa/repository/AuthUserRepository.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters