Developing with MapStore
- Apache Maven for Java
A basic knowledge of both tools is required.
To start developing the MapStore framework you have to:
- download developer tools and frontend dependencies locally:
After a while (depending on the network bandwidth) the full set of dependencies and tools will be downloaded to the node_modules sub-folder.
- start the development instance with:
Then point your preferred browser to http://localhost:8081. By default the front-end works using the online dev server as back-end. This configuration is useful for a quick startup, but is not the suggested configuration if you want to develop. To learn how to connect the front-end dev server to a local back-end read the following instructions.
Connect Front-end to local back-end
npm start uses the online dev server as a backend.
This configuration needs to be changed to develop locally in order to access all the functionalities.
To use a local back-end you have to:
- Remove auth configuration dedicated to GeoServer from
localConfig.json --> authenticationRules(it provides the MapStore/GeoServer integration for dev-server, that is not present in your local back-end)
1 2 3 4 5 6 7 8 9 10 11 12
Run the back-end locally. See the dedicated section in this page
Setup dev-server to use the local back-end, applying this changes to
buildConfig.js--> devServer configuration. (the configuration of the port and path depends on how you configured the local back-end.
1 2 3 4 5 6 7 8 9 10 11 12
npm start doesn't run the examples by default (for dev performance reasons). If you want to run in dev mode the application with also the examples you can run, instead of
npm start the following command:
This command will compile and run both mapstore and examples, with the same live editing functionalities of
Debugging the frontend
The development instance uses file watching and live reload, so each time a MapStore file is changed, the browser will reload the updated application.
Use your favorite editor / IDE to develop and debug on the browser as needed.
We suggest to use one of the following:
- Visual Studio Code with the following plugins:
- EditorConfig for VSCode
- Atom with the following plugins:
- minimap & minimap-highlight-selected
- highlight-line & highlight-selected
- Sublime Text Editor with the following plugins:
- Babel snippets
Redux Dev Tools
When you are running the application locally using
npm start you can debug the application with redux dev tools using the flag ?debug=true
It also integrates with the browser's extension, if installed.
This way you can monitor the application's state evolution and the action triggered by your application.
Frontend unit tests
To run the MapStore frontend test suite you can use:
You can also have a continuously running watching test runner, that will execute the complete suite each time a file is changed, launching:
npm run continuoustest
To run ESLint checks launch:
npm run lint
To run the same tests Travis will check (before a pull request):
npm run travis
More information on frontend building tools and configuration is available here
In order to have a full running MapStore in development environment, you need to run also the back-end java part locally. In this section you will find how to start the back-end and how to develop with it.
Defaults Users and Database
Running MapStore back-end locally, on start-up you will find the following users:
admin, with ADMIN role and password
userwith USER role with password
You can login as
admin to set-up new users and access to all the features reserved to
The database used by default in this mode is H2 on disk. You can find the files of the database in the directory
webapps/mapstore/ starting from your execution context. Check how to set-up database in the dedicated section of the documentation.
When we say "running the back-end", in fact we say that we are running some sort of a whole instance of MapStore locally, that can be used as back-end for your front-end dev server, or for debugging of the back-end itself.
MapStore is configured to use a tomcat maven plugin-in to build and run mapstore locally. To use it you have to:
- make sure to run at least once
mvn installin the root directory, to make
Your local back-end will now start at http://localhost:8080/mapstore/.
If you want to change the port you can edit the dedicated entry in
web/pom.xml, just remember to change also the dev-server proxy configuration on the front-end in the same way.
Local tomcat instance
If you prefer, or if you have some problems with
mvn tomcat7:run-war, you can run MapStore back-end in a tomcat instance instead of using the embedded one.
To do so, you can :
- download a tomcat standalone here and extract to a folder of your choice
- To generate a war file that will be deployed on your tomcat server, go to the root of the Mapstore project that was git cloned and run
./build.sh. This might take some time but at the end a war file named
mapstore.warwill be generated into the
- Copy the
mapstore.warand then head back to your tomcat folder. Look for a
webappsfolder and paste the
- To start tomcat server, go to the terminal,
cdinto the root of your tomcat extracted folder and run
./bin/startup.sh( unix systems) or
./bin/startup.bat(Windows). The server will start on port
8080and Mapstore will be running at
http://localhost:8080/mapstore. For development purposes we're only interested in the backend that was started on the tomcat server along with Mapstore.
Even in this case you can connect your front-end to point to this instance of MapStore.
To run or debug the server side part of MapStore we suggest to run the back-end in tomcat (embedded or installed) and connect in remote debugging to it. This guide explains how to do it with Eclipse. This procedure has been tested with Eclipse Luna.
Enable Remote Debugging
for embedded tomcat you can configure the following:
then start tomcat
For your local tomcat, you can follow the standard procedure to debug with tomcat.
Setup eclipse project
- Run eclipse plugin
- Import the project in eclipse from File --> Import
- Then select Existing project into the Workspace
- Select root directory as "web" (to avoid eclipse to iterate over all node_modules directories looking for eclipse project)
- import the project
Start Debugging with eclipse
- Start Eclipse and open Run --> Debug Configurations
- Create a new Remote Java Application selecting the project "mapstore-web" setting:
- host localhost
- port 4000
- Click on Debug Remote debugging is now available.
NOTE With some version of eclipse you will have to set
suspend=yin mvn options to make it work. In this case the server will wait for the debug connection at port 4000 (