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 inapplication-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 viastart.jar
. It is mainly suited for development, and should not be used for production environments. -
A
fusion.production
profile inapplication-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 thefusion.single
profile. This configuration file is imported in bothapplication-fusion.development.yml
andapplication-fusion.production-template.yml
, so it can be used for settings that are shared between both profiles.
The |
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
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 setauthenticated
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 least0
, in which case no idle thread will be kept in the thread pool, and at mostInteger.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 theminimumSize
(or1
in case 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 is 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 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 theserver.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 least0
, in which case no idle thread will be kept in the thread pool, and at mostInteger.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 theminimumSize
(or1
in case the minimumSize is0
) and at mostInteger.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.
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 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.