The trailer registration service to be consumed by DVLA to save trailer registration certificates. More details related to class diagrams and detailed description of the service and the database is here.
The project runs on node 10.x with typescript and serverless framework. For further details about project dependencies, please refer to the package.json file.
nvm is used to managed node versions and configuration explicitly done per project using an .npmrc file. You may need to install dynamoDB as well using the following command:
node_modules/.bin/sls dynamodb install
Please refer to the the docs for the API specification and samples of postman requests.
Further details about this micro service.
Once the dependencies are installed, you will be required to rename the /config/env.example file to .env.local as we use dotenv files for configuration for local local development for example. Further information about variables and environment variables with serverless.
Please note that serverless framework is only used to develop locally and mock API Gateway.
The application runs on port :3020 by default when no stage is provided.
The service has local environmental variables (please see env placeholder file) set locally however should we wish to further extend the service, the environmental variables will need to be ported over to the CI/CD pipeline which currently uses the following environmental variables: BRANCH and BUCKET.
We use NODE_ENV environment variable to set multi-stage builds (region, stages) with the help of dotenv through npm scripts to load the relevant .env.<NODE_ENV> file from ./config folder into the serverless.yml file as we don't rely on serverless for deployment.
If no NODE_ENV value is provided when running the scripts, it will default its NODE_ENV value to 'development' with the .env.development config file.
The defaulted values for 'stage' and 'region' are 'local'. Please refer to the values provided in the serverless.yml file.
The following values can be provided when running the scripts with NODE_ENV:
// ./config/.env.<NODE_ENV> files
'local'; // used for local development
'development'; // used development staging should we wish to require external services
'test'; // used during test scripts where local services, mocks can be used in conjonction/** Running serverless offline as an example for a specific stage - 'local'.
* Stage 'local' will be injected in the serverless.yml
**/
NODE_ENV=local serverless offlineFurther details about environment setup can be found in the provided documentation and env.example file.
All secrets the secrets are will stored in AWS Secrets Manager.
The following scripts are available, for further information please refer to the project package.json file:
- start:
npm start- launch serverless offline service - dev:
npm run dev- run in parallel the service and unit tests in--watchmode with live reload. - test:
npm t- execute the unit test suite - build:
npm run build- bundle the project for production - production build:
npm run build:production- generate the project with bundled libraries, minified, concatenated code
Serverless-offline with webpack is used to run the project locally. Please use npm run dev script to do so. Go to http://localhost:3001/local/version to confirm that everything has loaded correctly, you should see that the version is the same as the version in the package.json
The below routes are available as default routes from this scaffolding
(GET) http://localhost:3001/local/version
# We enable proxying so that APIG can be configured with any parent routes
# The app router is mounted on '/trailers' which will define the beginning of our valid routes in the service
(POST) http://localhost:3001/local/*/trailers/Serverless can invoke lambda functions locally which provide a close experience to the real service if you decide not use the offline mode. events and paths can be found under /local folder.
For further details using lambda locally please refer to the serverless documentation.
Existing configuration to debug the running service has been made available for vscode, please refer to .vscode/launch.json file. Serverless offline will be available on port :4000. 2 jest configurations are also provided which will allow to run a test or multiple tests.
Should you wish to change the ports when debugging, please change the config args accordingly.
For further information about debugging, please refer to the following documentation:
json-serverless has been added to the repository should we wish to mock external services during development and can be used in conjunction with the test environment.
Jest is used for unit testing. Please refer to the Jest documentation for further details.
To be added and customised depending on needs, supertest is used but we could be looking at other packages such as nock, ts-mockito, typemoq, wiremock, etc.. or testing (pactjs, hoverfly, mockserver, etc..)
Releases (tag, release notes, changelog, github release, assets) are automatically managed by semantic-release and when pushing (or merging) to develop branch which is protected. semver convention is followed.
Please be familiar with conventional commit as described in the Contributing section below.
Default preset used is angular for conventional commits, please see the angular conventions.
The <type> 'breaking' in the commit message will trigger a major version bump as well as any of the following text contained in the commit body: "BREAKING CHANGE", "BREAKING CHANGES", "BREAKING_CHANGES", "BREAKING", "BREAKING_CHANGE". Please refer to the .releaserc.json file for the full configuration.
The script npm run release will automatically trigger the release in CI. To manually test the release the following flags ---dry-run --no-ci - can be passed to the release script.
Publishing and artifacts are managed separately by the pipeline.
To facilitate the standardisation of the code, a few helpers and tools have been adopted for this repository.
The projects has multiple hooks configured using husky which will execute the following scripts: audit, lint, build, test and format your code with eslint and prettier.
You will be required to install git-secrets (brew approach is recommended) and DVSA repo-security-scanner that runs against your git log history to find accidentally committed passwords, private keys.
We follow the conventional commit format when we commit code to the repository and follow the angular convention.
The type is mandatory and must be all lowercase. The scope of your commit remain is also mandatory, it must include your ticket number and be all lowercase. The format for the ticket number can be set in the commitlint.config.js file.
// Please see /commitlint.config.js for customised format
type(scope?): subject
// examples
'chore(cvsb-1234): my commit msg' // pass
'CHORE(cvsb-1234): my commit msg' // will failDomain Drive Design diagram with Interfaces, Application, Domain layers and Infrastructure across the layers.
The code uses eslint, typescript clean code standards as well as sonarqube for static analysis. SonarQube is available locally, please follow the instructions below if you wish to run the service locally (brew is the preferred approach):
-
Brew:
- Install sonarqube using brew
- Change
sonar.host.urlto point to localhost, by default, sonar runs onhttp://localhost:9000 - run the sonar server
sonar start, then perform your analysisnpm run sonar-scanner
-
Manual:
- Add sonar-scanner in environment variables in your _profile file add the line:
export PATH=<PATH_TO_SONAR_SCANNER>/sonar-scanner-3.3.0.1492-macosx/bin:$PATH - Start the SonarQube server:
cd <PATH_TO_SONARQUBE_SERVER>/bin/macosx-universal-64 ./sonar.sh start - In the microservice folder run the command:
npm run sonar-scanner
- Add sonar-scanner in environment variables in your _profile file add the line: