Installing GeoWebCache

Installing GeoWebCache ¶

Standalone ¶

GeoWebCache is distributed as a .war file made for J2EE containers such as Tomcat or JBoss.

In Tomcat you can upload this file through the Tomcat Manager interface, http://localhost:8080/manager/html , and it should start automatically. Alternatively the file (which is a regular .zip file) can be unpacked in a new directory and then moved to the webapps directory.

See the documentation of your container for details.

If you have the build environment (Maven and Java Developer Kit), you can start an instance of Jetty by running mvn install jetty:run

GeoWebCache will answer WMS request for tiles through http://localhost:8080/geowebcache/service/wms?

GeoServer Extension (NEW!) ¶

GeoWebCache is also distributed as an extension for GeoServer. (Go to the GeoServer download page.)
Note the GeoServer extension will automatically generate 4x4 metatiles from a 1024x1024px image, this can not be changed.

Configuring GeoWebCache ¶

The following does not apply to the 1.0 versions! Please edit geowebcache.xml in the resource folder or contact us if you have questions. We will be happy to help, the documentation will be updated in advance of the 1.0 release.

Overview ¶

There are four components to configuring GeoWebCache. The paths below assume that the .war file has been unpacked by the servlet container (Jetty, Tomcat or JBoss).

• WEB-INF/web.xml
  • This is the configuration for the servlet. It does very little, but you can define where GwC should store its cache here.
• WEB-INF/classes/applicationContext.xml
  • This file is used by the Spring framework to take Java classes and create the application you know as GWC. The main thing you may want to change in here is where GWC looks for configuration files (see the next two bullet points). In the future you will also be able to add new services by defining them as beans.
• WEB-INF/classes/layer_*.properties
  • By default, GWC will search the classpath for files of the form layer_name.properties and parse these to add layers. The path(s) to be searched are configured through applicationContext.xml. It should be noted that the GeoServer extension does not use the *.properties file it only uses GetCapabilities?.
• WMS GetCapabilities
  • If defined in applicationContext.xml, GWC can make a GetCapabilities request to a WMS server and automatically configure all layers it finds.

web.xml ¶

The only thing you should change in here is optionally define where GWC should store the cache for the layers where this is not explicitly defined.

applicationContext.xml ¶

Please see comments in the file. Where you see <list>...<list> it is possible to pass in several variables. Pay close attention to the log if you make changes to this file, both during startup and the first few requests.

.properties files ¶

The property files contain variables similar to those used in WMS requests. The examples below are for GeoWebCache 0.8.0:

Example 1: layer_states.properties ¶

This file will result in a new layer called "states" (based on the filename of the .properties file). It will serve tiles from http://localhost:8080/geoserver/wms?layers=topp:states and support EPSG:4326 and the PNG format (transparent). Each request will also return headers hat allow you debug any problems.

type=wms

# Backend
wmsurl=http://localhost:8080/geoserver/wms
wmslayers=topp:states

# Tile profile
mimetypes=image/png
srs=EPSG:4326
grid=-180.0,-90.0,180.0,90.0;
bbox=-124.0,22.0,-66.0,72.0;

width=256
height=256
version=1.1.0
errormime=application/vnd.ogc.se_inimage
tiled=false
transparent=true
metatiling=3x3
debugheaders=true

Example 2: layer_states2.properties ¶

This example is similar to above, but supports both JPEG and PNG, serves the layer topp:states and has debugging turned off.

#Type, determines configuration parser
layername=topp:states
type=wms

# Backend
wmsurl=http://localhost:8080/geoserver/wms
wmslayers=topp:states

# Tile profile
mimetypes=image/png,image/jpeg
srs=EPSG:4326
grid=-180.0,-90.0,180.0,90.0
bbox=-124.0,22.0,-66.0,72.0;

width=256
height=256
version=1.1.0
errormime=application/vnd.ogc.se_inimage
tiled=false
transparent=true
metatiling=3x3
debugheaders=false

Example 3: layer_states3.properties ¶

This example is similar to above, but serves the layer topp:states2 and, supports 4326 and 900913 and specifies where to store the cache explicitly.

#Type, determines configuration parser
layername=topp:states2
type=wms

# Backend
wmsurl=http://localhost:8080/geoserver/wms
wmslayers=topp:states

# Tile profile
mimetypes=image/png,image/jpeg
srs=EPSG:4326;EPSG:900913
grid=-180.0,-90.0,180.0,90.0;-20037508.34,-20037508.34,20037508.34,20037508.34
bbox=-124.0,22.0,-66.0,72.0;-20037508.34,-20037508.34,20037508.34,20037508.34

width=256
height=256
version=1.1.0
errormime=application/vnd.ogc.se_inimage
tiled=false
transparent=true
metatiling=3x3
debugheaders=false

# Cache backend settings
cacheprefix=/tmp/geowebcache/states
# cacheprefix=c://geowebcache

Configuration parameters for .properties files ¶

Here is a list of the various parameters, subject to change, and what their default values are.

• imagemimes
  • a comma-separated list of supported MIME-types, if you want all of them: image/jpeg,image/png,image/gif,image/tiff
  • default: image/png
• wmsurl
  • the address of the WMS server, can also be a comma-separated list of WMS servers
  • default: n/a
• wmslayer
  • a comma separated list of layers to request from the WMS server
  • default: n/a
• wmsstyles
  • the styles parameter sent to the WMS server
  • default: <blank>
• grid
  • the bounding box for the underlying grid, used to calculate cache keys. Should be the bounds of the coordinate system
  • default: 180.0,-90.0,180.0,90.0 if the SRS is EPSG:4326, -20037508.34,-20037508.34,20037508.34,20037508.34 if it is EPSG:900913
  • Can be a semicolon-separated list of grids
• bbox
  • the bounding box to which the cache will respond, after rounding to the closest metatile
  • default: the grid bounding box
  • Can be a semicolon-separated list of bounds
• srs
  • the spatial reference system
  • default: EPSG:4326
  • Can be a semicolon-separated list of SRSs
• width
  • the width of a tile in pixels
  • default: 256
• height
  • the height of a tile in pixels
  • default: 256
• version
  • the WMS version for backend queries. Does not currently affect how GeoWebCache queries the backend, but it will forward this version number.
  • default: 1.1.0
• errormime
  • the error MIME sent to the backend WMS server.Does not currently affect how GeoWebCache queries the backend, but it will forward this MIME.
  • default: application/vnd.ogc.se_inimage
• tiled
  • A hint for the backend WMS server that the requests come from a tiling client. If you set metatiling to something other than 1x1, this should generally be set to false.
  • default: false
• transparent
  • whether the client desires transparent tiles, if the specified format supports it
  • default: false
• metatiling
  • whether GeoWebCache should request metatiles and and split them into the correct tilesize. This reduces labeling problems, but increases the size of the images requested from the WMS backends.
  • default: 1x1
• debugheaders
  • appends HTTP headers with some debug information to every single response. This may help debugging, but should normally be left off to reduce bandwidth consumption and parsing on the client.
  • default: false
• expireclients
  • the expiration header sent to clients with every tile from this layer, in seconds.
  • default: Use value from WMS backend, alternatively 6 hours if this value is not available
• expirecache
  • the expiration time in seconds for tiles, measured from the time they are sent to the cache backend. Not all backends support this.
  • default: never expire
• cachetype
  • the type of cache to be used. Currently only org.geowebcache.cache.file.FileCache and org.geowebcache.cache.jcs.JCSCache are supported
  • default: org.geowebcache.cache.file.FileCache
• cacheprefix
  • A prefix for the cache, such as filepath or other keys. You have to escape /, e.g. c://temp//test
  • default: %GEOWEBCACHE_CACHE_DIR%/layername
• zoomstart
  • the starting "zoom level"
  • default: 0, meaning two tiles to display the world in EPSG:4326 or one tile in EPSG:900913
• zoomstop
  • the stopping "zoom level"
  • default: 25, meaning you can "zoom in" (double the resolution) 25 times
• vendorparameters (added in 0.7.2)
  • vendor specific parameters appended to every request, example: vendorparameters=key1=value1&key2=value2}
  • default: none

Configuration options specific to FileCache

• filecachepath - DEPRECATED - USE cacheprefix instead

Using GeoWebCache ¶

After creating / updating the layer_*.properties files you have to restart GeoWebCache. It should then respond like any tiling WMS server through http://localhost:8080/geowebcache/service/wms

If you need a client to test, modify index.html in the exploded war-file. It is a minimal OpenLayers client.

Logging ¶

This section is currently undocumented, see log4j.properties or ask for help on the mailing list.