Externalize Configurations¶

Editing the configuration directly in your webapp folder is not a good choice. In this section you will learn how to externalize the configurations of a MapStore installation to keep your changes outside the webapp folder and so maintain them across updates.

Java system properties¶

MapStore accepts some Java system properties from your running JDK to configure the installation. These options can tell to MapStore where to find some files or paths of the system to use as working directories.

They can be passed on Java startup this way:

java -Dsome_setting=some_value ...

Typically in tomcat you can configure them by editing JAVA_OPTS or CATALINA_OPTS environment variable this way:

CATALINA_OPTS="-Dgeostore-ovr=file:<path-to-file>"

These are the some java system properties that can be used to configure mapstore.

datadir.location path to the location of the data directory. See dedicated section.
geostore-ovr: redefines the path to geostore-datasource-ovr.properties, to externalize the database configuration. This helps to configure the database even without setting up a data directory.
MAPFISH_PDF_FOLDER: path to an external directory where to save PDF files generated by the print plugin (if installed)

The configuration of Java system properties, JAVA_OPTS or CATALINA_OPTS depends on the OS and the tomcat installation you have.

Here some examples:

Windows: tomcat installed as a service:
Guide here
Ubuntu 20.04: tomcat 9 installed from apt :
JAVA_OPTS or CATALINA_OPTS are configurable editing the file /etc/default/tomcat9.

Data Directory¶

In order to reduce the complexity of configuring MapStore, from 2020.01.xx MapStore started to centralize the configurations in a unique folder, called data-directory.

The purpose of the data directory is to:

Provide a central folder where to store all the current back-end settings
Provide support for the externalization of all the configuration files, included the front-end ones
Support patch configurations for front-end configuration files, to store only differences from default
Support installation and maintenance of extensions across updates.

In particular this is actually the only way to externalize extensions installation. To configure your data-directory you have to add to the JAVA_OPTS the property datadir.location valorized with the path to this directory.

More detail about the externalizing configuration using the data directory can be found here.

Note

Data directory for version prior to 2021.02.00 is not available by default and must be explicitly enabled by editing some source files in the project.

Examples of data-directory usage¶

Check data directory active¶

A first operation that you can do with the data directory is to add a flag to the localConfig.json to check that the data-dir is active and fully working. You can do it using the JSON files patching functionality.

Create a new file localConfig.json.patch file in <data-dir>/configs/ with this content

[
{
  "op": "add",
  "path": "/dataDirActive",
  "value": true
}
]

open <MapStore-URL>/configs/localConfig.json (e.g. localhost:8082/mapstore/configs/localConfig.json).

If the data directory is active, you will find the dataDirActive entry in the file.

Add a plugin to the default viewer¶

If you want to customize the plugin list in your intallation without edit the localConfig.json in the webapp, you can use the JSON files patching functionality.

For instance we can add the StreetView plugin, that is not present by default in MapStore.

Create a new file localConfig.json.patch file in <data-dir>/configs/ with this content

[{
  "op": "add",
  "path": "/plugins/desktop/-",
  "value": "StreetView"
}]

Now you can open the default viewer of MapStore and see this plugin up and running.

Note

This plugin need to be configured with a Google API key. See the documentation to see how, this can be an additional exercise for the JSON patch functionality.

Replacing a file in the config directory¶

If patching is not enough, you can place in the <data-dir>/configs/ the files you want to override.

To do it you can:

Copy localConfig.json from MapStore instance into <data-dir>/configs/
Start modifying it

The file will be served instead of the one contained in the webapp. Moreover if a .patch file with the same name is found it will be applied in addition to this file.

Add a static map¶

Every json file placed in this directory will be available on the /configs/ file of MapStore. You can use it to configure some static maps.

Example:

Create a custom file called custom.json in <data-dir>/configs/

{
  "version": 2,
  "map": {
    "projection": "EPSG:900913",
    "units": "m",
    "center": {
      "x": 1250000.000000,
      "y": 5370000.000000,
      "crs": "EPSG:900913"
    },
    "zoom": 5,
    "maxExtent": [
      -20037508.34,
      -20037508.34,
      20037508.34,
      20037508.34
    ],
    "layers": [{
        "type": "osm",
        "title": "Open Street Map",
        "name": "mapnik",
        "source": "osm",
        "group": "background",
        "visibility": true
      }]
  }
}

Open https://localhost:8082/mapstore/#/viewer/openlayers/custom

Tomcat Context¶

Some functionalities in MapStore are configured to be part of the deployment document, the web.xml inside the webapp, configured as context-param or init-params. context-param can be overridden by adding a Parameter option to the context.xml file of your context instance. This is the case of proxyPropPath context parameter, that can indicate where is the proxy.properties

<CATALINA_BASE>/conf/context.xml

<Context>
<!-- [...] -->
<!--  This allows to change the proxy config path -->
<Parameter name="proxyPropPath" value="/var/lib/tomcats/mapstore/conf/proxy.properties" override="false"/>
</Context>

Instead you can change the init-param path to config of the mapfish.print servlet, used for config.yaml, only by editing the web.xml inside the application.

web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.4"
  xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd">

  <!-- pick up all spring application contexts -->
  <context-param>
    <param-name>contextConfigLocation</param-name>
    <param-value>
            classpath*:applicationContext.xml
            classpath*:applicationContext-print.xml
        </param-value>
  </context-param>

  <context-param>
        <param-name>webAppRootKey</param-name>
        <param-value>geostore.root</param-value>
    </context-param>

    <context-param>
      <param-name>proxyPropPath</param-name>
      <param-value>/proxy.properties</param-value>
    </context-param>

    <!-- ... other configurations ... -->

    <servlet>
      <servlet-name>mapfish.print</servlet-name>
      <servlet-class>org.mapfish.print.servlet.MapPrinterServlet</servlet-class>
      <init-param>
        <param-name>config</param-name>
        <!-- You can edit this value directly in the app. You can use ${property} syntax to refer Java System Properties -->
        <param-value>printing/config.yaml</param-value>
      </init-param>
  </servlet>
  <servlet-mapping>
    <servlet-name>mapfish.print</servlet-name>
    <url-pattern>/pdf/*</url-pattern>
  </servlet-mapping>
</web-app>

MapStore Training documentation

Table of Contents

Previous topic

Next topic

This Page

Externalize Configurations¶

Java system properties¶

Data Directory¶

Examples of data-directory usage¶

Check data directory active¶

Add a plugin to the default viewer¶

Replacing a file in the config directory¶

Add a static map¶

Tomcat Context¶

MapStore Training documentation

Externalize Configurations¶

Java system properties¶

Data Directory¶

Examples of data-directory usage¶

Check data directory active¶

Add a plugin to the default viewer¶

Replacing a file in the config directory¶

Add a static map¶

Tomcat Context¶

Navigation