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:


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.


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.


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.


  • 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": [
    "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


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

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.


<?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 -->



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

        <!-- You can edit this value directly in the app. You can use ${property} syntax to refer Java System Properties -->