Best Practices

In this section we will see the best practices for a MapStore installation in production. The suggested installation is using Tomcat.


MapStore, being 90% on the client side, doesn’t require too much resources on the server side. The best practices for tomcat are in general right, following the minimal requirements.

Generally the things that you have to pay attention are only correctly configure:

  • the database

  • logging

  • directories (print)

  • Proxy


For all the configurations files listed in Configurations section, you can decide to:

  • edit in the project before the build (versioning the changes)

  • edit directly in the webapp folder (not recommended)

  • externalize (when allowed)

When the changes are the same across installations (and you don’t have to keep them secret) you can decide to version your configuration directly in your repository. This allows to keep track of the changes and to deploy the application already configured.

When otherwise you need to configure any specific instance with your own settings.

A typical working example is when you have a test environment and a production environment. Usually a context like this you will version all json files of the front-end, that are the same for test and production environment. The same is for config.yaml for printing module, this usually will be the same for both test and production environment, so every customization can be versioned on your repository. Instead you may have to externalize the DB connection parameter, because you typically use two different databases for test or production environments, or H2 for your local machine.

Anyway this depends mostly on your use case. Generally speaking, a common best practice is to reduce the differences between test and production environment as much as possible.


You can configure the current MapStore instance setting the JAVA_OPTS envirnonment variable. A typical example is:



Here the detail about the various options suggested, so you can tune your instance accordingly:

  • $JAVA_OPTS: concatenate with previous definitions of $JAVA_OPTS, if any, in the script.

  • -Xms1024: Initializes the JVM with 1GB of memory. This stores immediately the memory for the application, so it doesn’t require to allocate more memory in the future.

  • -Xmx1024: Limits the usage of the RAM to 1GB. This makes the application fail with a OutOfMemory error instead of allocating too much memory, in case of memory leaks. This way you can set-up a watchdog to report the error and restart the application.

  • -Dgeostore-ovr=file://<path-to-file>/ Externalized configuration of the database. Allows to keep the database configuration across the updates.

  • -DMAPFISH_PDF_FOLDER=<path-to-one-directory>: If Print module is installed, this java system property defines where to store the pdf files generated by the module.



The MapStore backend is not that expensive in terms of system resources as it is only involved to manage users, permissions and to retrieve / save resources such as: - maps - dashboards - stories

This usually doesn’t require any particular optimization

Configuring Maps and layers

When the application is loaded, front-end performances depends mainly on the performances of external resources (typically GeoServer).

You can follow these suggestions to configure and query GeoServer in order to achieve the best performances:

Use compressed formats for WMS images (configurable in “Layer Settings”)

  • In general try to use image/png8 rather than image/png for layers: PNG8 is a lighter format.

  • Consider to use JPEG as format for background layers if possible.

  • If present, you can use the format image/vnd.jpeg-png8, that uses automatically PNG8 or JPEG checking if the image has opacity.

Try to use the cache as much as possible both client side and server side caching, especially for layers that don’t change too frequently. This means:

  • Configure on GeoServer tile layers on GeoServer to create server side tile cache (make sure to align with your map projection/tile size).

  • Configure on GeoServer the cache headers for the layers to configure the client side caching.

  • Make sure to have enabled “use the cache” option for your WMS in MapStore “Layers Settings”.

  • check the geowebcache-cache-result header to check if the server side cache is used. (configurable in “Layer Settings”).

Reduce the requests performed:

  • On maps with many layers, you can consider to configure some layers with Single Tile property. For these layers you will not be able to use the tile cache, but you will reduce the This will now allow to use the cache, but can reduce the number of requests to perform to GeoServer

  • Try to reduce as much as possible maps with many layers active at the same time to reduce the number of client requests (see below)

  • Configure the visibility scale limits on the client side ( configurable “Layer Settings”, to perform the requests only on the desired zoom level intervals.

  • Configure, as alternative on the configuration above, proper styles GeoServer side to visualize layers only below or above certain scale values using scale denominators rules in the SLD.

  • Use bigger tile size, to reduce the number of requests (prefer 512 pixel tiles over 256, configurable in “Layer Settings”).


Most of the configurations suggested above can be configured from Layer Settings. You can access these settings by clicking on the Layer entry in the Table of Contents (TOC), then clicking on the “Selected Layer Settings” button in the toolbar on top on the layer.

how to open the layer settings

You can access to the settings of a particular layer by selecting the layer and clicking on the “setting buttons”

All the configuration listed are in the “Display” tab. In this tab you can find the image format, tile size, visibility limits and options for tile cache or single tile

layer settings of MapStore

Display tab of the layer settings contains all the settings for the optimization of the layer

use domain sharding

Most of the web browsers limits to 6 the number of concurrent requests that can be performed on a single domain, to avoid to open too many connections.

If you are using many tiled layers, you may find this limitation as a bottle neck for the performances of your application.

To avoid this limitation, you may decide to publish your data on different domains (e.g., … ). MapStore allows to add multiple alternative URLs for a layer. To do it, you can add multiple URLs in the “Advanced Options” for type WMS. These aliases will be used for all the layers added from this catalog

configuring a WMS catalog with domain sharding