Configuring Platform properties and Spring profiles

The configuration files for LuciadFusion Platform are in the config folder of the distribution. The LuciadFusion Platform is based on the Spring framework for system and application development, and uses YAML configuration files with file names that have the following format: application-<profile name>.yml.

Spring profiles allow you to segregate parts of the application configuration and make them available only when they are activated. This comes in handy when you want different property values for different environments. You can activate profiles in the usual way, by setting Spring properties, for example:

  • In application.yml: spring.profiles.active: fusion.single,fusion.production

  • On the command line: --spring.profiles.active=fusion.single,fusion.production

For more information about externalized configuration and property resolving order in Spring Boot, go to: https://docs.spring.io/spring-boot/docs/2.7.8/reference/html/features.html#features.external-config.

Property ordering rules

Spring imposes the way in which property values are resolved.

In consequence, the properties defined in the YAML files can be overwritten by JNDI attributes (from java:comp/env) for example, and those can in turn be overwritten by command-line arguments.

Securing secret property values

Some configuration file properties may store secret values, database passwords for instance. In general, it’s not a good practice to store sensitive data, like passwords of production systems, in clear text in YAML configuration files. Typically, you configure such properties outside the configuration files. To do so, you can use Spring Boot’s externalized configuration options. For example, you can define these properties through environment variables or Kubernetes Secrets.

LuciadFusion profiles

The config folder contains the following files:

  • A fusion.development profile in application-fusion.development.yml: this application profile contains configurations that allow you to get a server application up and running. It is used when you start LuciadFusion Platform via start.jar. It is mainly suited for development, and should not be used for production environments.

  • A fusion.production profile in application-fusion.production-template.yml: you must use this configuration file as a basis for production. It lists all properties that must have a value before you build the application. See Configuring LuciadFusion Studio for more information. Some of those properties are mandatory. Others are optional.

  • The fusion.common.yml: this optional file can be used to overwrite the default values set in the fusion.single profile. This configuration file is imported in both application-fusion.development.yml and application-fusion.production-template.yml, so it can be used for settings that are shared between both profiles.

The fusion.single profile must always be included in the list of active profiles in the spring.profiles.active property. This profile contains sensible default property values to run all LuciadFusion services on one (single) server instance.

The profile YAML files in the list contain documentation for each property. This guide gives an overview of the most important properties.

Create a specific profile for each environment. For example:

  • development environment: application-fusion.development.yml

  • production environment: application-fusion.production.yml

  • test environment: application-fusion.test.yml

  • staging environment: application-fusion.staging.yml

These profiles are modified copies of application-fusion.production-template.yml. They all import the same fusion.common.yml configuration.

The deploy environment of the application server determines how you set active profiles. For example, for the staging environment: spring.profiles.active=fusion.single,fusion.staging The properties that are configured in both the fusion.single profile and the fusion.staging profile (and its imported fusion.common.yml configuration file) will be resolved from left to right. That means that the re-defined properties of fusion.single will be overwritten.

General configuration

Each service is enabled by default and can be disabled by setting the <service prefix>.enabled: false. For example, to disable the OGC WMS service in the fusion.common.yml file: fusion.ogc.wms.enabled: false

Configuring security

The LuciadFusion Platform comes with a number of ready-to-use security configuration options.

The property fusion.security.enabled is set to true by default. If the built-in security in the LuciadFusion Platform is enabled, the following properties need to be set:

fusion.security.cors.origins

A list of origins for which cross-origin requests are allowed. Values may be a specific domain, e.g. "https://domain1.com", the CORS defined special value "*" for all origins or a more flexible origins patterns with "*" anywhere in the host name in addition to port lists. Examples:

  • https://*.domain1.com — domains ending with domain1.com

  • https://*.domain1.com:[8080, 8081] — domains ending with domain1.com on port 8080 or port 8081

  • https://*.domain1.com:[*] — domains ending with domain1.com on any port, including the default port

fusion.security.authenticationManager

Possible values are authenticate_all, properties_in_memory, ldap_ad, ldap.

fusion.security.authenticationTypes

Possible values are form, http_basic, no_auth.

The pre-defined authentication types are:

  • form: enables form-based authentication, using cookies to track a user’s session

  • http_basic: enables HTTP Basic authentication

  • no_auth: disables authentication

The pre-defined authentication managers are:

  • ldap_ad: for performing user authentication against an Active Directory server.

  • ldap: for performing user authentication against a LDAP server.

  • properties_in_memory: for defining users within the configuration file. This is not recommended in a production environment.

Each of the options has its own set of configuration settings. Within the configuration file, they are organized by authentication type.

Using your own authentication and authorization system

You can still configure the security for your own authentication and authorization system, if the available options aren’t enough. You can use your own security configuration, through the Spring Boot Security Java configuration.

  • Configure user authentication: You can configure user authentication logic using Spring Security. It is guaranteed to work no matter if access control/LuciadFusion security is enabled or disabled.

  • Configure user authorization: You can configure user authorization logic using Spring HTTP Security to restrict access to critical resources. Your authorization logic will override any existing built-in HTTP security authorization configuration (including enabled access control configurations), which comes out of the box with LuciadFusion software distribution.

If you only disable the LuciadFusion security, and don’t configure your own security, Spring Boot Security uses a default fallback: basic authentication on all HTTP endpoints and a single user, with user as the username and a random password that is printed in the logs at INFO level with the text "Using generated security password".

For more information about Spring Boot Security, go to https://docs.spring.io/spring-boot/docs/2.7.8/reference/html/web.html#web.security. For a general overview of Spring Security, see Spring security architecture.

You can also configure SSL in LuciadFusion. See application-fusion.production-template.yml for more information.

Configuring access control

The LuciadFusion Platform offers support for access control. If you enable access control, you must configure access to data and product resources with access rules. Also, with enabled access control, only administrator users can log in to LuciadFusion Studio.

Access control is disabled by default. To enable access control, set the property fusion.accessControl.enabled to true. If you enable access control, set these properties:

fusion.accessControl.adminRole

Specifies which organization-defined role is considered an administrator role. Users with that role have full access to LuciadFusion.

fusion.accessControl.authenticatedEndpoints

Any endpoint pattern listed there (with authenticated set to true) will require authentication. If a service endpoint doesn’t match any pattern it will not require authentication. If you want to allow anonymous access to a service you need to make sure the endpoint doesn’t match any pattern (or set authenticated to false). The syntax of the endpoint pattern is defined by the ant-style pattern

If you enable access control, but don’t specify access rules, only administrator users can access the data and products served by LuciadFusion.

See Access control in LuciadFusion, the REST API Console and REST API documentation for more information on working with access rules. If a LuciadFusion instance is running, you can find the console at http://localhost:8081/api/console and the REST API documentation at http://localhost:8081/api/documentation.

Configuring asynchronous event handling

By default, the event listeners for all LuciadFusion events are executed asynchronously, in a background thread pool. The event handling thread pool can be configured using the following properties:

fusion.events.async.enabled

Allows the asynchronous execution of LuciadFusion event listeners to be enabled or disabled. Asynchronous execution is enabled by default. When disabled, LuciadFusion Platform will revert to the default Spring event dispatching behavior. Namely, all event listeners will be executed synchronously, on the same thread that the event was published on. This may slow down the handling of requests by LuciadFusion Studio or the Platform Services. If you need more specific event handling behavior, you can disable asynchronous event handling and register your own ApplicationEventMulticaster in the Spring application context.

fusion.events.async.threadPool.minimumSize

Configures the minimum number of threads available to execute event handlers. There will always be at least this many threads available in the thread pool, even if they are all idle. When there are more threads than the minimum thread pool size, idle threads will be terminated and removed from the thread pool. The minimumSize must be at least 0, in which case no idle thread will be kept in the thread pool, and at most Integer.MAX_VALUE.

fusion.events.async.threadPool.maximumSize

Configures the maximum amount of available threads. If an event handler needs to be executed and the amount of active threads is equal to the maximum thread pool size, the execution of the event handler will be queued until a thread becomes available. The maximumSize must be at least equal to the minimumSize (or 1 in case the minimumSize is 0) and at most Integer.MAX_VALUE.

Configuring logging

Logging is configured as follows:

  • The fusion.development and fusion.production profiles refer to the logging configuration using the logging.config property. By default, it refers to the config/fusion.logback.xml file.

  • The config/fusion.logback.xml file contains the default logging configuration for LuciadFusion. It defines to which file the logs are written, and which levels are used for console logging and for file logging. It is possible to modify or replace this file. See config/fusion.logback.xml for more information on how to change the configuration.

Modifying the port

Depending on how LuciadFusion Platform is used, the port should be configured differently.

  • If you are using the LuciadFusionPlatform.zip file generated by the deployment script or the startup script that is shipped with the release, you can modify the port by changing the server.port property in the fusion.development profile (config/application-fusion.development.yml).

  • If you are deploying the LuciadFusionPlatform.war file generated by the deployment script on a servlet container, refer to the documentation of the servlet container, for example Apache Tomcat or Jetty.

Configuring Studio

For Studio, you can find the production properties that require a value in application-fusion.production-template.yml and the development properties in application-fusion.development.yml. Shared Studio properties are listed in fusion.common.yml configuration file.

Configuring the Studio database

The database configuration properties are available under the fusion.studio.db section. The available properties are:

fusion.studio.db.url

The JDBC connection string to connect to your database. You can find examples of JDBC connection strings for all our supported databases in application-fusion.production-template.yml.

fusion.studio.db.username

The username of the database user you want to connect with.

It is important that the database user has the necessary grants to create schemas, tables and indexes the first time you run Studio. You can use a user with less privileges the subsequent times you run Studio.

fusion.studio.db.password

The password of the database user you want to connect with.

Consider carefully before storing a database password directly in a YAML file. See Securing secret property values for more information.

Read our Deploying the LuciadFusion Platform article for more information on the supported databases and how to install them.

Configuring Studio’s jobs thread pool

Studio executes long-running jobs (for instance, crawling and preprocessing jobs) in a background thread pool. The size of this jobs thread pool can be configured using the following properties:

fusion.studio.configuration.jobs.threadPool.minimumSize

Configures the minimum number of threads available to execute jobs. There will always be at least this many threads available in the thread pool, even if they are all idle. When there are more threads than the minimum thread pool size, the idle threads will be terminated and removed from the thread pool. The minimumSize must be at least 0, in which case no idle thread will be kept in the thread pool, and at most Integer.MAX_VALUE.

fusion.studio.configuration.jobs.threadPool.maximumSize

Configures the maximum amount of available threads. If a job needs to be executed and the amount of active threads is equal to the maximum thread pool size, the job execution will be queued until a thread becomes available. The maximumSize must be at least equal to the minimumSize (or 1 in case the minimumSize is 0) and at most Integer.MAX_VALUE.

Configuring default metadata

It is possible to configure default metadata values in Studio. These values are required according to the ISO-19115. If during crawling, Studio fails to auto-generate any of these values, the default metadata value will be used instead. This configuration needs to be filled in if you want all the metadata generated by Studio to strictly adhere to the ISO-19115 standard. Studio will also prefill the relevant values in the Contact Information section of the Service creation form. The default metadata configuration properties are available under fusion.studio.configuration.defaultMetadata. The available properties are:

fusion.studio.configuration.defaultMetadata.language

The language code of the language that the dataset is in (e.g. en, nl, fr, etc).

fusion.studio.configuration.defaultMetadata.abstractText

Default abstract text to be used.

fusion.studio.configuration.defaultMetadata.accessConstraint

Handling restrictions imposed on the dataset because of national security, privacy, or other concerns.

fusion.studio.configuration.defaultMetadata.responsibleParty.role

Function performed by the responsible party. Possible values: resourceProvider, custodian, owner, user, distributor, originator, pointOfContact, principalInvestigator, processor, publisher, author.

fusion.studio.configuration.defaultMetadata.responsibleParty.organisationName

Name of the organization of the responsible party.

fusion.studio.configuration.defaultMetadata.responsibleParty.individualName

Name of the responsible person: surname, given name, title separated by a delimiter.

fusion.studio.configuration.defaultMetadata.responsibleParty.position

Role or position of the responsible person.

fusion.studio.configuration.defaultMetadata.responsibleParty.phone

Telephone number by which individuals can speak to the responsible organization or individual.

fusion.studio.configuration.defaultMetadata.responsibleParty.fax

Telephone number of a facsimile machine for the responsible organization or individual.

fusion.studio.configuration.defaultMetadata.responsibleParty.email

List of emails to communicate with persons and organizations associated with the dataset.

fusion.studio.configuration.defaultMetadata.responsibleParty.address.deliveryPoint

Address line for the location.

fusion.studio.configuration.defaultMetadata.responsibleParty.address.city

City of the location.

fusion.studio.configuration.defaultMetadata.responsibleParty.address.administrativeArea

State or province of the location.

fusion.studio.configuration.defaultMetadata.responsibleParty.address.postCode

ZIP or other postal code.

fusion.studio.configuration.defaultMetadata.responsibleParty.address.country

Country of the location.

Configuring OGC services

The OGC service properties are explained in the configuration file fusion.common.yml The property prefix of the OGC services is fusion.ogc.<ogc service>. These settings include:

  • Properties to enable or disable services. If you want to disable a service, set fusion.ogc.wcs.enabled: false for example.

  • The OGC WMS and WMTS tile caching settings.

  • The configuration of metadata auto-generation and OGC CSW server settings such as the INSPIRE profile.

All OGC services properties are listed in fusion.common.yml.

Configuring the Tiling Engine and the LTS service

The most important property of the Tiling Engine is fusion.engine.tilestoreHome, to be found in application-fusion.production-template.yml. It is required for the production profile and has ${fusion.studio.configuration.uploadPath}/coverages as default value. The dollar sign and the curly braces indicate a reference to other properties in the YAML files.

The optional parameters for the tiling service can be found in fusion.common.yml.

Configuring the symbology service

The Symbology Service is a servlet that serves military MS2525/APP6 icons with specified styling information. LuciadRIA, the Luciad browser solution, needs to have access to this service. Without it, the luciad.symbology.military.MilitarySymbologyPainter does not function properly.

You can customize the symbology service to use a specific default style, and clients can request icons with both custom and default styling. The configuration options can be set in the fusion.common.yml configuration file.

Setting the default styling parameters

The default styling parameters file contains a list of styling parameters values and their values. You can manually override the default styling values for each query.

Table 1. Available styling parameters with their default values

Parameter Key

Default Value

Possible Values

Symbol.Frame

true

true, false

Symbol.Fill

true

true, false

Symbol.FillPercentage

1.0

Floating point number between 0.0 and 1.0

Symbol.Icon

true

true, false

Symbol.HaloSize

0

Positive integer [0,1,2…​]

Symbol.HaloColor

rgb(255,255,255)

RGB color [rgb(0,0,0), rgb(128,0,128),…​]

Symbol.AffiliationColorEnabled

true

true, false

Symbol.Size

32

Positive non-zero integer […​31,32,33…​]

Defining affiliation colors

The affiliation colors configuration file contains a list of affiliation types. Each type is mapped to a specific color. The colors are defined as RGB color codes, specifying each color component as an integer between 0 and 255. An overview of the default colors is available in the following table:

Table 2. Available affiliation color parameters with their default values

AFFILIATION_PENDING

rgb(255,255,128)

AFFILIATION_UNKNOWN

rgb(255,255,128)

AFFILIATION_ASSUMED_FRIEND

rgb(128, 224, 255)

AFFILIATION_FRIEND

rgb(128, 224, 255)

AFFILIATION_ASSUMED_NEUTRAL

rgb(171, 255, 171)

AFFILIATION_NEUTRAL

rgb(171, 255, 171)

AFFILIATION_SUSPECT

rgb(255, 128, 128)

AFFILIATION_HOSTILE

rgb(255, 128, 128)

AFFILIATION_EXERCISE_PENDING

rgb(255,255,128)

AFFILIATION_EXERCISE_UNKNOWN

rgb(255,255,128)

AFFILIATION_EXERCISE_ASSUMED_FRIEND

rgb(128, 224, 255)

AFFILIATION_EXERCISE_FRIEND

rgb(128, 224, 255)

AFFILIATION_EXERCISE_ASSUMED_NEUTRAL

rgb(171, 255, 171)

AFFILIATION_EXERCISE_NEUTRAL

rgb(171, 255, 171)

AFFILIATION_JOKER

rgb(255, 128, 128)

AFFILIATION_FAKER

rgb(255, 128, 128)

If the affiliation configuration file is not available, because it is not linked in the web.xml file or because it does not exist, the servlet will use a sensible default.