Kinegram Document Validation Service - Installation Guide

The Kinegram Document Validation Service (DocVal) is provided as a Docker Image.

Docker Registry

$ docker login registry.kurzdigital.com -u <REGISTRY_USER> -p <REGISTRY_PSW>

$ docker pull registry.kurzdigital.com/kta/kta-kinegram-document-validation-service:latest

Example Setup using Docker Compose

# docker-compose.yml
version: '2.1'
services:
  app:
    image: 'registry.kurzdigital.com/kta/kta-kinegram-document-validation-service:latest'
    ports:
      - "5000:8080"
    environment:
      - CLIENT_IDS=<client-id-1>;<client-id-2>;<client-id-3>;
      - RESULT_SERVER_URLS=<result-server-url-1>;<result-server-url-2>;<result-server-url-3>;
      - WS_ENDPOINT_INCLUDE_BINARY_FILES_IN_RESULT=false
    healthcheck:
      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://localhost:8080/actuator/health"]

In this example the container port 8080 is mapped to port 5000 on the host machine.

# Start the Docker Container (with the `docker-compose.yml` in place)
$ docker-compose up

Environment Variables

Application Configuration

Environment Variable	Description
CLIENT_IDS	Semicolon separated list of Client-IDs.
RESULT_SERVER_URLS	Semicolon separated list of Result-Server URLs.
RESULT_SERVER_SIGNING_KEY_PATH	Optional private key for signing the request to the Result Server according to RFC 9421, in DER format
WS_ENDPOINT_INCLUDE_BINARY_FILES_IN_RESULT	If “true”, binary files (SOD and DataGroups) are included in the Result.
SERVER_NAME	Optional name for the server that can be viewed in the app. Useful for multi-region deployments.

The Client Ids function as API access keys as described in the API Description.
Configure a corresponding result server URL for each WebSocket API client.

Result Server Connection Behavior

When posting results to the configured result server, DocVal implements the following connection behavior:

Timeout: 3 seconds per connection attempt (both connect and read timeout)
Retry Policy: Up to 3 attempts total
Retry Conditions:
- Network/connection errors (e.g., timeouts, connection reset, SSL handshake failures) trigger automatic retry
- Only 408, 429, and 5xx HTTP error responses trigger retry
Total Maximum Time: Approximately 10 seconds (3 attempts × 3 seconds + 200ms delays between retries)

Websocket Handshake Authorization

Environment Variable	Description
WS_HANDSHAKE_AUTHORIZATION_VALIDATION_ENABLED	Set to `true` to enable WebSocket handshake authorization. When enabled, DocVal expects connecting clients to include an `Authorization` header in their handshake request.
WS_HANDSHAKE_AUTHORIZATION_VALIDATION_URL	The URL of your external authorization service endpoint. DocVal sends a request here (with the client’s `Authorization` header) to validate the token. Must be set if `WS_HANDSHAKE_AUTHORIZATION_VALIDATION_ENABLED` is `true`.
WS_HANDSHAKE_AUTHORIZATION_VALIDATION_HTTP_METHOD	The HTTP method (e.g., GET, POST) DocVal should use when calling the `WS_HANDSHAKE_AUTHORIZATION_VALIDATION_URL`. Defaults to `GET`.
WS_HANDSHAKE_AUTHORIZATION_FORWARD_TO_RESULT_SERVER	Set to `true` to forward the `Authorization` header received from the client during the handshake to the configured result server. This forwarding can operate even if `WS_HANDSHAKE_AUTHORIZATION_VALIDATION_ENABLED` is `false`.

DocVal provides an optional mechanism for handling Authorization headers during the websocket handshake. You can configure DocVal to perform two main actions with the Authorization header received from the client:

Validate the Header: DocVal can call an external authorization service you provide to verify the token or credentials in the header before fully establishing the WebSocket connection.
Forward the Header: DocVal can pass the Authorization header received from the client along to the configured result server.

These two actions can be enabled independently or used together.

OpenAPI and Swagger Configuration

Environment Variable	Description
SPRINGDOC_APIDOCS_ENABLED	Whether the OpenAPI documentation should be enabled. Defaults to `false`.
SPRINGDOC_SHOWACTUATOR	Whether the actuator endpoints should be included in the OpenAPI definition. Defaults to `true`.
SPRINGDOC_SWAGGERUI_ENABLED	Whether the SwaggerUI should be enabled. Defaults to `true`. Only if OpenAPI is enabled.

For a list of all config options, conduct the Springdoc Documentation. The environment variable is the capitalized parameter name with dots (.) replaces by underscores (_) and dashes (-) removed.

When enabled, the OpenAPI definition is available under /v3/api-docs and the SwaggerUI can be viewed under /swagger-ui.html.

Proxy Configuration (if required)

Java Proxies Configuration

Variable	Description
HTTP_PROXY_HOST	Proxy Server hostname or address for outgoing HTTP requests.
HTTP_PROXY_PORT	Proxy Server port for outgoing HTTP requests. (Defaults to “80”)
HTTPS_PROXY_HOST	Proxy Server hostname or address for outgoing HTTPS requests.
HTTPS_PROXY_PORT	Proxy Server port for outgoing HTTPS requests. (Defaults to “443”)
NON_PROXY_HOSTS	List of hosts that should be reached directly, bypassing the proxy.¹
TRUST_STORE_PATH	Path to a Java Keystore with additional CA certificates for the proxy/result server
TRUST_STORE_PASSWORD	Keystore password

¹ Separated by the ‘|’ character. The wildcard character ’*’ can be used for pattern matching.

Telemetry Data (Logs, Traces, and Metrics) Configuration

Telemetry Data (Logs, Traces, and Metrics)

Health Endpoint

To retrieve the health of the application, make a GET request to /actuator/health and check for a 200 OK status code.

More information can be found in the Spring Boot documentation.

Trusted Certificates (Master List)

DocVal ships with a built-in master list that aggregates CSCA certificates from official government sources (e.g. BSI master list and certificates from .gov websites operated by authorities).

The provided master list is offered as a voluntary add-on and is explicitly not part of the contractually owed functionality of the DocVal Server and is provided on a best-effort basis.

Alternatively, you may provide your own master list and maintain it independently, for example, by using the master list published by the German Federal Office for Information Security (BSI).

To integrate your own master list(s), mount them into the /app/master-lists directory:

Volume mount on /app/master-lists: Replaces the built-in list entirely.
File mount of individual files into /app/master-lists/: Extends the built-in list with additional certificates.

[Optional] Signing the message to the Result Server

When a private key is provided, requests sent to the Result Server will be signed according to RFC 9421. The private key must be in DER format.

For example: RESULT_SERVER_SIGNING_KEY_PATH=file:example-path/to/private-key.der