Mapbender Web GIS on Ubuntu 24.04 on Azure User Guide

Overview

This guide covers the deployment and configuration of Mapbender on Ubuntu 24.04 on Azure using cloudimg Azure Marketplace images. Mapbender is an open source geoportal framework maintained under the Open Source Geospatial Foundation (OSGeo) and published at mapbender.org. It lets an organisation compose, publish and manage web mapping applications from a browser backend instead of writing code: you register your existing OGC web services (WMS and WFS), arrange them into layersets, drop map elements such as a layer tree, search, feature info, measure and print onto a template, and publish the result as a shareable map application.

The image installs Mapbender 4.2.6 on the Symfony 6.4 framework, nginx and PHP 8.3 FPM to serve it, and PostgreSQL 16 with the PostGIS extension from Ubuntu 24.04 to hold the portal configuration, and wires all of it together. Unattended security upgrades are configured to keep the server patched on your running VM.

A portal and proxy over your own services. Mapbender composes and proxies the OGC services you already run, so it is light on data — PostGIS holds the portal configuration (applications, sources, layers, users and access control), not heavy raster tiles — and runs comfortably on a small VM while your map servers do the heavy lifting.

One appliance, three services. nginx and php8.3-fpm serve the portal on port 80, and postgresql holds every application, source, layer and account. PostgreSQL is bound to localhost:5432 and PHP FPM listens on a Unix socket, so neither is ever exposed to the network. Port 80 is the only reachable surface.

A Symfony deployment done properly. The document root is the framework's public/ directory and nothing above it. The application source, its vendored dependencies, the configuration and above all .env.local — which holds this VM's application secret, database password and JWT passphrase — and the JWT private key live outside any URL the web server can address. On top of that, only the Symfony front controller is permitted to execute PHP, so a file placed anywhere else in the web root is refused rather than run.

Security by design — the well known root/root default is closed. Mapbender normally ships a super administrator with the username root and the password root. This image ships no account, no .env.local, no application secret, no JWT keypair and no database schema at all. On the very first boot of every VM a one shot service generates a unique Symfony APP_SECRET, a unique database password, a unique JWT passphrase and keypair, builds the schema and the default demo map applications, and then rotates the super administrator to a unique per instance password — proving through the real login form that the new password signs in and that root/root, a blank password and other common guesses do not, before writing /root/mapbender-credentials.txt (mode 0600, root only).

Why the per instance application secret matters. APP_SECRET is Symfony's session, cookie and CSRF signing material. If it were baked into the image, every customer of that image would share it, and anyone holding the image could forge a signed session for anyone else's portal. Here it is generated on your VM, for your VM.

The portal cannot serve an unprovisioned instance. nginx and php8.3-fpm are each gated on a bootstrap marker that first boot writes only after every credential is in place. Until that marker exists systemd skips those units entirely, so there is no window in which the transient root/root default is reachable on any network. The units are still enabled, so the portal comes straight back after a reboot.

What is included:

• Mapbender 4.2.6 on Symfony 6.4, served by nginx and PHP 8.3 FPM, with the public/ directory as the only web root

• PostgreSQL 16 with the PostGIS extension (postgresql.service) holding the portal configuration, bound to loopback

• Three bundled demo map applications built from OpenStreetMap and example WMS sources, so a real map renders out of the box

• Register OGC WMS and WFS sources; compose applications from layersets and templates; a rich element library (layer tree, legend, feature info, search, measure, coordinate display, print, sketch, digitizer); a full user, group and role access control system; and a JWT secured REST API

• A per instance application secret, database password, JWT keypair and super administrator password generated on first boot and documented in /root/mapbender-credentials.txt (0600)

Prerequisites

• An Azure subscription with permission to create resources

• An SSH key pair (ssh-keygen -t rsa -b 4096 if you need one)

• Basic familiarity with the Azure Portal or the Azure CLI

• To publish your own maps: the URL of at least one OGC WMS or WFS service you control or are permitted to use

Step 1: Deploy from the Azure Portal

1. Search the Azure Marketplace for Mapbender Web GIS on Ubuntu 24.04 LTS by cloudimg and select Create.

2. Choose your subscription and resource group, a region, and the recommended size Standard_B2s (2 vCPU, 4 GB).

3. Set the administrator username to azureuser and provide your SSH public key.

4. On the Networking tab, allow inbound port 80 (HTTP) and port 22 (SSH).

5. Review and create. When the VM is running, note its public IP address.

Step 2: Deploy from the Azure CLI

RG="webgis-prod"; LOCATION="eastus"; VM_NAME="mapbender"
GALLERY_IMAGE_ID="/subscriptions/<sub-id>/resourceGroups/azure-cloudimg/providers/Microsoft.Compute/galleries/cloudimgGallery/images/mapbender-ubuntu-24-04/versions/<version>"
SSH_KEY="$(cat ~/.ssh/id_rsa.pub)"
az group create --name "$RG" --location "$LOCATION"
az vm create \
  --resource-group "$RG" --name "$VM_NAME" \
  --image "$GALLERY_IMAGE_ID" \
  --size Standard_B2s \
  --admin-username azureuser \
  --ssh-key-values "$SSH_KEY" \
  --public-ip-sku Standard
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 80 --priority 1001
az vm open-port --resource-group "$RG" --name "$VM_NAME" --port 22 --priority 1002

Step 3: First boot and your credentials

On first boot the image generates this VM's application secret, database password, JWT passphrase and keypair, builds the database schema and the demo map applications, rotates the root super administrator to a unique password, opens the bootstrap gate, starts the web server, verifies the new credentials work and root/root is rejected, and writes /root/mapbender-credentials.txt. This completes within a minute or two. SSH in as azureuser and read the details:

sudo cat /root/mapbender-credentials.txt

The file is mode 0600 and owned by root, so only a privileged user can read it. It contains the portal URL, the super administrator username (root), email address and password, and the database name, user and password.

Step 4: Confirm the appliance is running

All three services should report active. ss confirms the portal is on port 80 while PostgreSQL is bound to loopback only, and the response headers carry no server version banner.

systemctl is-active postgresql.service php8.3-fpm.service nginx.service
php -r 'echo "PHP ".PHP_VERSION."\n";'
sudo -u postgres psql -tAc "SELECT 'PostgreSQL '||current_setting('server_version')"
sudo -u postgres psql -d mapbender -tAc "SELECT 'PostGIS '||extversion FROM pg_extension WHERE extname='postgis'"
nginx -v
ss -tlnp | grep -E ':(80|5432) ' | sed 's/users:.*//' | sort
curl -sI http://127.0.0.1/user/login | head -4

Step 5: Sign in to your portal

Browse to http://<your-server-ip>/user/login and sign in with the username root and the password from your credentials file.

Step 6: Change the super administrator password

Once signed in, open the user menu (top right, Logged in as: root) and go to Security → Users → root to set your own password. You can also do it from the command line at any time:

cd /var/www/mapbender/application
sudo -u www-data php bin/console fom:user:resetroot --username=root --password='<new-password>' --email=you@example.com --silent

Step 7: Open the demo map application

The image ships three ready made demo applications. Open Mapbender Demo from the backend, or browse directly to http://<your-server-ip>/application/mapbender_user_yml. An OpenLayers map renders immediately with an OpenStreetMap base map, a layer tree, and elements for feature info, legend, search, print, measure and more — proof the whole stack is working end to end.

Step 8: Explore the management backend

The backend is served at / once you are signed in as an administrator. The Applications page lists every map application with actions to view, edit, copy and export it, and a New Application button to build your own.

Step 9: Register an OGC WMS or WFS source

Go to Sources → Add source and paste the GetCapabilities URL of a WMS or WFS service you control. Mapbender loads its capabilities and adds it to the repository, ready to drop into any application. The bundled applications already reference example WMS sources so you can see how a registered source is used. When an upstream service changes, use the reload action on the source's card to refresh its capabilities.

Step 10: Create your own application

From Applications → New Application, give it a title and URL slug, pick a template, then add a layerset built from your registered sources and drop the elements you want (layer tree, feature info, search, print). Publish it and it is reachable at http://<your-server-ip>/application/<your-slug>.

Step 11: Configure mail so password reset works

A fresh appliance sends mail to a null transport. To enable password reset and notifications, point Mapbender at your SMTP server by adding a MAILER_DSN line to .env.local and clearing the cache:

cd /var/www/mapbender/application
sudo sed -i 's#^MAILER_DSN=.*#MAILER_DSN=smtp://user:pass@<your-smtp-host>:587#' .env.local
sudo -u www-data php bin/console cache:clear

Step 12: Use your own domain and add TLS

Point an A record at your VM's public IP. Mapbender builds absolute URLs from the request Host header, so no configuration change is needed for the new hostname. Then install a certificate with Certbot:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d maps.example.com --redirect --agree-tos -m you@example.com

Certbot edits the nginx site in place and reloads it. Renewal is handled automatically by the packaged timer.

Step 13: How the security model works

nginx and php8.3-fpm are each gated on the bootstrap marker /var/lib/cloudimg/mapbender-bootstrap-ready, which first boot creates only after the application secret, database password, JWT material and the rotated root account all exist. Until then systemd skips those units, so the transient root/root default is never reachable. Both units are still enabled, so the portal returns after a reboot.

grep -H ConditionPathExists /etc/systemd/system/{nginx,php8.3-fpm}.service.d/cloudimg-bootstrap-gate.conf
ls -l /var/lib/cloudimg/
systemctl is-enabled postgresql.service php8.3-fpm.service nginx.service mapbender-firstboot.service

The web root is the Symfony public/ directory and nothing above it. .env.local (the application secret, database password and JWT passphrase) and the JWT private key live above the web root, and nothing above public/ is reachable over HTTP. Only the front controller executes PHP.

grep -E '^\s+root ' /etc/nginx/sites-available/mapbender
for p in /.env.local /config/jwt/private.pem /vendor/autoload.php /bin/console; do
  printf '%-28s HTTP %s\n' "$p" "$(curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1$p)"
done

The per instance secret is unique to this VM, and the real login form rejects root/root and every other common guess. Exactly one super administrator account exists on a fresh instance.

Step 14: Back up your portal

Everything Mapbender stores — applications, sources, layers, users and access control — lives in the mapbender PostgreSQL database. Take a consistent dump at any time:

sudo -u postgres pg_dump -Fc mapbender > mapbender-$(date +%F).dump

Restore into an empty database with pg_restore. Keep the dump somewhere off the VM (Azure Blob Storage, for example).

Step 15: Keeping Mapbender up to date

The OS receives unattended security updates automatically. To move to a newer Mapbender release, update the Composer requirement in /var/www/mapbender/application, run composer update, then php bin/console cache:clear and php bin/console doctrine:migrations:migrate as www-data. Always take a pg_dump backup first and test on a copy.

Troubleshooting

• The portal returns nothing right after boot. First boot takes a minute or two to build the schema and rotate the credentials. systemctl status mapbender-firstboot.service shows its progress; nginx and php8.3-fpm only start once it finishes.

• A map application shows an empty map. The application references an external WMS/WFS source that is unreachable from the VM. Check the source URL under Sources, and confirm the VM can reach it (curl -I <capabilities-url>).

• root/root does not work. That is by design — the default is closed on first boot. Use the per instance password from sudo cat /root/mapbender-credentials.txt.

• Password reset emails are not sent. Configure MAILER_DSN in .env.local (Step 11) and clear the cache.

• A 500 error after editing configuration. Clear the Symfony cache: cd /var/www/mapbender/application && sudo -u www-data php bin/console cache:clear, and check var/log/prod.log.

Support

cloudimg provides 24/7 technical support for this Mapbender image by email (support@cloudimg.co.uk) and live chat, with a one hour average response time for critical issues. We help with domain and TLS setup, registering OGC WMS and WFS sources, building templates and applications, user and access control configuration, PostGIS and digitizer setup, mail delivery, PostgreSQL backup and restore, performance tuning and version upgrades.

Mapbender is free software licensed under the MIT License, copyright the Open Source Geospatial Foundation. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.