Harmoney Services
The Harmoney platform consists of the following services:
- api: The main backend service that handles API requests, processes data, and manages business logic.
- web: The frontend service that serves the user interface and interacts with the backend API.
- pdf: A service dedicated to generating PDF documents.
- listcheck: A service that stores lists for compliance checks, autocomplete, etc.
The sections below provide an overview of the configuration possibilities of each service.
API​
Environment Variables​
The following environment variables can be configured:
| Variable Name | Description | Default Value |
|---|---|---|
| DOMAIN | Base domain of the instance | local.myharmoney.eu |
| DEFAULT_THREAD_POOL_SIZE | Max number of threads | 100 |
| DB_HOST | Database host | db |
| DB_SCHEMA | Database schema (in single-tenant mode) | harmoney |
| DB_USER | Database user | |
| DB_PASSWORD | Database password | |
| DB_MIN_POOL_SIZE | Min DB-connection-pool size | 0 |
| DB_MAX_POOL_SIZE | Max DB-connection-pool size | 150 |
| JDBC_OPTS | Query params to add to the jdbc url | allowPublicKeyRetrieval=true&useSSL=false |
| JDBC_OPTS_FLYWAY | Query params to add to the jdbc url for the Flyway migrations | allowPublicKeyRetrieval=true&useSSL=false |
| JOB_INTERVAL_SECONDS | Number of seconds between each job execution for a single timer | 1 |
| NUM_JOB_TIMERS | Number of job timers | 5 |
| LOG_LEVEL | Logging level | INFO |
| LOG_JSON | Enable JSON formatted logs | true |
| PROXY_HOST | Proxy host for outbound requests | |
| PROXY_PORT | Proxy port for outbound requests | |
| NON_PROXY_HOSTS | Pipe-separated list of hosts that should bypass the proxy | |
| OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry OTLP exporter endpoint (gRPC) | http://localhost:4317 |
| OTEL_EXPORTER_OTLP_HEADERS | OpenTelemetry OTLP exporter headers | |
| OTEL_RESOURCE_ATTRIBUTES | OpenTelemetry resource attributes | deployment.environment=local,application.packages=eu.myharmoney |
| OTEL_SERVICE_NAME | OpenTelemetry service name | api |
| OTEL_TRACES_SAMPLER_RATIO | OpenTelemetry Traces Sampler Ratio | 0.0 (tracing is off) |
| JAVA_OPTS | Additional Java options | |
| HARMONEY_KAFKA_* | See Data Warehouse | |
| DWH_* | See Data Warehouse |
Multi-tenancy​
The API service can be configured to run in either single-tenant or multi-tenant mode. In single-tenant mode, all data is stored in a single database schema. In multi-tenant mode, each tenant has its own database schema, and the service dynamically switches between schemas based on the host of the incoming request. The host is translated to the database schema using a host-mapping (see below).
The API service is at this moment not fully stateless. To avoid leaking state across tenants, all stateful components (e.g., caches) are tenant-aware, so they will only store and serve data for the current tenant.
The following configuration is necessary to enable multi-tenancy:
| Variable Name | Value |
|---|---|
| DB_SCHEMA | Must be empty |
| JDBC_OPTS | Should be extended with databaseTerm=SCHEMA |
| JDBC_OPTS_FLYWAY | Same as JDBC_OPTS, but without databaseTerm=SCHEMA |
| JAVA_OPTS | See example below |
JAVA_OPTS should be extended with the host mapping as follows:
JAVA_OPTS: >-
-Dtenants.host-map.tenant1.myharmoney.eu=tenant1
-Dtenants.host-map.tenant2.myharmoney.eu=tenant2
An empty schema with the name base must be present for the API to connect to the database at startup. Multi-tenancy works with a single user, so that user must have access to all schemas.
Database Configuration​
The following parameters can be configured in the table settings_global_parameters:
| Parameter Name | Description | Default Value |
|---|---|---|
| ENVIRONMENT | Contains the base domain of this instance (required) | |
| API_URL | The relative url of the api (required) | /api |
| HEALTH_CHECK_GATEWAY | Checks (level) that should be included in the gateway health-check endpoint | 1 |
| HEALTH_CHECK_TIMEOUT | Default timeout for health-checks of external providers (in seconds) | 30 |
| HEALTH_CHECK_GLOBAL_TIMEOUT | Global timeout for health-checks of external providers (in seconds) | 30 |
| RUN_HEALTH_CHECKS | Execute health-checks or not (L1: 50s, L2: 300s, L3: 600s) | true |
| PRIVACY_POLICY_URL | Default privacy policy url | https://cdn.myharmoney.eu/harmoney-public/terms/terms-of-use-{{lang}}.pdf |
| TERMS_OF_USE_URL | Default terms of use url | https://cdn.myharmoney.eu/harmoney-public/terms/privacy-policy-{{lang}}.pdf |
| ERROR_REPORTING_ENABLED | Used to enable/disable error-mails | true |
| RATE_LIMIT_DISABLED | Used to enable/disable the rate limit (both internal api and gateway) | false |
| RATE_LIMIT_WHITELIST | Comma-separated list of IP-addresses that skip the rate limiter | |
| GATEWAY_RATE_LIMIT_NUM_CALLS | Number of gateway calls per IP-address per window | 12 |
| GATEWAY_RATE_LIMIT_WINDOW | Rate limit window (in seconds) | 60 |
| SMS_VALIDITY | Validity of OTP codes sent via SMS (in seconds) | 120 |
| EMAIL_VALIDITY | Validity of OTP codes sent via email (in seconds) | 120 |
| DEV_MAIL | Email used to send error-mails to | [email protected] |
| CONFIG_MAIL | Email used to send configuration exceptions to | [email protected] |
| EXPONENTIAL_BACK_OFF | Base delay for exponential backoff of job retries. E.g. 30s, 60s, 120s, etc. | 30 |
| DATABASE_CLEAN_ARCHIVES_BEFORE_DURATION | ||
| JWT_SHARED_SECRET | Secret used to encrypt JWT tokens | |
| JWT_EXPIRATION | Expiration time of JWT tokens of authenticated users (in minutes) | 120 |
| SESSION_EXPIRATION | Expiration of sessions (JWT expiration can be extended until session expiration) (in minutes) | 1440 |
| COOKIE_SAME_SITE | Controls the SameSite attribute of the authorization cookie | Strict |
| COOKIE_DOMAIN | Controls the Domain attribute of the authorization cookie | WL origin |
| WHITE_LABEL_VERIFICATION_DISABLED | Allows to disable cross-white-label verification | false |
| TIMEOUT_SECONDS | Default (per-request) timeout of external calls (in seconds) | 110 |
| GLOBAL_TIMEOUT_SECONDS | Default global (including retries) timeout of external calls (in seconds) | 110 |
Web​
Environment Variables​
The following environment variables can be configured:
| Variable Name | Description | Default Value |
|---|---|---|
| API | Relative path towards the api | /api |
| APM_CONFIG | OpenTelemetry configuration (see examples below) | |
| KEYCLOAK_ADMIN_CONFIG | Keycloak configuration (see example below) (beta) |
Elastic RUM​
Example value for APM_CONFIG when using Elastic RUM:
{
"active": true,
"serviceName": "web",
"environment": "local",
"serverUrl": "<elastic apm server url>"
}
Datadog RUM​
Example value for APM_CONFIG when using Datadog RUM:
{
"active": true,
"serviceName": "web",
"environment": "local",
"datadogApplicationId": "<datadog application id>",
"datadogClientToken": "<datadog client token>",
"datadogSite": "<datadog site>",
"sessionSampleRate": 100,
"telemetrySampleRate": 100,
"datadogTrackingConsent": "not-granted"
}
Keycloak (beta)​
{
"keycloakUrl": "https://kc.uat.myharmoney.eu/",
"realm": "realmName",
"clientId": "uat-admin-ui",
"adminApiUrl": "kc-admin-service.uat.myharmoney.eu",
"managerGroup": "/user-managers"
}
PDF​
Environment Variables​
The following environment variables can be configured:
| Variable Name | Description | Default Value |
|---|---|---|
| OTEL_EXPORTER_OTLP_ENABLED | Enable OpenTelemetry OTLP exporter | false |
| OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry OTLP exporter endpoint (gRPC) | http://localhost:4317 |
| OTEL_EXPORTER_OTLP_HEADERS | OpenTelemetry OTLP exporter headers | |
| OTEL_RESOURCE_ATTRIBUTES | OpenTelemetry resource attributes | deployment.environment=local |
| OTEL_SERVICE_NAME | OpenTelemetry service name | pdf |
| OTEL_TRACES_SAMPLER_RATIO | OpenTelemetry Traces Sampler Ratio | 0.0 (tracing is off) |
Listcheck​
Environment Variables​
The following environment variables can be configured:
| Variable Name | Description | Default Value |
|---|---|---|
| DB_HOST | Database host | db |
| DB_SCHEMA | Database schema (in single-tenant mode) | harmoney |
| DB_USER | Database user | |
| DB_PASSWORD | Database password | |
| JDBC_OPTS | Query params to add to the jdbc url | allowPublicKeyRetrieval=true&useSSL=false |
| JDBC_OPTS_FLYWAY | Query params to add to the jdbc url for the Flyway migrations | allowPublicKeyRetrieval=true&useSSL=false |
| LOG_LEVEL | Logging level | INFO |
| LOG_JSON | Enable JSON formatted logs | true |
| OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry OTLP exporter endpoint (gRPC) | http://localhost:4317 |
| OTEL_EXPORTER_OTLP_HEADERS | OpenTelemetry OTLP exporter headers | |
| OTEL_RESOURCE_ATTRIBUTES | OpenTelemetry resource attributes | deployment.environment=local,application.packages=eu.myharmoney |
| OTEL_SERVICE_NAME | OpenTelemetry service name | listcheck |
| OTEL_TRACES_SAMPLER_RATIO | OpenTelemetry Traces Sampler Ratio | 0.0 (tracing is off) |
| JAVA_OPTS | Additional Java options |
Multi-tenancy​
The listcheck service can be configured to run in either single-tenant or multi-tenant mode. In single-tenant mode, all data is stored in a single database schema. In multi-tenant mode, each tenant has its own database schema, and the service dynamically switches between schemas based on an incoming HTTP header from the API service. For simplicity, the listcheck service uses the same host-mapping as the API service, but instead of using the host of the incoming request, it uses the value of the X-Tenant-Schema header to determine the tenant and thus the database schema.
The listcheck service is fully stateless, so no additional measures are necessary to avoid leaking state across tenants.
The following configuration is necessary to enable multi-tenancy:
| Variable Name | Value |
|---|---|
| DB_SCHEMA | Must be empty |
| JDBC_OPTS | Should be extended with databaseTerm=SCHEMA |
| JDBC_OPTS_FLYWAY | Same as JDBC_OPTS, but without databaseTerm=SCHEMA |
| JAVA_OPTS | See example below |
JAVA_OPTS should be extended with the host mapping as follows:
JAVA_OPTS: >-
-Dtenants.host-map.tenant1.myharmoney.eu=tenant1
-Dtenants.host-map.tenant2.myharmoney.eu=tenant2
An empty schema with the name base must be present for the listcheck service to connect to the database at startup. Multi-tenancy works with a single user, so that user must have access to all schemas.