Configuring LuciadFusion Platform properties and Spring profiles

You can find the configuration files for LuciadFusion Platform in the config folder of your LuciadFusion distribution.

The LuciadFusion Platform is based on the Spring framework for system and application development. It uses YAML configuration files to configure the properties of an environment. The Spring configuration file names have this format: application-<profile name>.yml.The profile name corresponds with the environment you’re configuring.

Spring profiles allow you to segregate parts of the application configuration and make them available only when they’re activated. This comes in handy when you want distinct property values for different environments.

You activate profiles 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

Always include the fusion.single profile 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 a single server instance.

Spring order of resolving profile properties

Spring imposes the order in which property values are resolved.

As a consequence, command line arguments can override JNDI attributes from java:comp/env, and those JNDI attributes can in turn override the properties defined in the YAML files.

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

LuciadFusion profiles

You can find these configuration files in the config folder:

  • application-fusion.development.yml with a fusion.development profile: this application profile contains configurations to get a server application up and running. It’s used when you start LuciadFusion Platform via start.jar. It’s suitable for development only, so do not use it for production environments.

  • application-fusion.production-template.yml with a template for a fusion.production profile: you base your actual production profile on the contents of this template configuration file. It lists all properties that must have a value before you build the application. Other properties are optional. See Deploying the LuciadFusion Platform for more information.

  • fusion.common.yml: you can use this optional file can to overwrite the default values set in the fusion.single profile. Both application-fusion.development.yml and application-fusion.production-template.yml import this file, so you can use it for settings that are shared between both profiles.

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

To set up these profiles, you can start from a copy of application-fusion.production-template.yml, and modify the properties. The copies 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 in both the fusion.single profile and the fusion.staging profile (and the imported fusion.common.yml configuration file) are resolved from left to right. If the 'fusion.staging' profile re-defines properties of the fusion.single profile, those properties are overwritten.

General configuration

Enabling and disabling services

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

Configuring security

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.

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 — mandatory for deployment

A list of origins for which cross-origin requests are allowed. Values may be a specific domain, for example "https://domain1.com". Use the CORS-defined special value "*" for all origins. You can also use it to specify more flexible origins patterns, using "*" anywhere in the host name and port lists. Examples:

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

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

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

fusion.security.authenticationManager — mandatory for deployment

Defines where LuciadFusion checks user credentials. Possible values are:

  • authenticate_all: recommended for use in demo and testing environments only. This setting disables user management. All users are authenticated regardless of their credentials.

  • properties_in_memory: Recommended for use in development environments only, not for deployment. You configure user credentials within the configuration file under fusion.security.users. See application-fusion.development.yml for an example with an administrator (admin) and data manager (dm) user.

  • ldap_ad: you use an Active Directory LDAP service for authentication management, and specify the service details under fusion.security.ldap_ad.

  • ldap: you use an LDAP service for authentication management, and specify the service details under fusion.security.ldap.

fusion.security.authenticationTypes — mandatory for deployment

The pre-defined authentication types are:

  • form: enables form-based authentication, using cookies to track a user’s session. It shows a LuciadFusion Studio login screen with form fields for user names and passwords. These are passed to the server in a POST request.

  • http_basic: HTTP basic authentication. It sets up basic authentication for the LuciadFusion REST API and LuciadFusion services. The browser and other clients transmit user names and passwords in an HTTP header in a server request. Activate this option if you’re securing services that don’t support credential forms.

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’s 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/3.2.1/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 won’t 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 Spring Web MVC 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’re all idle. If there are more threads than the minimum thread pool size, the idle threads are terminated and removed from the thread pool. The minimumSize must be at least 0 and Integer.MAX_VALUE at most. With a minimumSize of 0, no idle thread will be kept in the thread pool.

fusion.events.async.threadPool.maximumSize

Configures the maximum number of available threads. If an event handler needs to be executed and the number of active threads equals the maximum thread pool size, the execution of the event handler is queued until a thread becomes available. The maximumSize must be at least equal to the minimumSize — or 1 if 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’s 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 you use the LuciadFusion Platform, you must configure the port differently.

  • If you are using the LuciadFusionPlatform.zip file generated by the deployment script or the startup script shipped with the release, you can change the port by modifying the server.port property in the development profile in 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 LuciadFusion 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 data store

fusion.studio.configuration.datastore — mandatory for deployment

Defines where LuciadFusion saves its data, such as uploaded data, index files, database files for an embedded H2 database, or data pre-processed for a service.

Configuring the Studio database

The database configuration properties are available under the fusion.studio.db section. It defines access information for the database storing the LuciadFusion data. The available properties are:

fusion.studio.db.url — mandatory for deployment

The JDBC connection string to connect to your database. The URL includes the database server location and port. You can find examples of JDBC connection strings for all our supported databases in application-fusion.production-template.yml.

fusion.studio.db.username — mandatory for deployment

The user name 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 LuciadFusion Studio. You can use a user with fewer privileges the next time you run LuciadFusion Studio.

fusion.studio.db.password — mandatory for deployment

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 the Deploying the LuciadFusion Platform article for more information on the supported databases and how to install them.

Configuring the thread pool for LuciadFusion Studio jobs

LuciadFusion Studio executes long-running jobs, such as crawling and preprocessing jobs, in a background thread pool. You can configure the size of this jobs thread pool 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’re all idle. When there are more threads than the minimum thread pool size, the idle threads are terminated and removed from the thread pool. The minimumSize must be at least 0 and Integer.MAX_VALUE at most. With a minimumSize of 0, no idle thread will be kept in the thread pool.

fusion.studio.configuration.jobs.threadPool.maximumSize

Configures the maximum amount of available threads. If LuciadFusion Studio needs to execute a job, and the number of active threads equals the maximum thread pool size, it queues the job execution until a thread becomes available. The maximumSize must be at least equal to the minimumSize — or 1 if the minimumSize is 0 — and at most Integer.MAX_VALUE.

Configuring default metadata

It’s possible to configure default metadata values in Studio. These are values required according to the ISO-19115 standard. If LuciadFusion Studio fails to auto-generate any of those values during crawling, it uses these default metadata values instead. You must complete this configuration if you want all the metadata generated by LuciadFusion Studio to strictly adhere to the ISO-19115 standard. Studio also pre-fills 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: en, nl or fr for example.

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

See the configuration file fusion.common.yml for an explanation of the OGC service properties. 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. The tile store is the location where the Tiling Engine stores the coverages it generates. The tile store is located within the data store.

fusion.engine.tilestoreHome — mandatory for deployment

Located in application-fusion.production-template.yml. The tile store’s location is required for the production profile, where it has ${fusion.studio.configuration.datastore}/FusionCoverages as default value.

The dollar sign and the curly braces indicate a reference to other properties in the YAML files.

For the optional parameters for the tiling service, see 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, must have access to this service. Without it, the luciad.symbology.military.MilitarySymbologyPainter doesn’t 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. Set the configuration options 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 isn’t available, because it isn’t linked in the web.xml file or because it doesn’t exist, the servlet uses a sensible default.