MapStore is a full web GIS platform that ships as a WAR file or a Docker image

It is a web application, not a mapping library

The distinction decides everything else. MapStore is an open-source web mapping framework that lets users create, share and embed maps and dashboards, drawing on a broad range of geospatial data sources. It is delivered as a web application you deploy, and the README names the two ways to try it: Docker, with all tags available on the geosolutions Docker Hub, or a local Java web container such as Apache Tomcat.

That shape is very different from the mapping libraries most web developers reach for. It is not a component you render inside your own page, and it is not a set of functions for adding a map to a form. It is the application that a user logs into, in which they compose a map, style layers, run spatial analysis and publish a dashboard.

The topics on the repository list the stack it sits on: cesium, geojson, gis, leaflet, maps, mapstore, openlayers, tcatalog and tomcat. The README states the framework integrates with OpenLayers, Leaflet and Cesium for both 2D and 3D visualization, and it is based on OpenLayers, Cesium, Leaflet and ReactJS.

Two names in that topic list are worth pausing on if you have operated a web GIS. TCatalog appears as a topic, and OGC standards such as WMS, WMTS, WFS, 3DTiles and CSW are named as built-in support. GeoJSON is there too. The README says MapStore caters to professional GIS users while keeping an intuitive interface for casual users, and supports layer styling, spatial analysis tools and collaborative editing.

The layer that matters commercially is the plugin system. The architecture is described as designed for modularity and extensibility, allowing developers to integrate custom plugins, and the Docker section confirms the practical consequence since a custom plugin means building your own image.

A Docker run is the fastest way to see it work

The README's quickest path is a two command Docker run. You pull the published image and start it with a name and a port mapping:

docker pull geosolutionsit/mapstore2
docker run --name mapstore -p 8080:8080  geosolutionsit/mapstore2

Once the container is up you open http://localhost:8080/mapstore and log in with the default credentials, admin and admin, then start creating maps.

Those default credentials are the first thing to change if the instance is reachable by anything other than your own laptop, and the README repeats the admin and admin instruction in both the Docker section and the WAR section, so it is clearly the intended starting point for a quick evaluation rather than a production configuration.

The image tag is the second decision. The README says all tags are available on the geosolutions Docker Hub, and the three instance environments described later in the README are the way to decide which one you want. The DEV instance deploys every change as soon as it is published on the master branch. The STABLE instance is deployed on demand after each release. QA is used internally before a release, becomes active one week before any release during the hardening phase, and for that week it diverges from STABLE because it is anticipating the next stable. As the README puts it, if you want the latest features use DEV, and if you are not that brave use STABLE.

That three tier scheme is a useful signal about the project's release discipline, and it is also a reason to pick a tag rather than always tracking latest.

Building your own image takes a WAR file, and the Dockerfile will find it or fail

Customising MapStore means building an image rather than pulling one, and the README is explicit about why: if you need to customise MapStore, for example to use your own build or custom plugins, you build an image using the provided Dockerfile instead of relying on the prebuilt image.

The build takes one argument, MAPSTORE_WEBAPP_SRC, which specifies either the URL or the local path of an already built WAR file to include in the image:

docker build \
  --build-arg MAPSTORE_WEBAPP_SRC=<YOUR_WAR_FILE> \
  -t <YOUR_IMAGE_TAG> .

The Dockerfile itself is more careful than a typical one liner. The build stage copies the whole context, then looks for the WAR file in two known places, ./product/target/mapstore.war for a standard MapStore build and ./web/target/mapstore.war for a custom one, and fails with an explicit error if neither exists. The value of MAPSTORE_WEBAPP_SRC can also be a URL, in which case the build installs curl and ca-certificates, downloads the file, and then purges both packages and clears the apt lists again, so the image does not carry the download tooling.

The runtime stage is tomcat:10.1-jdk17, with a non-root user created through UID, GID and UNAME arguments, and the environment sets MAPSTORE_WEBAPP_DST to the Tomcat webapps directory so the WAR lands in the right place. Heap defaults are 512m for both initial and maximum memory, which are build arguments you can raise.

The practical consequence of all this is that the Docker path is not a pure JavaScript build. The client is bundled with webpack and Babel, and the application is a Java web app, so a full build means the Maven side and the client side together.

The compose file wires MapStore to PostGIS and an nginx proxy

For a local environment with a database, the repository ships a docker-compose.yml, and the README lists the adjustments you need to make first. You should change the MAPSTORE_WEBAPP_SRC build argument to test a different release, and you should change the value of POSTGRES_PASSWORD for more security. Due to proxy binding on host port 80 you may need to run docker-compose as root, and the README notes that the requirements of the deployment mean you should update the compose file to the latest version.

The compose file itself has three services on a bridge network called mapstore-network. The postgres service builds from ./docker/postgres/ and produces an image named geosolutions-mapstore/postgis, with a healthcheck of pg_isready against the postgres user, a five second interval and up to 120 retries, and a named volume pg_data for the data directory. Its environment sets POSTGRES_USER, POSTGRES_PASSWORD and POSTGRES_DB, with the database named geostore.

The mapstore service builds from the repository root using the Dockerfile, and its command line is explicit about the startup order:

    command: [ "wait-for-postgres", "postgres", "5432", "postgres", "postgres", "catalina.sh", "run" ]

It waits for the database before starting Tomcat, and it declares a dependency on the postgres service. The third service is nginx, which mounts ./docker/mapstore.conf as its default site configuration and publishes port 80 to the host, which is why the README warns about the root requirement for the port binding.

Once it is up you reach the application at http://localhost/mapstore, log in with admin and admin, and stop it with docker-compose down, or tear everything down including images and volumes with docker-compose down --remove-orphans --rmi all -v.

The WAR route still needs a Java and Tomcat version check

The traditional deployment is still supported. You download the WAR file from the latest release, and the README says to install it in your Java web container, for example Tomcat, with the usual procedures for the container, which normally means copying the war file into the webapps subfolder. You then reach the application at http://localhost:8080/mapstore on the standard port, again with admin and admin.

The README does not state the required versions in the quick start, and instead points at the developer guide requirements page for which version of Java and Tomcat are needed. That is the first thing to check, and it is a check worth doing before you plan a deployment, since the container images pin tomcat:10.1-jdk17 and a Tomcat 9 or Java 8 deployment of the same WAR is a different proposition.

The repository layout explains the rest of the structure. There is a java/ directory for the server side, a web/ directory for the client, a product/ directory for the standard packaging and a project/ directory for the custom build, plus build/, build.sh, utility/, binary/, tests/ and docs/. The two WAR search paths in the Dockerfile map directly onto product/ and web/, which is the same distinction the README draws between standard MapStore and custom MapStore.

The documentation is built with mkdocs, since mkdocs.yml and a .readthedocs.yaml are present, and the published site at docs.mapstore.geosolutionsgroup.com is what both the README and the developer guide point to.

The licence story needs reading twice

Here the README and the repository listing disagree in wording, and an engineer should read both. The repository listing classifies the licence as a custom one that GitHub cannot classify, pointing at the LICENSE file, and the top level entries do include a LICENSE.txt.

The README's licence section says something different. It states that MapStore is Free and Open Source software, that it is based on OpenLayers, Cesium, Leaflet and ReactJS, and that it is licensed under the Simplified BSD License.

Those two statements are not obviously the same thing. A file at the root and a sentence in the README are the two things you can actually read, and a permissive per-file BSD grant and a custom project-wide grant have different consequences for a commercial deployment and for redistribution. Treat the LICENSE.txt file as the source of truth and have your own review look at it, because this article is not legal advice and the README text is not the licence text.

On the other side of the ledger, the components MapStore builds on carry their own licences, and OpenLayers, Leaflet, Cesium and React all have well known terms that a downstream reviewer will want to see accounted for. The README notes that MapStore is based on those four, which is a useful pointer for that review.

Maintenance is the other half of the adoption question. The last push was on 2026-10-20, the day before this review, the repository is not archived, and the release tags are dated versions such as v2026.02.00, v2026.02.01 and v2026.02.02. A dated version scheme and a master branch that deploys continuously to DEV indicate an active release process rather than an occasional one.

Editorial conclusion

Adopt MapStore if you need a browser based map editor and dashboard on top of OGC services, and want a ready made application rather than a library to embed. Do not adopt it if you need a component inside your own React application or a permissive licence, since the repository is classified with a custom licence and the README states the project is licensed under the Simplified BSD License. Verify first which Java and Tomcat versions the developer guide requires, change the default admin credentials before exposing the instance, and read LICENSE.txt directly, because the two licence descriptions you can see do not match in wording.

Frequently asked questions

Official sources

1. geosolutions-it/MapStore2 on GitHub
2. Issues
3. Project website
4. README
5. Releases