This is the repository for the GAP projects apply for a grant admin journey backend. The backend is a spring boot API which communicates with a PostgreSQL database, a SQS queue, S3 buckets and Contentful.
The Apply for a Grant admin backend is a maven project. This means to run the app locally you must have Maven installed and setup on your machine. For this app's other dependencies, please see the dependencies section. Once all dependencies and Maven is set up, you can start the app locally by running a simple maven command:
mvn spring-boot:run
Since adding Spring Security, you must be authenticated to access any of the endpoints (excluding /health
and /login).
Before you can make your requests via Postman or the FE, you will to authenticate via login endpoint to create a
session. Login requires a valid JWT signed by COLA that has not expired provided in an Authorization header as a Bearer
token.
For local development purposes, there are three properties in application.properties that you can set to log in as a
given user without a valid JWT.
By setting debug.ignore-jwt equal to true, the app will no longer look for a JWT and will instead log you in as an
admin with the following two properties (grantAdminId and funderId). These should match with an admin that already
exists in the database.
debug.ignore-jwt=false
debug.grant-admin-id=1
debug.funder-id=1
Please be careful not to commit any local changes you make to these properties
Tests can typically be run through your IDE, or through maven. Here are some handy Maven commands to get you started with testing this app.
Run all tests:
mvn test
Run a single test class:
mvn Test -Dtest=className
Run a single test:
mvn Test -Dtest=className#methodName
flowchart TD
GrantAdmin["Grant Admin
[User]
A person who is responsible for creating grant adverts,\napplication forms and evaluating submissions"]
GrantAdminPortal["Admin Website
[WebSite]
UI for Grant Admin functions"]
Cola["Cabinet Office Login Authentication
[Software Service]
Provides user authentication with Cognito"]
Cognito["AWS Cognito
[Software Service]
Holds details about user login credentials"]
GrantAdmin -- "uses\n[HTTPS]" ---> Cola
Cola -- "authenticates via\n[HTTPS]" --> Cognito
Cola -- "sends email\n[HTTPS]" --> GovNotify
GrantAdvertController["Advert Builder Service
[Software Service]
Provides access to data\nrelated to Grant Adverts"]
SchemeController["Grant Scheme Service
[Software Service]
Provides access to data\nrelated to Grant Schemes"]
ApplicationFormController["Application Form Service
[Software Service]
Provides access to data\nrelated to Grant Applications"]
ApplicationFormQuestionsController["Form Questions Service
[Software Service]
Provides access to data\nrelated to Grant Application forms"]
ApplicationFormSectionsController["Form Sections Service
[Software Service]
Provides access to data\nrelated to Grant Application forms"]
SubmissionsController["Submission Service
[Software Service]
Provides access to data\nrelated to Grant Submissions"]
UploadS3["Attachment Uploads
[AWS S3]
Location to host\nuploaded attachments"]
GrantExportController["Export Service
[Software Service]
Handles the export of Submissions"]
GrantAdmin -- "uses\n[HTTPS]" --> GrantAdminPortal
GrantAdminPortal -- "provides access to\n[HTTPS]" ---> AdminService
GrantAdminPortal <-- "uses for authentication\n[HTTPS]" --> Cola
subgraph AdminService[gap-apply-admin-backend]
GrantExportController
GrantAdvertController
SchemeController
ApplicationFormController
ApplicationFormQuestionsController
ApplicationFormSectionsController
SubmissionsController
end
GapDatabase[(GAP\nDatabase\nPostgreSQL)]
ExportQueue["Export Queue
[AWS SQS]"]
ExportLambda["Submission Export
[AWS Lambda]"]
ExportS3["S3 Export
[AWS S3]
Location to host\nexported submission data"]
GovNotify["GOV.Notify
[Software Service]
Provides templated emails"]
GrantAdvertController <-- "reads and writes\n[JDBC]" ---> GapDatabase
SchemeController <-- "reads and writes\n[JDBC]" ---> GapDatabase
ApplicationFormController <-- "reads and writes\n[JDBC]" ---> GapDatabase
ApplicationFormQuestionsController <-- "reads and writes\n[JDBC]" ---> GapDatabase
ApplicationFormSectionsController <-- "reads and writes\n[JDBC]" ---> GapDatabase
SubmissionsController <-- "reads and writes\n[JDBC]" ---> GapDatabase
SubmissionsController -- "writes files\n[HTTPS]" --> UploadS3
GrantExportController -- "writes events\n[HTTPS]" --> ExportQueue
GrantExportController <-- "reads and writes\n[JDBC]]" ---> GapDatabase
ExportQueue -- "reads events\n[SQS]" --> ExportLambda
ExportLambda -- "sends emails\n[HTTPS]" --> GovNotify
ExportLambda -- "writes files\n[HTTPS]" --> ExportS3
ExportLambda <-- "reads and writes\n[JDBC]" ----> GapDatabase
classDef focusSystem fill:#1168bd,stroke:#0b4884,color:#ffffff
classDef govService fill:#666,stroke:#0b4884,color:#ffffff
classDef awsFunction fill:#FF9900,stroke:#252F3E,color:#252F3E
class AdminService focusSystem
class Cola,GovNotify govService
class Cognito,UploadS3,ExportQueue,ExportS3,GapDatabase awsFunction
gap-apply-admin-backend now uses PostgreSQL as its primary data store. This mean to start the app locally you must first have a local postgreSQL database running with the correct properties added within application.properties.
PostgreSQL and pgAdmin can be easily setup easily through the use of docker compose. A suitable docker-compose.yml file
can be found at /src/main/resources/Docker.
A local instance of PostgreSQL and pgAdmin can be started by navigation to /src/main/resources/Docker within a terminal
and running:
docker compose up -d
With the above containers running, pgAdmin can be found at http://localhost:5050. This presents you with a login page, the credentials for which can be found in the docker compose file but the default is:
- email: [email protected]
- password: root
Once in, follow the below steps to connect to your local DB:
- Right click on servers, then register > server
- Give a name to your new server group
- Click on connection tab
- Set Host name/address to the postgres container name
- The default within the file is pg-gap-admin
- Set username and password to the credentials found within the docker compose file
- The default credentials within the file are: root
To maintain database synchronisation across environments, we are using Flyway to handle database setup/migration.
Spring will automatically run new migrations on start up, but this can also be done manually through maven.
Credentials needed by Flyway are stored in pom.xml, within Flyway's plugin definition.
SQL scripts are stored in src/main/resource/db/migration and to run the migration setup
using Maven run the following command:
mvn flyway:migrate
This will run all scripts in the directory listed above. Migration history is automatically stored in a table called
flyway_schema_history. This means that whenever a new script is added to the directory, and you run the Maven migration
command again, it will only run the new script. Therefore, once the database is established and deployed
in long-term environments, when making changes to schemas, you do not modify existing scripts that have already
been migrated - you must add new scripts. A more eloquent explanation and example is provided
here.
For test data, in the directory src/main/resource/db/ there is a file named testdata.sql which you can use to
manually populate your database for development purposes. You can use PGAdmin to run the contents of the script.
Please do not add test data to the SQL scripts used by Flyway, as these are intended to be used by all
environments (incl. production).
To enforce consistent formatting across IDEs, we are using Spring's own Java formatting plugin. To run the formatter, you can run:
mvn spring-javaformat:apply
Or to validate the codebase against the formatter, you can run:
mvn spring-javaformat:validate
This validate step is included in Maven build phase, so if the code does not pass validation, the build will fail. There are plugins you can install for IntelliJ and Eclipse which allows the IDE reformat to utilise the same rules, hopefully keeping everyone in sync.
NOTE: It's recommended you configure your IDE to reformat your code automatically, either when you save a file or make a commit.
- Download the plugin from here (it can't be installed through the plugin Marketplace).
- Go to IntelliJ's settings (preferences) and find the Plugins section.
- Along the top of the Plugins section (where it says Marketplace and Installed), click the cog and select Install Plugin from Disk.
- Select the .jar you downloaded in step 1
- Download the plugin from here (it can't be installed through the Eclipse Marketplace).
- Navigate to Help > Install New Software.
- On this window, click the Add button along the right-hand side.
- In the next window, click Archive and select the zip file you downloaded in step 1.
- You may be asked to install an unauthorised plugin, due to it not coming directly from the Marketplace. Tick the plugin and click accept.
- In Eclipse's settings (preferences), navigate to Java > Code Style > Formatter.
- Change the formatter implementation to
Spring (spaces).
To use the /submissions/export-all endpoint that interacts with AWS SQS, you will need to add AWS credentials to the
following file: ~/.aws/credentials
The credentials file requires the following entries:
[default]
aws_access_key_id = {your access key - if you don't have any, leave blank}
aws_secret_access_key = {your secret key - if you don't have any, leave blank}
The config file requires the following entry:
[default]
region = eu-west-2By default, your own credentials will not work unless you explicitly give them permission on the affiliated SQS queue.
The service account has access to send messages to SQS, so it is recommended to use that profile (it's already set
in application.properties). If you don't have service account credentials, speak to Chris Steele about details of the
service account for this purpose.