Kotlin Application Template
Kotlin service built with the Spring WebFlux reactive stack.
Prerequisites
Kotlin 1.6 w/ Java 17, Docker for building + running the containerized application:
brew install openjdk@17
brew install --cask docker # or just `brew install docker` if you don't want the Desktop app
For the provided Git hooks you will need:
brew install lefthook node talisman
Getting started
To get started with development run:
./run.sh init
This will replace placeholders in the application template and install a couple of Git hooks.
Tests
The project has distinct unit and integration test sets.
To run just the unit tests:
./gradlew test
To run the integration tests:
./gradlew integrationTest
Note: Running integration tests requires passing unit tests (in Gradle terms: integration tests depend on unit tests), so unit tests are going to be run first. In case there are failing unit tests we won't attempt to continue running any integration tests.
To run integration tests exclusively, without the unit test dependency:
./gradlew integrationTest --exclude-task test
Denoting an integration test is accomplished by using a JUnit 5 tag annotation: @Tag("integration")
.
Furthermore, there is another type of test worth mentioning. We're using ArchUnit for ensuring certain architectural characteristics, for instance making sure that there are no cyclic dependencies.
Formatting & Linting
For linting and formatting Kotlin code ktlint is used.
Consistent formatting for Kotlin, as well as various other types of source code (JSON, Markdown, Yaml, ...), is being enforced via Spotless.
Check formatting:
./gradlew spotlessCheck
Autoformat sources:
./gradlew spotlessApply
IntelliJ IDEA setup
See https://github.com/pinterest/ktlint#-with-intellij-idea
brew install ktlint
ktlint applyToIDEAProject
Git hooks
The repo contains a Lefthook configuration, providing a Git hooks setup out of the box.
To install these hooks, run:
./run.sh init
The hooks are supposed to help you to:
- commit properly formatted source code only (and not break the build otherwise)
- write conventional commit messages
- not accidentally push secrets and sensitive information
Code quality analysis
Continuous code quality analysis is performed in the pipeline upon pushing to trunk; it requires a
token provided as SONAR_TOKEN
repository secret that needs to be obtained from https://sonarcloud.io.
To run the analysis locally:
SONAR_TOKEN=[sonar-token] ./gradlew sonarqube
Go to https://sonarcloud.io for the analysis results.
Container image
Container images running the application are automatically published by the pipeline to the GitHub Packages Container registry.
To run the latest published image:
docker run -p8080:8080 "ghcr.io/digitalservicebund/kotlin-application-template:$(git log -1 origin/main --format='%H')"
The service will be accessible at http://localhost:8080
.
We are using Spring's built-in support for producing an optimized container image:
./gradlew bootBuildImage
docker run -p8080:8080 ghcr.io/digitalservicebund/kotlin-application-template
Container images in the registry are signed with keyless signatures.
To verify an image:
COSIGN_EXPERIMENTAL=1 cosign verify "ghcr.io/digitalservicebund/kotlin-application-template:$(git log -1 origin/main --format='%H')"
If you need to push a new container image to the registry manually there are two ways to do this:
Via built-in Gradle task:
export CONTAINER_REGISTRY=ghcr.io
export CONTAINER_IMAGE_NAME=digitalservicebund/kotlin-application-template
export CONTAINER_IMAGE_VERSION="$(git log -1 --format='%H')"
CONTAINER_REGISTRY_USER=[github-user] CONTAINER_REGISTRY_PASSWORD=[github-token] ./gradlew bootBuildImage --publishImage
Note: Make sure you're using a GitHub token with the necessary write:packages
scope for this to work.
Using Docker:
echo [github-token] | docker login ghcr.io -u [github-user] --password-stdin
docker push "ghcr.io/digitalservicebund/kotlin-application-template:$(git log -1 --format='%H')"
Note: Make sure you're using a GitHub token with the necessary write:packages
scope for this to work.
Vulnerability Scanning
Scanning container images for vulnerabilities is performed with Trivy
as part of the pipeline's build
job, as well as each night for the latest published image in the container
repository.
To run a scan locally:
Install Trivy:
brew install aquasecurity/trivy/trivy
./gradlew bootBuildImage
trivy image --severity HIGH,CRITICAL ghcr.io/digitalservicebund/kotlin-application-template:latest
License Scanning
License scanning is performed as part of the pipeline's build
job. Whenever a production dependency
is being added with a yet unknown license the build is going to fail.
To run a scan locally:
./gradlew checkLicense
Architecture Decision Records
Architecture decisions
are kept in the docs/adr
directory. For adding new records install the adr-tools package:
brew install adr-tools
See https://github.com/npryce/adr-tools regarding usage.
Slack notifications
Opt in to CI posting notifications for failing jobs to a particular Slack channel by setting a repository secret
with the name SLACK_WEBHOOK_URL
, containing a url for Incoming Webhooks.