Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/digitalservicebund/java-application-template

Bootstrap a Java application with Spring WebFlux, Gradle and Continuous Delivery
https://github.com/digitalservicebund/java-application-template

continuous-delivery java

Last synced: 8 days ago
JSON representation

Bootstrap a Java application with Spring WebFlux, Gradle and Continuous Delivery

Awesome Lists containing this project

README 

        
# Java Application Template



[![Pipeline](https://github.com/digitalservicebund/java-application-template/actions/workflows/pipeline.yml/badge.svg)](https://github.com/digitalservicebund/java-application-template/actions/workflows/pipeline.yml)

[![Scan](https://github.com/digitalservicebund/java-application-template/actions/workflows/scan.yml/badge.svg)](https://github.com/digitalservicebund/java-application-template/actions/workflows/scan.yml)

[![Secrets Check](https://github.com/digitalservicebund/java-application-template/actions/workflows/secrets-check.yml/badge.svg)](https://github.com/digitalservicebund/java-application-template/actions/workflows/secrets-check.yml)



Java service built with

the [Spring WebFlux reactive stack](https://docs.spring.io/spring-framework/docs/current/reference/html/web-reactive.html#spring-webflux).



## Prerequisites



Java 21, Docker for building + running the containerized application:



```bash

brew install openjdk@21

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:



```bash

brew install lefthook node talisman

```



## Getting started



**To get started with development run:**



```bash

./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:**



```bash

./gradlew test

```



**To run the integration tests:**



```bash

./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:**



```bash

./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](https://www.archunit.org/getting-started)

for ensuring certain architectural characteristics, for instance making sure that there are no cyclic dependencies.



## Formatting



Java source code formatting must conform to the [Google Java Style](https://google.github.io/styleguide/javaguide.html).

Consistent formatting, for Java as well as various other types of source code, is being enforced

via [Spotless](https://github.com/diffplug/spotless).



**Check formatting:**



```bash

./gradlew spotlessCheck

```



**Autoformat sources:**



```bash

./gradlew spotlessApply

```



## Git hooks



The repo contains a [Lefthook](https://github.com/evilmartians/lefthook/blob/master/docs/full_guide.md) configuration,

providing a Git hooks setup out of the box.



**To install these hooks, run:**



```bash

./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](https://chris.beams.io/posts/git-commit/)

- not accidentally push [secrets and sensitive information](https://thoughtworks.github.io/talisman/)



## 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:**



```bash

SONAR_TOKEN=[sonar-token] ./gradlew sonarqube

```



Go to [https://sonarcloud.io](https://sonarcloud.io/dashboard?id=digitalservicebund_java-application-template)

for the analysis results.



## Container image



Container images running the application are automatically published by the pipeline to

the [GitHub Packages Container registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).



**To run the latest published image:**



```bash

docker run -p8080:8080 "ghcr.io/digitalservicebund/java-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:



```bash

./gradlew bootBuildImage

docker run -p8080:8080 ghcr.io/digitalservicebund/java-application-template

```



Container images in the registry are [signed with keyless signatures](https://github.com/sigstore/cosign/blob/main/KEYLESS.md).



**To verify an image**:



```bash

cosign verify "ghcr.io/digitalservicebund/java-application-template:$(git log -1 origin/main --format='%H')" --certificate-identity="https://github.com/digitalservicebund/java-application-template/.github/workflows/pipeline.yml@refs/heads/main" --certificate-oidc-issuer="https://token.actions.githubusercontent.com"

```



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:**



```bash

export CONTAINER_REGISTRY=ghcr.io

export CONTAINER_IMAGE_NAME=digitalservicebund/java-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:**



```bash

echo [github-token] | docker login ghcr.io -u [github-user] --password-stdin

docker push "ghcr.io/digitalservicebund/java-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](https://github.com/aquasecurity/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:



```bash

brew install aquasecurity/trivy/trivy

```



```bash

./gradlew bootBuildImage

trivy image --severity HIGH,CRITICAL ghcr.io/digitalservicebund/java-application-template:latest

```



As part of the automated vulnerability scanning we are generating a Cosign vulnerability scan record using Trivy,

and then use Cosign to attach an attestation of it to the container image, again

[signed with keyless signatures](https://github.com/sigstore/cosign/blob/main/KEYLESS.md) similar to signing the

container image itself. Using a policy engine in a cluster the vulnerability scan can be verified and for instance

running a container rejected if a scan is not current.



## 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:**



```bash

./gradlew checkLicense

```



## Architecture Decision Records



[Architecture decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)

are kept in the `docs/adr` directory. For adding new records install the [adr-tools](https://github.com/npryce/adr-tools) package:



```bash

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](https://api.slack.com/messaging/webhooks).



## Contributing



🇬🇧

Everyone is welcome to contribute the development of the _java-application-template_. You can contribute by opening pull request,

providing documentation or answering questions or giving feedback. Please always follow the guidelines and our

[Code of Conduct](CODE_OF_CONDUCT.md).



🇩🇪

Jede:r ist herzlich eingeladen, die Entwicklung der _java-application-template_ mitzugestalten. Du kannst einen Beitrag leisten,

indem du Pull-Requests eröffnest, die Dokumentation erweiterst, Fragen beantwortest oder Feedback gibst.

Bitte befolge immer die Richtlinien und unseren [Verhaltenskodex](CODE_OF_CONDUCT_DE.md).



### Contributing code



🇬🇧

Open a pull request with your changes and it will be reviewed by someone from the team. When you submit a pull request,

you declare that you have the right to license your contribution to the DigitalService and the community.

By submitting the patch, you agree that your contributions are licensed under the MIT license.



Please make sure that your changes have been tested before submitting a pull request.



🇩🇪

Nach dem Erstellen eines Pull Requests wird dieser von einer Person aus dem Team überprüft. Wenn du einen Pull Request

einreichst, erklärst du dich damit einverstanden, deinen Beitrag an den DigitalService und die Community zu

lizenzieren. Durch das Einreichen des Patches erklärst du dich damit einverstanden, dass deine Beiträge unter der

MIT-Lizenz lizenziert sind.



Bitte stelle sicher, dass deine Änderungen getestet wurden, bevor du einen Pull Request sendest.