A2J ERV wrapper

Java SpringBoot service that handles erv for a2j.

Prerequisites

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

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:

brew install lefthook node talisman

Getting started

To get started with development, make a copy of the local config:

cp src/main/resources/application-local.yaml.example src/main/resources/application-local.yaml

You'll also need to run spring with the local profile (how to do that depends on your dev setup).

Replace dummy config

The checked in dummy configuration gets you started. However if you want to use fit-connect properly, you need to register at the fitko self service portal and create:

• a sender client (client for Onlinedienst),
• a subscriber client (client for Verwaltungssystem, you can use this tool to create the keys),
• a destination (Zustellpunkt).

Use these to replace the ids and secrets in your application-local.yaml.

Generate sources for EGVP SOAP service

enable wsimport task in build.gradle.kts by setting

register("wsimport") {
        enabled = true
        ...

Place the webservice wsdl into the resources folder

/src/main/resources/EGVP-WebService.xml

and run

./gradlew clean build

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

Java source code formatting must conform to the Google Java Style. Consistent formatting, for Java as well as various other types of source code, is being enforced via Spotless.

Check formatting:

./gradlew spotlessCheck

Autoformat sources:

./gradlew spotlessApply

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.

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/a2j-erv-wrapper:$(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/a2j-erv-wrapper

Container images in the registry are signed with keyless signatures.

To verify an image:

cosign verify "ghcr.io/digitalservicebund/a2j-erv-wrapper:$(git log -1 origin/main --format='%H')" --certificate-identity="https://github.com/digitalservicebund/a2j-erv-wrapper/.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:

export CONTAINER_REGISTRY=ghcr.io
export CONTAINER_IMAGE_NAME=digitalservicebund/a2j-erv-wrapper
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/a2j-erv-wrapper:$(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/a2j-erv-wrapper: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 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:

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

Contributing

🇬🇧 Everyone is welcome to contribute the development of the a2j-erv-wrapper. 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.

🇩🇪 Jede:r ist herzlich eingeladen, die Entwicklung des a2j-erv-wrapper 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.

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.