.. _Externalize Configurations:

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 <https://docs.oracle.com/javase/tutorial/essential/environment/sysprop.html>`__ 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:

.. code-block:: bash

  java -Dsome_setting=some_value ...

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

.. code-block:: bash

  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 <#data-directory>`_ 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 <https://tomcat.apache.org/tomcat-8.5-doc/windows-service-howto.html>`_
- **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 <https://mapstore.readthedocs.io/en/latest/developer-guide/externalized-configuration/>`_.

.. 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 <https://mapstore.readthedocs.io/en/2021.01.xx/developer-guide/externalized-configuration/>`_.

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

.. code-block:: json

  [
  {
    "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


.. code-block:: json

  [{
    "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/``

.. code-block:: json

  {
    "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``

.. code-block:: 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``

.. code-block:: 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>