GeoServer 3.0 on Ubuntu 24.04 on Azure User Guide

Overview

GeoServer is the reference open source server for publishing your geospatial data to the world using open Open Geospatial Consortium (OGC) standards. It speaks WMS (map images), WFS (vector features), WCS (coverages) and WMTS (map tiles), and ships a rich built in Web Admin console for managing workspaces, data stores and layers and for previewing them on an interactive map. Install the cloudimg image and you have your own private geospatial server ready to serve GIS and web mapping applications. The image installs GeoServer 3.0.0 from the official platform independent distribution (bundled Jetty) and runs it as the dedicated geoserver system service under OpenJDK 21. GeoServer is bound to the loopback connector 127.0.0.1:8080 and fronted by nginx on port 80, alongside an unauthenticated health endpoint. The GEOSERVER_DATA_DIR, its configuration, the shipped sample layers and the tile cache all live on a dedicated Azure data disk. A unique admin password is generated on the first boot of every VM by rotating GeoServer's well known default admin / geoserver credential, so no VM ever ships with a known credential. The sample layers that ship with GeoServer are preloaded so the Layer Preview and a real map render work immediately. Backed by 24/7 cloudimg support.

What is included:

• GeoServer 3.0.0 installed from the official platform independent distribution (bundled Jetty) and run as the geoserver system service under OpenJDK 21
• GEOSERVER_DATA_DIR relocated onto a dedicated Azure data disk at /var/lib/geoserver
• GeoServer bound to 127.0.0.1:8080, fronted by nginx on port 80 proxying /geoserver
• Port 80 serving an unauthenticated /healthz endpoint for load balancer probes
• The shipped sample workspaces and layers preloaded so Layer Preview and a WMS map render work out of the box
• A unique admin account password rotated on first boot from GeoServer's default admin / geoserver, recorded in a root only file
• The keystore master password also rotated away from its default, so the console ships without security warnings
• geoserver.service + 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_D2s_v4 (2 vCPU / 8 GiB RAM) is a reasonable starting point for a JVM based geospatial server; size up for heavier rendering workloads and larger data. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp if you add TLS) for the Web Admin and the OGC services. GeoServer 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 GeoServer 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 geoserver \
  --image <marketplace-image-urn> \
  --size Standard_D2s_v4 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

After the VM is created, open port 80 so you can reach the Web Admin:

az vm open-port --resource-group <your-rg> --name geoserver --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 Web Admin URL and where the credentials file lives.

Step 4 - Confirm the services are running

GeoServer runs as a systemd service behind nginx. Confirm both are active, that GeoServer is bound to the loopback connector, and that GEOSERVER_DATA_DIR is on the dedicated data disk:

systemctl is-active geoserver.service nginx.service
ss -tlnp | grep -E '127.0.0.1:8080|:80 '
findmnt /var/lib/geoserver

Step 5 - Retrieve your admin password and confirm the default is rotated

The per VM admin password is written to a root only file at /root/geoserver-credentials.txt (mode 0600). The well known default admin / geoserver credential is rotated away on first boot and is rejected on both the Web Admin login form and the REST API:

sudo cat /root/geoserver-credentials.txt
GS=http://127.0.0.1:8080/geoserver
curl -s -o /dev/null -w '%{http_code}\n' -u admin:geoserver $GS/rest/about/version.json   # 401, rejected

Step 6 - Explore the OGC service capabilities

GeoServer advertises each OGC service through a GetCapabilities document. Retrieve the WMS capabilities and confirm every service answers:

PW=$(sudo grep '^GEOSERVER_ADMIN_PASSWORD=' /root/geoserver-credentials.txt | cut -d= -f2-)
GS=http://127.0.0.1:8080/geoserver
curl -s -u admin:$PW "$GS/ows?service=WMS&version=1.3.0&request=GetCapabilities" -o wms-capabilities.xml
head -n 5 wms-capabilities.xml

Step 7 - Render a map with WMS GetMap

Prove the geospatial engine renders by requesting a map image of the sample layer topp:states:

PW=$(sudo grep '^GEOSERVER_ADMIN_PASSWORD=' /root/geoserver-credentials.txt | cut -d= -f2-)
GS=http://127.0.0.1:8080/geoserver
curl -s -u admin:$PW -o states.png \
  "$GS/ows?service=WMS&version=1.3.0&request=GetMap&layers=topp:states&bbox=-124.73,24.96,-66.97,49.37&width=512&height=340&srs=EPSG:4326&format=image/png"
file states.png

Step 8 - Sign in to the Web Admin

Browse to http://<vm-public-ip>/geoserver/web/, click the user icon and sign in with admin and the password from Step 5. The home page welcomes you with an Administration panel summarising the layers, layer groups, stores and workspaces the server is publishing.

Step 9 - Browse the layers with Layer Preview

Open Layer Preview to browse every layer the server publishes. Each layer offers an OpenLayers preview and downloads in common formats such as GML and GeoJSON:

Step 10 - Preview a layer on an interactive map

Click the OpenLayers link next to the topp:states layer to open it on an interactive slippy map. Pan and zoom to explore the data rendered live by the WMS service:

Step 11 - Manage layers, stores and workspaces

The Layers page under Data lists every published layer with its store, native projection and enabled state, and gives you the actions to add, remove, enable and disable layers. This is where you publish your own data:

Step 12 - Publish your own data

To publish your own geospatial data, add a store then publish a layer from it. In the Web Admin go to Data then Stores then Add new store, choose a format (for example PostGIS, GeoPackage, Shapefile or GeoTIFF), point it at your data, then go to Data then Layers then Add a new layer and publish. Everything you add is written under GEOSERVER_DATA_DIR on the dedicated data disk, so it survives independently of the operating system disk.

Step 13 - Confirm data lives on the dedicated disk

The GEOSERVER_DATA_DIR sits on the dedicated Azure data disk, so your configuration, styles and published data are decoupled from the OS disk and can be resized independently:

findmnt /var/lib/geoserver
ls /var/lib/geoserver

Maintenance

Add TLS. GeoServer 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 Web Admin and the OGC services are served over HTTPS on port 443.

Back up the data directory. Everything that matters, the security configuration, styles, workspaces, stores and layers, lives under /var/lib/geoserver. Snapshot the data disk or back up that directory to preserve your configuration and published data.

Keep the admin password safe. The per VM password is in /root/geoserver-credentials.txt (root only). Change it from the Web Admin under Security then Users, Groups, Roles at any time.

Updates. The image ships with unattended security upgrades enabled for the operating system. GeoServer itself can be upgraded by following the project's upgrade notes.

Support

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