Configuring Your Installation

After the Full Stack Quick Start, every service runs with starter values: shared secrets, bundled infrastructure, and settings chosen for a first run. This section takes you from that starting point to an installation you control.

This page covers how configuration works for each service, how configuration layers are merged, and the recommended order for replacing the starter setup.

How each service is configured

Service	Configured with
Core	YAML configuration files, then ONE_ environment variables
BFF, Bridge, WRPR	Spring Boot properties, set as environment variables
oauth2-proxy, Keycloak, Traefik, databases, Redis	Their own configuration formats; see each project's documentation

Core has the most configuration and the most detailed merge behavior. The rest of this page focuses on Core, with a short section on the Java services.

Core configuration layers

Core builds its runtime configuration from layers, applied in order:

1. Each configuration file passed with --config, in the order given

2. Environment variables beginning with ONE_

When a setting appears in more than one layer, the later layer wins, following the merge rules below.

With Docker Compose, configuration files are set in the service's command and environment variables in env_file:

services:
  core:
    env_file:
      - ./env/.core.env               # Applied last
    command:
      - --config
      - config/config-procivis-base.yml   # Applied first
      - --config
      - /config/my-config.yml             # Applied second
    volumes:
      - ./conf/core/my-config.yml:/config/my-config.yml:ro

Files inside the image, such as the base configuration, are referenced by their path in the image. Your own files must be mounted into the container.

Starting configurations

The Core image includes configuration files to start from:

• Base configuration: defaults for all deployments. Always load it first.
• Deployment configuration: settings for a type of deployment, such as a server. Load it after the base configuration.
• Examples: configurations for specific use cases, in /config/examples. Each example has been tested for its use case and is a reasonable place to start, but it is not guaranteed to fit your requirements. Load an example after the base configuration, then add your own changes in a later layer.

Keep your own changes in a separate file or in environment variables rather than editing the files in the image. This keeps your changes in one place and makes upgrades easier.

Merge and override rules

Core uses Figment to load configuration, with its merge strategy for combining layers:

• Values are replaced. Strings, numbers, and booleans take the value from the later layer. This includes empty strings: a later "" replaces an earlier value.
• Lists are replaced. A later list replaces the earlier list entirely; it is not appended to.
• Objects are merged. Nested settings, such as a provider instance, are merged key by key. A later layer only needs to contain the keys it changes.
• Omitted settings are kept. A setting missing from a later layer keeps its value from the earlier layer.

Earlier layer	Later layer	Result
x: 1	x: 2	x: 2
x: "a"	x: ""	x: ""
x: "a"	x: null	x: null, usually rejected at startup
x: 1	(not set)	x: 1
x: [a, b]	x: [c]	x: [c]
x: {y: 1}	x: {z: 2}	x: {y: 1, z: 2}
x: {y: 1}	x: {}	x: {y: 1}
x: ""	x: {y: 1}	x: {y: 1}

To keep an earlier value, remove the setting from the later layer or comment it out. Do not leave it empty, and do not set it to null: most settings expect a specific type, and Core fails to start if it receives null instead.

warning

Core ignores settings it does not recognize. A misspelled key, or a key with the wrong capitalization, has no effect and produces no error. If a change does not take effect, check the key against the configuration reference, then check the result with the configuration API.

Example

If the configuration passes the following files to Core:

core:
  env_file:
    - ./env/.core.env
  command:
    - --config
    - config/base.yml

and the base configuration contains:

format:
  MDOC:
    type: MDOC
    params:
      public:
        leewaySeconds: 60

and the .core.env contains:

ONE_format__MDOC__params__public__leewaySeconds="120"

the result is an MDOC instance with type: MDOC and leewaySeconds: 120.

Turning off an instance

A later layer cannot remove an instance defined by an earlier layer. Omitting it, or setting it to an empty object, leaves it unchanged. To turn off an instance, set enabled: false:

format:
  MDOC:
    enabled: false

Existing assets created with the instance remain available, but the instance cannot be used for new operations.

Environment variable pathing

To set a Core configuration value with an environment variable:

1. Start with the prefix ONE_.

2. Write the YAML path, replacing each level separator with __ (double underscore).

Given this configuration:

app:
  auth:
    staticToken: "abc123"
keyStorage:
  AZURE_VAULT:
    params:
      private:
        vaultUrl: "https://example.com"

the equivalent environment variables are:

ONE_app__auth__staticToken="abc123"
ONE_keyStorage__AZURE_VAULT__params__private__vaultUrl="https://example.com"

Variable names are case-sensitive. The path must match the YAML path exactly: ONE_app__coreBaseUrl sets app.coreBaseUrl, while ONE_APP__COREBASEURL is ignored.

Environment variables follow the same merge rules as configuration files.

Value syntax

Environment variable values are parsed using TOML-like syntax:

Type	Syntax	Example
String	Text in double quotes	ONE_app__traceLevel="info"
Boolean	true or false, no quotes	ONE_app__enableMetrics=true
Number	Digits, no quotes	ONE_app__databasePool__maxConnections=10
List	Values in [ ], wrapped in single quotes	ONE_issuanceProtocol__OPENID4VCI_FINAL1__params__public__redirectUri__allowedSchemes='["https", "myapp"]'
Object	key=value pairs in { }, wrapped in single quotes	ONE_app__auth='{mode="UNSAFE_STATIC", staticToken="abc123"}'

Inside lists and objects, put strings in double quotes and leave numbers and booleans unquoted. Objects can be nested:

ONE_globalSettings='{httpClient={insecureHttpTransportAllowed=true, maxRedirects=3}}'

An object set this way is merged like any other layer: it adds to and overrides the earlier object, but does not replace it. Setting one value per variable is easier to read and less error-prone; use objects when you need to set many related values at once.

You can configure Core entirely with environment variables, without your own configuration file.

For the full parsing rules, see the Figment Env provider documentation.

Java services

BFF, Bridge, and WRPR are Spring Boot applications. Set their configuration as environment variables using the property names from each service's configuration reference:

frontend.url="https://example.com"
sts.token.iss="https://example.com"

Environment variables override the defaults built into each service. For precedence details and other ways to supply properties, see the Spring Boot documentation on externalized configuration.

Configuration references:

• BFF
• OpenID Bridge
• WRPR

In the quick start bundle

The Full Stack Quick Start bundle configures each service as follows:

Service	Configuration
Core	config/config-procivis-base.yml (in the image), then conf/core/core-config.yml, then env/.core.env
BFF	env/.bff.env
Bridge	env/.bridge.env
WRPR	env/.wrpr.env
oauth2-proxy	conf/oauth2_proxy/oauth2-proxy.cfg, conf/oauth2_proxy/alpha-config.yml
Keycloak	env/.keycloak.env, master-realm.json
Databases	env/.*_mariadb.env, env/.keycloak_postgres.env
Traefik	command and labels in docker-compose.yml

Several values must match across files, such as static tokens and database credentials. The pages in this section list where each value appears.