Basics

In this section you will learn how to quickly install MapStore and we will cover the basic concepts behind a MapStore installation.

Requirements

Minimal requirements for installation and running area available here

The current training is tested on an Ubuntu 22.04 where we can install the database, openJDK, tomcat and other useful tools with the following commands:

sudo apt install -y net-tools postgresql openjdk-11-jdk tomcat9

Installation

A MapStore instance (the main product or a derived project) is a java web application that can be installed in a servlet container like Tomcat.

The easiest way to install MapStore in tomcat is to copy war file of your application in the webapps folder of your tomcat base and start the tomcat instance. The war archive will be extracted in the webapps folder on tomcat start up.

Warning

By default mapstore.war uses h2 database. This database is not recommended for production. So please follow the database section to configure a different database.

Updates

To update a MapStore instance you will only need to replace the old war file with the one for the new version.

If you externalize the configuration by following the Best Practices you will be able to keep your local changes to configuration and maps between updates.

MapStore Product and Projects

There is a difference between the main MapStore product (distributed with MapStore release) and a project created using MapStore as a framework.

When you create a new project in MapStore, the default setup produces a war file identical to the original product that can be installed following the same rules. Anyway from this default starting point the project can be completely refactored by the developers, even using another back-end or no back-end at all. This guide will take into account the case you create a project with default settings. In this way the team that handles the project can see all the opportunities given by the framework in terms of default services and configurations and decide to maintain or modify these features, depending on their particular use case.

The differences between the MapStore product and a default MapStore project are minimal. They have almost the same structure and so the rules of installing and managing these applications are almost the same.

For this reason in this documentation we will refer to a unique method of installation and configuration for both the use cases.

Note

There are some exceptions to this rule. When the two installations differ, this will be highlighted in the related section of the training. Future versions of MapStore will reduce these difference to have a unique system to install and configure both MapStore product and projects.

Printing Module

MapStore has a printing module on the back-end that provides support to the Print plugin. This module can be installed on an existing mapstore instance (product or project) or you can build your MapStore with a specific profile (also a project by default has this build option).

For more information about how to install it, see : Including the printing module in MapStore section in the documentation

Plugins

One of the base concepts that will be often used in this guide is Plugin. They are the base front-end development unit of MapStore, and they provide all the functionalities for the application. There is a plugin for the Map, one for the TOC, one for the Catalog and so on… Each one provides a specific functionality. MapStore product provides a list of core plugins compiled in its JavaScript bundles ready to be used, that can be customized by editing the front-end configuration files.

Usually a MapStore project creates its own build of the front-end part customizing the list of plugins and their configuration (typically adding some custom ones).

Extensions

From MapStore 2021.01.xx MapStore started to support Extensions. Extensions are zip files containing plugins that can be installed (from the MapStore UI) in an existing instance of MapStore.

These plugins will be added to the ones available in the instance (product or project) to be configured in contexts or in front-end configuration files. Also in this case the files related to these installations can be properly externalized to keep them across installations.