Operate GeoServer: upgrades, recovery and diagnosis

A GeoServer backup is useful when another operator can restore the service and its data relationships. Copying a WAR file or container image does not recover stores, styles, security configuration, database contents, external rasters or secrets. Define recovery around a working consumer task.

Specify the recovery target

Choose an acceptable data-loss window and an acceptable service-restoration time with the business owner. These are requirements, not values inferred from how often a backup happens. A daily backup can lose nearly a day of edits; a large restore may take longer than the business can tolerate even when the backup completed successfully.

Inventory the components needed to draw and query a representative layer:

Component	What must be recoverable	Common omission
GeoServer runtime	Exact release and compatible extensions	Plugin versions absent from inventory
Data directory	Catalog, styles and security configuration	Copy taken during inconsistent writes
Database	Data, schema, roles and required extensions	Only application configuration saved
External files	Rasters, fonts, shapefiles and supporting files	Absolute path unavailable on new host
Secrets	Authorized retrieval procedure	Encrypted values restored without required keys
Proxy and identity	Routes, certificates and provider configuration	Internal URLs work; public clients fail
Cache	Rebuild plan or selected backup	Empty cache overloads service after recovery

The GeoServer data directory documentation explains the configuration location. Back it up using a consistency strategy appropriate to your deployment; do not assume a filesystem copy racing administrative writes is a coherent snapshot.

Rehearse recovery on an isolated target

Select a known backup and record its date, data revision and runtime version. Restore into an isolated environment whose outgoing notifications, scheduled jobs and public DNS cannot affect production. Retrieve secrets through the approved operating mechanism; do not bundle them into a shared test archive.

Restore the database and external files, then configuration and matching extensions. Confirm ownership and filesystem permissions. Start the service and run the same WMS/WFS publication checks used during acceptance. Test a restricted layer as an unauthorized identity as well as a permitted reader. A recovery that makes every layer public is a failed recovery.

Measure elapsed time from the declared starting point to successful consumer use. Include operator preparation, file transfer, database recovery, service startup, cache warm-up and validation if those activities are part of the recovery promise. Record missing dependencies and repair the procedure while the exercise is fresh.

Upgrade a restored copy first

Read release notes and the support matrix for the exact target. Pin matching extension versions rather than mixing downloads from different releases. Review Java/container requirements, database driver compatibility and changes in security or service defaults. Keep the prior runtime and a compatible backup so rollback has a concrete starting point.

Run a small regression suite: capabilities, representative WMS image, WFS filtering/pagination, secured access, styling/fonts, REST automation and each essential desktop client. For a site with writes, include transaction behavior and read-back. Check cold-cache behavior because an upgrade can appear fast only while old cache contents hide rendering work.

Do not reverse an upgrade simply by starting an older binary over potentially changed configuration. Rehearse rollback with the compatible configuration/data snapshot and account for edits that occurred after the change. The production guidance is a reference for operational tuning, not a replacement for this deployment-specific rehearsal.

Monitor the task users actually need

Track request success and latency by operation class, database connection use, memory/garbage collection, disk capacity, cache behavior and data freshness. A process being alive does not prove a layer draws. Add one small synthetic read and one image request against a stable fixture, with expected content checks.

Signal	Investigation	Avoid
WMS slows, WFS stable	Styles, labels, render load	Increasing database resources blindly
All requests slow	CPU, memory, network and pool exhaustion	Restarting without preserving useful diagnostics
One layer fails	Source availability, schema or permission change	Treating it as total server failure
Tile cache grows rapidly	Zoom/format/parameter combinations	Adding disk without finding the cause
Data is stale but API healthy	Ingestion and publication schedule	Reporting service uptime as freshness

Build a repeatable recovery check

Maintain a small request set for the deployment's most important contracts. The following local example uses the downloadable lab layer lab:assets; change the URL and layer names for a different installation. Run against an isolated restored instance. It verifies that the restored service can return a capabilities document, a bounded feature response and an image, while leaving semantic inspection to the checks below.

Code example

curl --fail --silent --show-error --get \
  'http://localhost:8080/geoserver/lab/wfs' \
  --data-urlencode 'service=WFS' \
  --data-urlencode 'version=2.0.0' \
  --data-urlencode 'request=GetCapabilities' \
  --output restored-capabilities.xml

curl --fail --silent --show-error --get \
  'http://localhost:8080/geoserver/lab/wfs' \
  --data-urlencode 'service=WFS' \
  --data-urlencode 'version=2.0.0' \
  --data-urlencode 'request=GetFeature' \
  --data-urlencode 'typeNames=lab:assets' \
  --data-urlencode 'count=10' \
  --data-urlencode 'outputFormat=application/json' \
  --output restored-features.json

curl --fail --silent --show-error --get \
  'http://localhost:8080/geoserver/lab/wms' \
  --data-urlencode 'service=WMS' \
  --data-urlencode 'version=1.1.1' \
  --data-urlencode 'request=GetMap' \
  --data-urlencode 'layers=lab:assets' \
  --data-urlencode 'styles=' \
  --data-urlencode 'srs=EPSG:4326' \
  --data-urlencode 'bbox=-75.65,6.15,-75.54,6.26' \
  --data-urlencode 'width=512' \
  --data-urlencode 'height=512' \
  --data-urlencode 'format=image/png' \
  --output restored-map.png

A server can return an XML exception with HTTP 200. Inspect content, not only curl's exit code. Confirm that the capabilities document advertises the required layer, the JSON contains ten features with expected business identifiers and the PNG draws points in the expected extent. Query one known identifier separately and verify the data revision. A restored cache containing an old map is not proof that the underlying database is current.

The lab's recorded GeoServer checks used a local Shapefile source. They demonstrate that fixture's requests, not a PostGIS backup/restore. For a real recovery exercise, reconcile the restored source against the selected backup revision and repeat both allowed and denied access tests.

Separate routine care from change work

Operating moment	Concrete check	Response to an unexpected result
Routine service observation	Representative image and feature result, freshness, disk and errors	Identify affected layer and upstream source before changing capacity
After publishing a new layer	Permissions, column exposure, extent and request limits	Correct publication before directing consumers to it
After a style change	Dense and sparse extent at relevant scales	Restore previous style if labels or render time break the task
Before upgrading	Restore prior configuration on a separate instance	Resolve missing plugins/data before changing runtime
After a credential change	New credential works and revoked identity fails	Remove stale sessions/configuration according to the access design
During recovery rehearsal	Full consumer task and measured elapsed time	Update procedure, resources or the promised recovery target

Choose the frequency from the service's consequences and change rate. This is a work pattern, not a universal requirement for daily or weekly maintenance. Include its hours in support estimates. An organization publishing one static public layer needs a different operating arrangement from a continuously edited, restricted asset service.

When an incident affects rendering, first reproduce a small request with a known extent and simple style. If that works, vary one dimension at a time: layer, extent, output size, style or query filter. This narrows the cause more reliably than changing several resource settings at once. Preserve the failing request without tokens or private attributes, note the runtime/data revision, and confirm the fix against the original consumer before closing the incident.

Give incidents a clear owner

Document how to identify the affected layer and revision, reach the operator, disable an expensive publication, restore the previous style and communicate a known stale-data condition. Use request identifiers and coarse operational metrics; avoid logging private feature attributes or credentials.

For a managed service proposal, ask who performs patches, who approves downtime, which restore exercises are included, how incidents are escalated and how configuration/data are exported when the contract ends. “Support included” is too vague to compare costs.

A complete handover consists of a successful restore exercise, a tested upgrade/rollback procedure, an inventory of versions and dependencies, and a named operating owner. Price that work in the migration cost model; it belongs in both proprietary and open alternatives.