GeoWebCache: accelerate maps without serving stale data
Design tile matrices, extents, zoom levels and invalidation before generating millions of tiles.
Editorial review: 2026-09-23
GeoWebCache improves repeat map delivery by reusing rendered tiles. It is valuable when many readers request the same published geography and style. It does not repair an unindexed database, a slow uncached query or an application that asks for a unique map on every request.
Before tuning, make the uncached GeoServer publication correct. A cache can make an incorrect map consistently fast. Record data revision, style revision, public/private scope and acceptable staleness before generating tiles.
Choose the cacheable product
| Workload | Candidate | Why it matters |
|---|---|---|
| Public basemap updated weekly | Shared tile cache | High reuse, explicit refresh window |
| Public thematic layer updated nightly | Cache plus bounded invalidation | Readers may accept a known delay |
| Individual confidential records | Separate authorized delivery | Shared cache keys may expose another user's result |
| Constantly changing analyst filters | Direct WMS or a designed query API | Combinations can defeat reuse |
| Static vector publication | Vector tiles or PMTiles | Different rendering and update model |
Use GeoWebCache's GeoServer integration to select enabled layers, formats and gridsets. Avoid enabling every grid, format and zoom level “for flexibility”; each choice expands storage, seeding time and invalidation work.
Make the tile grid explicit
A WMTS request identifies a layer, style, format, tile matrix set, matrix, row and column. Those identifiers must agree between server and client. Inspect the capabilities document and use its advertised values. An EPSG:3857 map client does not automatically understand an arbitrary national grid.
For a regional service, constrain the geographic bounds and supported zoom range to the use case. At each additional full-world zoom level a square tile grid has roughly four times as many tiles. Actual regional counts depend on extent and grid alignment; estimate the real region rather than multiplying a guessed full-world total.
estimated bytes = tile count × measured mean bytes per tile
seed duration ≈ tile count ÷ measured sustained render rate
Measure representative urban, rural and empty tiles because their sizes and rendering costs can differ. Include output variants such as language, time or style only if consumers actually need them.
Measure cold and warm behavior separately
Choose a small fixed tile sample. Run it once against an empty or deliberately isolated test cache, then repeat the same requests. Record success rate, duration distribution, tile size, CPU, database activity and cache hit information available in your deployment. Keep concurrency and dataset version fixed.
Report both cold and warm results. A “fast” median from an already populated cache says little about a cache miss during a public incident. Compare a representative pan/zoom sequence, not only a single repeated tile. Do not publish a speedup claim without fixture, hardware, software versions, request list and raw measurements.
Design updates before seeding
There are three different changes: data updates, style updates and access-policy updates. For each, identify which tiles become stale and how quickly they must disappear. A public style revision can tolerate an announced refresh window; a permission correction may require immediate eviction and temporarily disabling delivery.
Seed a bounded area and zoom range first. Confirm visual output, disk growth and impact on the database. Expand gradually during an approved operational window. Seeding concurrency that saturates the database can hurt uncached readers and editors, so reserve capacity and provide a way to stop the job.
The GeoWebCache seeding documentation describes the administration controls. Treat a truncate operation as destructive to cache contents: target the intended layer/grid/extent, and know how it will be regenerated. Cached tiles are reproducible artifacts, but regenerating a large area can still be expensive.
Diagnose cache failures
| Symptom | Likely area to inspect | Useful evidence |
|---|---|---|
| Old colors after SLD update | Existing tile revisions | Compare direct WMS and cached tile |
| Empty tiles at some scales | Grid, bounds or scale rule | Request advertised matrix coordinates |
| Disk grows unexpectedly | Zoom range and parameter variants | Count objects by layer/grid/format |
| Warm requests still hit database | Request not eligible for cache | Compare exact URL and cache metadata |
| Private content visible across users | Cache key and authorization boundary | Two-identity test through public edge |
Do not put authentication solely in a web viewer: a user can request the tile URL directly. Follow GeoServer security and test the complete path, including CDN or reverse proxy.
The operating result should be a documented grid, allowed variants, measured storage estimate, refresh procedure and a recovery plan for an empty cache. If the product is a static vector publication, compare the PMTiles approach before maintaining a rendering service unnecessarily.