GeoWebCache 2.0 on Ubuntu 24.04 on Azure User Guide

Overview

GeoWebCache is a tile cache server and caching proxy from the GeoServer and GeoTools ecosystem. It sits in front of a WMS map source, pre renders map tiles for the zoom levels and regions you care about, stores them in a blob store on disk, and serves them straight from cache over the standard WMTS, TMS and WMS-C tiling protocols. Web mapping clients such as OpenLayers, Leaflet and MapLibre request tiles by grid position and receive them in milliseconds, while the backend map server is spared from re rendering the same views over and over.

This cloudimg image installs GeoWebCache 2.0.0 from the official standalone distribution as a Java web application inside Apache Tomcat 11 on OpenJDK 21, fronted by nginx on port 80. Tomcat is bound to the loopback connector 127.0.0.1:8080 so the container is reachable only through nginx. A unique administrator password is generated on the first boot of every VM, so no VM ever ships with the well known default geowebcache / secured credential. A demo OpenStreetMap layer named osm is pre seeded into the cache at build time, so the server renders real map tiles the moment it boots, with no external dependency. Backed by 24/7 cloudimg support.

What is included:

• GeoWebCache 2.0.0 installed from the official standalone distribution, run as a web application in Apache Tomcat 11 under OpenJDK 21
• Apache Tomcat bound to 127.0.0.1:8080, fronted by nginx on port 80 proxying /geowebcache
• Port 80 serving an unauthenticated /healthz endpoint for load balancer probes
• The tile cache blob store at GEOWEBCACHE_CACHE_DIR=/var/lib/geowebcache
• A demo osm layer (OpenStreetMap via the terrestris WMS) pre seeded into the cache so real tiles render out of the box
• Secure by default: the WMTS/TMS/WMS tile service is public, while the REST, seed, truncate and reconfiguration endpoints require the administrator credential
• A unique administrator password rotated on first boot from GeoWebCache's default geowebcache / secured, recorded in a root only file
• tomcat.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_B2s (2 vCPU / 4 GiB RAM) is a comfortable starting point for a single JVM tile cache; size up for heavier seeding workloads and larger caches. NSG inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp if you add TLS) for the web UI and the tile services. GeoWebCache 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 GeoWebCache 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). Then Review + create then Create.

Step 2 - Deploy from the Azure CLI

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

Open port 80 (and 22 for SSH) on the VM's network security group, then browse to http://<vm-public-ip>/.

Step 3 - Connect over SSH

ssh azureuser@<vm-public-ip>

The first boot generates the administrator password and prints a summary to the message of the day, so your first SSH session shows the web UI URL and where the credentials file lives.

Step 4 - Confirm the services are running

GeoWebCache runs as a web application in Tomcat behind nginx. Confirm both services are active and that Tomcat is bound to the loopback connector only:

systemctl is-active tomcat.service nginx.service
ss -tlnp | grep -E '127.0.0.1:8080|:80 '
java -version

Step 5 - Retrieve your admin password and confirm the secure by default posture

The per VM administrator password is written to a root only file at /root/geowebcache-credentials.txt (mode 0600). The tile service is public, while the REST and seed endpoints reject both anonymous access and the well known default geowebcache / secured credential:

sudo cat /root/geowebcache-credentials.txt
GWC=http://127.0.0.1/geowebcache
curl -s -o /dev/null -w 'anon      %{http_code}\n' $GWC/rest/layers.xml
curl -s -o /dev/null -w 'default   %{http_code}\n' -u geowebcache:secured $GWC/rest/layers.xml
curl -s -o /dev/null -w 'tiles     %{http_code}\n' "$GWC/service/wmts?REQUEST=GetCapabilities&SERVICE=WMTS&VERSION=1.0.0"

The anonymous and default REST calls return 401, while the public WMTS service returns 200. Authenticate the REST API with the geowebcache user and the password from your credentials file to receive 200.

Step 6 - Confirm the pre seeded tile cache

The demo osm layer is pre seeded into the on disk blob store, so a real tile request is served straight from cache. Request a WMTS tile and confirm it comes back as a real PNG image:

GWC=http://127.0.0.1/geowebcache
curl -s -D - -o tile.png \
  "$GWC/service/wmts?REQUEST=GetTile&SERVICE=WMTS&VERSION=1.0.0&LAYER=osm&STYLE=&TILEMATRIXSET=EPSG:4326&TILEMATRIX=EPSG:4326:0&TILEROW=0&TILECOL=0&FORMAT=image/png" \
  | grep -iE 'HTTP/|content-type|content-length|geowebcache-cache-result'
file tile.png

The geowebcache-cache-result: HIT header confirms the tile was served from the cache rather than re rendered by the backend.

Step 7 - Explore the WMTS capabilities

GeoWebCache advertises its layers and tile matrix sets through a WMTS GetCapabilities document. Retrieve it and confirm the osm layer and the EPSG:4326 tile matrix set are present:

GWC=http://127.0.0.1/geowebcache
curl -s "$GWC/service/wmts?REQUEST=GetCapabilities&SERVICE=WMTS&VERSION=1.0.0" -o wmts-capabilities.xml
grep -oE '<ows:Identifier>[^<]*</ows:Identifier>|<TileMatrixSet>[^<]*</TileMatrixSet>' wmts-capabilities.xml | head

Step 8 - Open the GeoWebCache web UI

Browse to http://<vm-public-ip>/geowebcache/home. The home page welcomes you with the GeoWebCache version, the automatically generated demos link, direct links to the WMTS, TMS and WMS GetCapabilities documents, and live runtime statistics for the cache.

Step 9 - Browse the demo layer list

Follow A list of all the layers and automatic demos to the demo page. Each configured layer is listed with its enabled state and grid sets, and offers OpenLayers and KML previews plus a Seed link. The pre seeded osm layer is published on the EPSG:4326 grid set:

Step 10 - Preview tiles on an interactive map

Click the OpenLayers preview link next to the osm layer to open it on an interactive slippy map. The map is rendered entirely from tiles served by GeoWebCache over WMTS. Pan and zoom to explore the OpenStreetMap data:

Step 11 - Zoom the tile preview

Use the zoom controls to move to higher zoom levels. Tiles already in the cache are served instantly; tiles not yet cached are fetched from the backend WMS, cached, and then served from cache on every subsequent request:

Step 12 - Add your own WMS backend

To cache your own maps, add a WMS backed layer through the authenticated REST API. Authenticate as the geowebcache user with the password from Step 5, then PUT a layer definition. For example:

GWC=http://<vm-public-ip>/geowebcache
curl -u geowebcache:<your-password> -XPUT -H 'Content-Type: application/xml' \
  -d '<wmsLayer><name>mylayer</name><mimeFormats><string>image/png</string></mimeFormats>
       <gridSubsets><gridSubset><gridSetName>EPSG:900913</gridSetName></gridSubset></gridSubsets>
       <wmsUrl><string>https://your-wms-server/wms</string></wmsUrl>
       <wmsLayers>your:layer</wmsLayers></wmsLayer>' \
  "$GWC/rest/layers/mylayer.xml"

Then seed it with a POST to "$GWC/rest/seed/mylayer.xml" or from the Seed this layer form on the demo page. See the GeoWebCache documentation for the full configuration reference.

Maintenance

Add TLS. GeoWebCache 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 UI and the tile services are served over HTTPS on port 443.

Back up the cache and configuration. The layer configuration (geowebcache.xml) and the tile blob store both live under /var/lib/geowebcache. Snapshot the disk or back up that directory to preserve your configuration and cached tiles.

Keep the admin password safe. The per VM password is in /root/geowebcache-credentials.txt (root only). It is the geowebcache administrator used for REST, seeding, truncation and reconfiguration.

Updates. The image ships with unattended security upgrades enabled for the operating system. GeoWebCache 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 GeoWebCache on Azure, contact the cloudimg team.