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 |
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 afusion.development
profile: this application profile contains configurations to get a server application up and running. It’s used when you start LuciadFusion Platform viastart.jar
. It’s suitable for development only, so do not use it for production environments. -
application-fusion.production-template.yml
with a template for afusion.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 thefusion.single
profile. Bothapplication-fusion.development.yml
andapplication-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.
Recommended practice for profiles
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 underfusion.security.users
. Seeapplication-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 underfusion.security.ldap_ad
. -
ldap
: you use an LDAP service for authentication management, and specify the service details underfusion.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 setauthenticated
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 least0
andInteger.MAX_VALUE
at most. With aminimumSize
of0
, 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 theminimumSize
— or1
if the minimumSize is0
— and at mostInteger.MAX_VALUE
.
Configuring logging
Logging is configured as follows:
-
The
fusion.development
andfusion.production
profiles refer to the logging configuration using thelogging.config
property. By default, it refers to theconfig/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. Seeconfig/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 theserver.port
property in the development profile inconfig/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 least0
andInteger.MAX_VALUE
at most. With aminimumSize
of0
, 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 theminimumSize
— or1
if the minimumSize is0
— and at mostInteger.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.
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:
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.