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 <https://mapstore.readthedocs.io/en/latest/developer-guide/requirements/>`_

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: 

.. code-block:: bash

    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 <https://en.wikipedia.org/wiki/Web_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 <database.html>`_  section to configure a different database.

.. todo:: fix the link by removing .html if you want to export it as PDF

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 :ref:`Best Practices <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 <https://mapstore.readthedocs.io/en/latest/developer-guide/printing-module/#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.