Externalized Configuration

Most of the MapStore configuration files can be externalized using a data directory.

Currently this functionality can only be enabled for projects, not for the main product.

This is useful if you have custom configurations that you don't want to overwrite when you deploy a new version of your MapStore project.

This is a list of backend configuration files that can be externalized in the data directory:

proxy configuration (proxy.properties)
log4j configuration (log4j.properties)
geostore database connection settings (geostore-datasource-ovr.properties)

This is a list of frontend configuration files that can be externalized in the data directory:

app configuration (localConfig.json)
extensions configuration (extensions.json)
context plugins configuration (pluginsConfig.json)
demo map configuration (config.json)
new map template configuration (new.json)
base folder for extensions bundles and assets

Configuration environment variables

Some of the configuration parameters can be set using JVM environment variables: This can be done using flags in the JVM start script:

1	java -Dsome_setting=some_value ...

Flags can also be set using a mapstore.properties file in the JVM classpath. A default one (empty) is included in the MapStore WEB-INF/classes folder. All examples will use the JVM flag syntax, but writing the property in the properties file is always possible.

Using a data directory

To use a data directory, this must be configured through a specific JVM system property: datadir.location

1	java -Ddatadir.location=/etc/mapstore ...

Temporarily, the geostore properties file must be also configured as a specific JVM system property, geostore-ovr, We are going to remove this in a near future.

1	java -Dgeostore-ovr=file:<path to the override file> ...

But this is not enough. Currently usage of the datadir must be enabled for every configuration file that can be externalized. We will see how to enable externalization for each of them in the following sections.

Multiple data directory locations

It is possible to specify more than one datadir location path, separated by commas. This can be useful if you need to have different places for static configuration and dynamic one. A dynamic configuration file is one that is updated by MapStore using the UI, while static ones can only updated manually by an administrator of the server. An example are uploaded extensions, and their configuration files.

MapStore looks for configuration resources in these places in order:

the first datadir.location path
other datadir.location paths, if any, in order
the application root folder

Dynamic files will always be written by the UI in the first location in the list, so the first path is for dynamic stuff.

Example

1	-Ddatadir.location=/etc/mapstore_extensions,/etc/mapstore_static_config

Externalize the proxy configuration

This must be done in the WEB-INF web.xml file:

<context-param>
      <param-name>proxyPropPath</param-name>
      <param-value>${datadir.location}/proxy.properties</param-value>
</context-param>

Externalize the log4j configuration

This must be done in the WEB-INF web.xml file:

<context-param>
    <param-name>log4jConfigLocation</param-name>
    <param-value>file:${datadir.location}/log4j.properties</param-value>
</context-param>

Externalize the database connection settings

This must be done in the geostore-datasource-ovr.properties file:

geostoreDataSource.driverClassName=org.postgresql.Driver
geostoreDataSource.url=jdbc:postgresql://localhost:5432/geostore
geostoreDataSource.username=geostore
geostoreDataSource.password=geostore
geostoreVendorAdapter.databasePlatform=org.hibernate.dialect.PostgreSQLDialect
geostoreEntityManagerFactory.jpaPropertyMap[hibernate.hbm2ddl.auto]=validate
geostoreEntityManagerFactory.jpaPropertyMap[hibernate.default_schema]=geostore
geostoreVendorAdapter.generateDdl=true
geostoreVendorAdapter.showSql=false

Externalize the frontend configuration

This must be done in the project app.jsx entry point, replacing the static configuration file names with a backend service call (/rest/config/load), that will load files from the datadir.

Please notice that the rest/config/load backend service, used to externalize the configuration files, has an automatic fallback to use the internal versions, in the web app folder, if the file is not found in the datadir, so it is safe to change app.jsx without moving the configuration until needed.

Also, the rest service can be used to load only allowed files (this is done for security reasons). By default the following resources are allowed:

localConfig.json
pluginsConfig.json
extensions.json
config.json
new.json

The list of allowed resources can be changed, via the allowed.resources JVM environment variable:

1	java -Dallowed.resources=localConfig,pluginsConfig,extensions,config,new ...

Notice that only json files can be allowed, and the extension is automatically appended.