Cache & Tile Management

Optimize rendering performance with GeoServer's integrated tile caching, XYZ/WMTS slicing, and distributed storage backends. Pre-render spatial data for low-latency map consumption.

📅 Updated: 2025-09-14 ⏱️ Read time: 8 min 🔗 Compatible: GeoServer 2.20+

Overview

GeoServer's tile caching system intercepts map render requests and stores pre-generated image tiles on disk or in distributed storage. Subsequent requests for the same tile at a specific zoom level and coordinate are served directly from cache, bypassing expensive vector rendering and data I/O.

ℹ️

Cache performance scales linearly with storage I/O throughput. SSD/NVMe storage or S3-compatible object stores are strongly recommended for production deployments.

Tile Architecture

Tiles are organized in a pyramid structure following the Slippy Map standard. Each level represents a zoom factor, with tiles typically rendered at 256×256 or 512×512 pixels.

Zoom Levels: Z1 → Z5 (Cache Hit/Miss State)

Cache Hit

Cache Miss / Pruned

Each tile is addressed via {z}/{x}/{y}.{ext} paths. The cache layer tracks metadata including last access time, generation timestamp, and source layer versions to ensure data consistency.

Supported Formats

Format	Compression	Transparency	Recommended Use
`PNG8`	Lossless	Yes (Indexed)	Vector overlays, symbology, categorical data
`JPEG`	Lossy (70-85%)	No	Raster basemaps, satellite imagery, elevation
`WebP`	Lossy/Lossless	Yes	Modern web clients, bandwidth optimization
`GeoTIFF`	Lossless/Deflate	Yes	Offline processing, analysis, high-precision workflows

Format selection is configurable per layer or layer group. WebP is recommended for public-facing web maps, while PNG8 remains the default for maximum compatibility.

Configuration

Cache settings can be managed via the Web UI, REST API, or direct XML configuration. The REST approach is recommended for CI/CD pipelines.

POST /geoserver/rest/tilelayers/{name}/tilecache.xml

<TileLayer>
  <name>us-topo-v3</name>
  <provider>
    <GridSet>EPSG:4326</GridSet>
    <Format>image/png8</Format>
    <CacheSize>5000000</CacheSize>
    <ExpirationPolicy>
      <default>P30D</default>
      <minZoom>1</minZoom>
      <maxZoom>12</maxZoom>
    </ExpirationPolicy>
  </provider>
  <TileLayerInfo>
    <enabled>true</enabled>
  </TileLayerInfo>
</TileLayer>

Edit ${GEOSERVER_DATA_DIR}/tilecache/tilecache.xml to configure global fallback policies, default grid sets, and storage backends. Changes require a service restart.

Navigate to Layer Groups → [Select] → Tile Caching. Enable caching, set the grid set (EPSG:900913 recommended for web), configure format, and define tile size. Use the "Seed/Truncate" button to manage cache population.

Seed & Prune Operations

Cache seeding pre-renders tiles for defined bounding boxes and zoom ranges. Pruning removes tiles outside defined boundaries or older than retention policies.

Seed Command (CLI)

geoserver-cache-seed --layer us-topo-v3 \
  --grid EPSG:4326 \
  --zoom-min 5 --zoom-max 12 \
  --bbox -180,-90,180,90 \
  --threads 8 \
  --format PNG8

⚠️

Seeding is CPU-intensive. Run during off-peak hours and monitor JVM heap usage. Consider distributed seeding for large coverage areas.

Distributed Caching

GeoServer supports multiple-node caching architectures. Supported backends include:

Geoserver-TileLayer (Disk): Local filesystem with shared NFS/GlusterFS mounts
S3/MinIO: Object storage with automatic lifecycle policies
Redis/Memcached: In-memory layer for hot tiles (TTL-based)
CDN Integration: CloudFront/Cloudflare edge caching with cache-key invalidation

Distributed setups require consistent grid set definitions across all nodes. Tile invalidation is handled via version tags or cache-control headers.

Performance Tuning

Parameter	Default	Optimized (High Traffic)
`maxRenderedCacheSize`	5000	15000-25000
`threadPoolSize`	4	8-16 (CPU cores)
`tileCacheDir`	${GEOSERVER_DATA_DIR}	/mnt/nvme/tiles (SSD)
`compressionLevel`	6	4 (speed vs size tradeoff)
`maxConcurrentRequests`	100	500-1000

Monitor cache hit ratios via /geoserver/web/monitor/tilecache. A healthy production cache maintains >85% hit rate for active viewport tiles.

Troubleshooting

Symptom: Cache misses increasing despite high traffic.

Causes: Grid set mismatch, incorrect bounding box, tile size mismatch, or expiration policy too aggressive.

Resolution: Verify WMTS/XYZ requests match the configured grid. Use the Tile Cache monitor to inspect active tiles. Clear cache if symbology changed without invalidation.

Symptom: High disk I/O during seeding.

Resolution: Reduce concurrent threads, switch to S3 backend, or pre-warm on staging infrastructure before production cutover.