Building and deploying
Maven is the main tool for building and deploying a complete application. It takes care of:
- building the java libraries and webapp(s)
- calling NPM as needed to take care of the frontend builds
- launching both backend and frontend test suites
- creating the final war for deploy into a J2EE container (e.g. Tomcat)
To create the final war, you have several options:
- full build, including submodules and frontend (e.g. GeoStore)
./build.sh [version_identifier] [profiles]
Where version_identifier
is an optional identifier of the generated war that will be shown in the settings panel of the application and profiles is an optional list of comma delimited building profiles (e.g. printing
, ldap
)
- fast build (will use the last compiled version of submodules and compiled frontend)
mvn clean install -Dmapstore2.version=[version_identifier] [profiles]
- binary build (produces also the binary)
mvn clean install -Dmapstore2.version=[version_identifier] -Pbinary
Building the documentation
MapStore generates 2 types of documentation:
- JSDoc: generated from source code, provides a reference of the API and for the plugins configurations
- MkDocs: generated from markdown files, provides guides for the developers and users
API and Plugins documentation (JSDoc)
The API and plugins documentation is automatically generated using docma. Docma parses the JSDoc comments in the source code and generates a static HTML documentation.
Refer to the existing files to follow the documentation style of various parts of the application:
Please see http://usejsdoc.org/ for further information about how to write proper documentation in JSDoc.
To install docma:
npm install -g docma
While developing you can generate the documentation to be accessible in the local machine by:
npm run jsdoc:test
The resulting doc will be accessible from http://localhost:8081/mapstore/docs/
For the production deploy a different npm task must be used:
npm run jsdoc:build
The documentation will be accessible from the /mapstore/docs/ path
The generated folders can be removed with:
npm run jsdoc:clean
Users and developers documentation (MkDocs)
Note
Make sure to install the proper python dependencies for Mkdocs. See the dedicated page here
Build the mkdocs and generate md files to test in local machine by:
npm run doc:build
Start the built-in dev-server of mkdocs to preview and test documentation live by:
npm run doc:start
Understanding frontend building tools
Frontend building is delegated to NPM and so leverages the NodeJS ecosystem.
In particular:
- a package.json file is used to configure frontend dependencies, needed tools and building scripts
- babel is used for ES6/7 and JSX transpiling integrated with the other tools (e.g. webpack)
- webpack-dev-server is used to host the development application instance
- mocha/expect is used as a testing framework (with BDD style unit-tests)
- webpack: as the bundling tool, for development (see webpack.config.js), deploy (see prod-webpack.config.js) and test (see test.webpack.js)
- karma is used as the test suite runner, with several plugins to allow for custom reporting, browser running and so on; the test suite running is configured through different configuration files, for single running or continuous testing
- istanbul/coveralls are used for code coverage reporting
Including the printing engine in your build
The printing module is not included in official builds by default.
To build your own version of MapStore with the this module, you can use the printing profile running the build script:
./build.sh [version_identifier] printing
For more information or troubleshooting about the printing module you can see the dedicated section