MapStore on Ubuntu 24.04 on Azure User Guide

Overview

MapStore is an open source web GIS framework from GeoSolutions for creating, saving and sharing interactive maps, dashboards, GeoStories and charts. It is the client and portal tier of a spatial data infrastructure: you point it at OGC services such as WMS, WFS and WMTS, at a GeoServer, or at public basemaps, and it gives your users a polished browser interface for exploring and publishing that data. It complements a map server rather than replacing one.

This image runs MapStore 2026.02.00 from the official upstream distribution on Apache Tomcat 9 under OpenJDK 17, with PostgreSQL as the persistence backend rather than the embedded H2 database that upstream ships for evaluation only. Tomcat is bound to the loopback connector 127.0.0.1:8080 and fronted by nginx on port 80, alongside an unauthenticated health endpoint. The PostgreSQL cluster and MapStore's external data directory both live on a dedicated Azure data disk, so every map, dashboard and user account you create is decoupled from the operating system disk.

A unique admin password is generated on the first boot of every VM. MapStore seeds two default logins, admin / admin and user / user; this image rotates the admin password to a per VM secret and removes the demo user account entirely, so no VM ever ships with a credential that is published in the upstream source. Backed by 24/7 cloudimg support.

What is included:

• MapStore 2026.02.00 on the vendor bundled Apache Tomcat 9.0.116, run as the mapstore system service under Ubuntu's OpenJDK 17
• PostgreSQL 16 as the GeoStore backend, replacing the embedded H2 database that upstream documents as unsuitable for production
• The PostgreSQL cluster and MapStore's data directory both on a dedicated Azure data disk at /var/lib/mapstore
• Tomcat bound to 127.0.0.1:8080 and fronted by nginx on port 80, with an unauthenticated /healthz endpoint for load balancer probes
• A unique admin password rotated on first boot, and the seeded demo user account deleted, recorded in a root only file
• A preloaded sample map with an OpenStreetMap background and an offline vector layer, so a real map renders on first load
• Request payload logging disabled, so credentials are never written to the system journal
• mapstore.service, postgresql and nginx.service as systemd units, enabled and active
• 24/7 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point: MapStore is a single JVM alongside a local PostgreSQL, and upstream's own reference production heap is 512 MiB. Size up if you expect many concurrent users or plan to enable the printing module heavily. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp if you add TLS). MapStore is served over plain HTTP by default, so for production put your own domain and a trusted certificate in front of it (see Maintenance).

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for MapStore by cloudimg, and select Create. On Basics pick your subscription, resource group, region and size; under Administrator account choose SSH public key and paste your key; under Inbound port rules allow SSH (22) and HTTP (80). Review the dedicated data disk on the Disks tab, then Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name mapstore \
  --image <marketplace-image-urn> \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

After the VM is created, open port 80 so you can reach the web interface:

az vm open-port --resource-group <your-rg> --name mapstore --port 80 --priority 900

Step 3 - Connect to your VM

ssh azureuser@<vm-public-ip>

The first boot rotates the admin password and prints a summary to the message of the day, so your first SSH session shows the MapStore URL and where the credentials file lives.

Step 4 - Confirm the services are running

MapStore runs as a systemd service behind nginx, with PostgreSQL as its backend. Confirm all three are active:

systemctl is-active postgresql@16-main.service mapstore.service nginx.service

Confirm Tomcat is bound to the loopback connector only, so MapStore is reachable exclusively through the nginx front end:

ss -tln | grep -E '127.0.0.1:8080|:80 '

Step 5 - Confirm MapStore is answering

The deployed version is published at /mapstore/version.txt, and nginx serves an unauthenticated health endpoint for load balancer probes:

curl -s http://localhost/mapstore/version.txt
curl -s -o /dev/null -w 'GET /mapstore/ -> HTTP %{http_code}\n' http://localhost/mapstore/
curl -s -o /dev/null -w 'GET /healthz   -> HTTP %{http_code}\n' http://localhost/healthz

Step 6 - Retrieve your admin password

The per VM admin password is written to a root only file at /root/mapstore-credentials.txt (mode 0600):

sudo cat /root/mapstore-credentials.txt

Confirm the published default logins are rejected. MapStore seeds both admin / admin and user / user in its source; this image rotates the first and deletes the second, and each is rejected with HTTP 401 while your per VM password authenticates with HTTP 200:

MS=http://localhost/mapstore
for p in admin:admin user:user; do
  code=$(curl -s -o /dev/null -w '%{http_code}' -XPOST -u $p $MS/rest/geostore/session/login)
  printf '%-16s -> HTTP %s\n' "$p" "$code"
  [ "$code" = "401" ] || { echo "UNEXPECTED: $p was not rejected"; exit 1; }
done
code=$(curl -s -o /dev/null -w '%{http_code}' -XPOST -u 'admin:<MAPSTORE_ADMIN_PASSWORD>' $MS/rest/geostore/session/login)
printf '%-16s -> HTTP %s\n' 'admin:<per-VM>' "$code"
[ "$code" = "200" ] || { echo "FAILED: the per VM admin password did not authenticate"; exit 1; }

Step 7 - Query the map catalogue over the REST API

MapStore stores maps, dashboards and GeoStories as resources in its GeoStore backend. List the maps your server is holding, and confirm the preloaded sample map is present:

MS=http://localhost/mapstore
curl -s -u 'admin:<MAPSTORE_ADMIN_PASSWORD>' -H 'Accept: application/json' \
  "$MS/rest/geostore/extjs/search/category/MAP/*?start=0&limit=5" | python3 -m json.tool

The response reports "success": true and a totalCount of at least 1, with the preloaded Welcome to MapStore map listed.

Step 8 - Confirm your data lives on the dedicated disk

Both the PostgreSQL cluster and MapStore's data directory sit on the dedicated Azure data disk, so your maps and accounts are decoupled from the OS disk and the disk can be resized or snapshotted independently:

df -h /var/lib/mapstore | tail -2
pg_lsclusters

Step 9 - Open MapStore in your browser

Browse to http://<vm-public-ip>/mapstore/. The homepage is MapStore's resource catalogue, listing the maps, dashboards and GeoStories available to you:

Step 10 - Sign in

Click the user icon at the top right and choose Login, then sign in as admin with the password from Step 6:

Once signed in, the catalogue shows the resources you own and gives you the Add Resource action for creating new maps, dashboards and GeoStories:

Step 11 - Open the sample map

Open the Welcome to MapStore card. The map renders immediately with an OpenStreetMap background and a set of sample points, with the scale bar, coordinate readout and zoom controls all live:

Step 12 - Explore the layer tree

Open the layers panel from the icon at the top left. The sample map ships with an offline vector layer of sample points that renders without contacting any external service, so you can confirm the map engine works even on a locked down network:

Step 13 - Connect your own OGC services

MapStore's value is consuming your own spatial data. Open the Catalog panel from the map toolbar to add a service, choose the service type (WMS, WFS, WMTS or CSW), give it a name and paste its URL, for example your own GeoServer at https://your-geoserver.example.com/geoserver/wms. Search the catalogue and add any layer it advertises straight onto the map, then save the map so it is available to your users.

If you also need to publish your own geospatial data over OGC services, cloudimg's GeoServer image pairs with this one: MapStore is the portal your users see, GeoServer is the server that publishes the layers.

Maintenance

Add TLS. MapStore is served over plain HTTP on port 80 by default. For production, point a DNS name at the VM and terminate TLS in nginx, for example with Certbot, so the interface is served over HTTPS on port 443.

Back up the database and data directory. Everything that matters lives on the dedicated data disk at /var/lib/mapstore: the PostgreSQL cluster under pgdata/ holds every map, dashboard, GeoStory and user account, and datadir/ holds the configuration overrides. Snapshot the data disk, or take a logical backup with sudo -u postgres pg_dump geostore, to preserve both.

Move the database off the VM. The image runs PostgreSQL locally, which suits a self contained deployment. To point MapStore at an external server such as Azure Database for PostgreSQL, edit the connection settings in /var/lib/mapstore/datadir/geostore-datasource-ovr.properties and restart mapstore.service. Migrate your existing content first with pg_dump and pg_restore so your maps and accounts come with you. PostGIS is not required: MapStore stores map documents, not geometry.

Keep the admin password safe. The per VM password is in /root/mapstore-credentials.txt (root only). Change it at any time from Manage accounts in the user menu.

Outbound connections. The shipped sample map draws its background from OpenStreetMap's public tile service, and MapStore's interface loads a web font from Google Fonts. Both are outbound only. If your VM has no internet egress, the offline vector layer still renders, and you can set any background you prefer in the map configuration.

Updates. The image ships with unattended security upgrades enabled for the operating system. MapStore itself can be upgraded by following the project's release notes; keep your data directory and database, which are external to the application, when you do.

Support

Every cloudimg image is backed by 24/7 support. If you have any questions about deploying or operating MapStore on Azure, contact the cloudimg team.