Getting Started

This section will show you how to create your MapStore standard downstream project and setup the development environment.

Note: ensure to install all the needed tools, see documentation for more info https://mapstore2.readthedocs.io/en/latest/developer-guide/developing/

The aim of the section is to have a MapStore project running locally:

Create Project

Clone the MapStore2 repository in the local workspace to generate the downstream project and install all the dependencies

git clone https://github.com/geosolutions-it/MapStore2 -b <branch-version>
# e.g.
git clone https://github.com/geosolutions-it/MapStore2 -b 2023.01.xx

cd MapStore2

npm install

Create the new project by running the following script from the MapStore2 folder

node ./createProject.js

the command line will prompt some information to create the project that needs to be filled as following (the default value, between parenthesis, will be used if you press enter)

Project Type (standard):
Project Name: MyMapStoreProject
Project Version (1.0.0):
Project Description (Project Name): A sample project for the training
Repository URL:
Output folder: ../MyMapStoreProject

This process will create the new project called MyMapStoreProject in the Output folder indicated (../MyMapStoreProject). Navigate to the new MyMapStoreProject folder to see the files created and start working with it.

cd ../MyMapStoreProject

npm install

Note

If initially, you have cloned the project from master tag, but you want to align mapstore to a specific release like 2023.01.xx , then we suggest to do also the following steps, otherwise the branch used during project creation is maintained in the submodule

To change the version of the MapStore2 submodule in the project to match the current stable branch

navigate inside the MapStore2 submodule

cd ./MapStore2

fetch all the available branches/tags from the origin remote

git fetch origin

switch to the stable branch

git checkout <branch-version or tag>
# e.g.
git checkout v2023.01.00

after the checkout we can return to the project folder

cd ..

Note

Now you can remove the MapStore2 you cloned, that is not needed anymore.

Include print module

The Print plugin will work only if the plugin module is included correctly. Here the steps to add the backend printing module

modify the build.sh file to include the -Pprinting profile

#!/bin/bash
set -e

export GITREV=`git log -1 --format="%H"`
export VERSION="SNAPSHOT-$GITREV"

npm install
npm run compile
npm run lint

if [ $# -eq 0 ]
then
-  mvn clean install -Dmapstore2.version=$VERSION
+  mvn clean install -Dmapstore2.version=$VERSION -Pprinting
else
-  mvn clean install -Dmapstore2.version=$1
+  mvn clean install -Dmapstore2.version=$1 -Pprinting
fi

create a printing directory and copy all the default configuration and image files

mkdir -p backend/resources/printing/

cp -a MapStore2/java/printing/resources/geoserver/print/. backend/resources/printing/

update the copy resource execution inside the web/pom.xml file to target the new configuration folder instead of the MapStore submodule one

<execution>
   <id>printing</id>
   <phase>process-classes</phase>
   <goals>
      <goal>copy-resources</goal>
   </goals>
   <configuration>
      <outputDirectory>${basedir}/target/MyMapStoreProject/printing</outputDirectory>
      <encoding>UTF-8</encoding>
      <resources>
            <resource>
-              <directory>${basedir}/../MapStore2/java/printing/resources/geoserver/print</directory>
+              <directory>${basedir}/../backend/resources/printing</directory>
               <includes>
                  <include>*</include>
               </includes>
            </resource>
      </resources>
   </configuration>
</execution>

Run development environment locally

There are two ways of starting the local environment:

• with a local embedded backend instance

• with an external backend instance

local embedded backend instance

In order to use the local backend instance together with the frontend part run

npm start

The dev environment runs at: http://localhost:8081/?debug=true#/

debug=true allows to enable debug mode and will enable redux dev tools to be used from the dev tools (F12) of the browser if you have installed it as extension

Alternatively, if you have only to change the port or the URL of MapStore backend, but you don’t have to do any more changes to the dev server, you can simply define the environment variable

export MAPSTORE_BACKEND_BASE_URL=https://localhost:8082/mapstore
npm run fe:start # this command lunches only the front-end

The backend environment runs at: http://localhost:8080/mapstore/

Note

If you want to run the backend alone, separated from the frontend, you have to run the following command. (it will start a local instance of the compiled mapstore.war)

npm run be:start

The MapStore application should run at:

http://localhost:8080/mapstore

For the frontend alone you have to run:

npm run fe:start

When you are done with your development you may want to test them in a deployed instance like tomcat, so let’s see how to build the project and generate the .war file

Build the .war

The build process will generate a .war webapp file that can be deployed inside a tomcat container. Compile the first build to verify the project setup

run the script build.sh

./build.sh

If everything is successful take the .war generated file and test it in a tomcat container

Now:

• rename the web/target/MyMapStoreProject.war file to mapstore.war

• download tomcat

• move the mapstore.war to the tomcat/webapps folder

• start the tomcat container (startup.bat for Windows OS or startup.sh for unix OS)

see the official documentation for additional information https://mapstore.readthedocs.io/en/latest/quick-start/#war-file

The MapStore application run at:

http://localhost:8080/mapstore

You can use this tomcat instance as the backend of your local project. The downside of having it in an external tomcat container is that you have to build/deploy mapstore every time if you want to see changes applied

By default the project created searches the backend at this url http://localhost:8080/mapstore, but you can change the whole devServer or only the proxy settings by passing devServer or proxy parameter of the buildConfig call function.

Note

In the mapstore framework we use devServer.js file, that includes the default configuration of the dev-server. It is used by build/webpack.config.js and build/prod-webpack.config.js, that are the configuration files used by the dev and production build for webpack.

MapStore2 submodule update

Every project generated with createProject.js provides a MapStore2 submodule folder that has a reference to a specific commit or branch of mapstore. The submodule is used by the project similarly to a node_modules packages with the difference to be able to apply changes to the submodule and send fixes to the MapStore2 repository/fork where needed. This setup allows to switch to a new version of MapStore2 by following these steps:

navigate to the MapStore2 folder

cd ./MapStore2

fetch the origin to get all the updated branches/commits

git fetch

checkout to a specific branch/commit

git checkout origin/branch

Now the MapStore2 submodule is updated to a specific branch and the project will use it as new package. It could be necessary to check migration guideline after switching to new branch to ensure a working project:

• mapstore migration guide

Best practices

The project could have some misalignment with the default MapStore configuration in particular when migrating to new versions. Before to move on with next steps we suggests steps to check everything is aligned:

• compare MyMapStoreProject/package.json with MyMapStoreProject/MapStore2/package.json in particular the devDependencies

• remove the MyMapStoreProject/package-lock.json and MyMapStoreProject/node_modules and install the packages again. This is needed when updating the version of the MapStore submodule

• compare MyMapStoreProject/web/pom.xml with MyMapStoreProject/MapStore2/java/web/pom.xml

• compare MyMapStoreProject/configs/localConfig.json with MyMapStoreProject/MapStore2/web/client/configs/localConfig.json if it has been added to the project

The list above shows the most common checks but based on the complexity of the project customization we could have additional files to compare.