GeoWebCache

Installing GeoWebCache

Foreword

Two editions of GeoWebCache exist:

  • Standalone version, which you can download from this page. It can be used with any WMS 1.1.x compliant server. This page mainly concerns itself with this version.
  • GeoWebCache is included with GeoServer 1.7.1a and greater. This version is just slightly easier to use with GeoServer, and reduces memory footprint somewhat. Note that you may add $GEOSERVER_DATA_DIR/gwc/geowebcache.xml to gain the same flexibility as described below. See http://geoserver.org for details.

Standalone

The standalone version of GeoWebCache is distributed as a .war (Web ARchive) file made for J2EE containers such as Tomcat or JBoss. It is built using Sun Java 1.5, but best performance is achieved by using a Sun Java 1.6 JRE.

In Tomcat you can upload the .war 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

To get a quick overview of the data that has been configured, and what services are offered, you should point your browser to http://localhost:8080/geowebcache/demo

Configuring GeoWebCache

Overview

There are three 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.
  • WEB-INF/geowebcache-servlet.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 a configuration file, or tell it to configure itself automatically from a WMS capabilities document. In the future you will also be able to add new services by defining them as beans.
  • WEB-INF/classes/geowebcache.xml
    • This is the main configuration file for manually defined layers. If you are coming from TileCache, this is probably where you want to start looking.
  • WEB-INF/users.properties
    • This file controls who is allowed to seed and use the RESTful interface. You put one user per line, the format is: username=password,ROLE_ADMINISTRATOR

web.xml

You can optionally define where GWC should store the cache for the layers where this is not explicitly defined. For example 

<context-param>
  <param-name>GEOWEBCACHE_CACHE_DIR</param-name>
  <param-value>C:/geowebcache</param-value>
</context-param>

As of GeoWebCache 1.1.3 you can also define GWC_BLANK_TILE_PATH , which should be a PNG file that is rendered when a request for a tile is out of bounds. It is also possible to define GWC_METASTORE_DISABLED as TRUE. This will disable the H2 datastore, which can be be handy if you run multiple GWC instances against the same directory. However, this will also disable modifiable parameters and future improvements.

geowebcache-servlet.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.

If you like, you can have GeoWebCache attempt to configure itself automatically against a WMS GetCapabilities document. The downside is reduced control, every layer will be made available in EPSG:4326 and EPSG:900913. To do this, open geowebcache-servlet.xml and change the following:

1) Open WEB-INF/geowebcache-servlet.xml and look for an XML element with id="gwcWMSConfig". This bean has five constructor arguments, note that all & characters must be rewritten as &amp;

  • The cache factory. Do not change it.
  • The URL to a valid WMS 1.1.0 getcapabilities document. This is the one you want to change. Note that
  • The supported formats. You can change this if you like.
  • The metatiling factor. You may want to increase this to 4x4.
  • Any additional parameters you want to be sent with every request. For example format_options=regionate_by:auto&amp;bgcolor=0x112233
  • Whether to allow uncached connections to the backend.

2) Restart GeoWebCache , and go to http://localhost:8080/geowebcache/demo to verify that the layers have been loaded. Check the logs of your container, like catalina.out, if they do not show up.

geowebcache.xml

This is the file where you can manually configure layers. It is a commented XML file, please open it in your favorite texteditor and follow along. If you would like to add a new layer, I recommend you copy one of the sample ones and modify it. We were hoping to have a nice AJAX based configuration system ready for 1.0, but we don't and we think you'll manage just fine.

Note that you can use an XML editor like jEdit or the plug-in for Eclipse to automatically check the online XSD and catch mistakes.

Basic structure of the file, there are currently no server wide settings in this file: 

<?xml version="1.0" encoding="utf-8"?>
<gwcConfiguration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
                  xsi:noNamespaceSchemaLocation="http://geowebcache.org/schema/1.1.3/geowebcache.xsd" 
                  xmlns="http://geowebcache.org/schema/1.1.3">
<version>1.1.3</version>
<backendTimeout>120</backendTimeout>
<cacheBypassAllowed>false</cacheBypassAllowed>
<layers>
<wmsLayer>
... definition of layer 1 ...
</wmsLayer>
<wmsLayer>
... definition of layer 2 ...
</wmsLayer>
</layers>
</gwcConfiguration>

The following is a minimal definition of a layer. This will support EPSG:4326 and EPSG:900913, for PNG and JPEG: 

<wmsLayer>
  <name>some:layer</name>
  <wmsUrl>
    <string>http://sigma.openplans.org/geoserver/wms</string>
  </wmsUrl>
  <wmsLayers>topp:states</wmsLayers>
</wmsLayer>

However, in most cases you will also want to define the grid: 

<wmsLayer>
  <name>some:layer</name>
  <grids>
    <entry>
      <srs>
        <number>2163</number>
      </srs>
      <grid>
        <srs>
          <number>2163</number>
        </srs>
        <!-- If in doubt, set dataBounds and gridBounds to be the same -->
        <dataBounds>
          <coords>
            <double>-2495667.977678598</double>
            <double>-2223677.196231552</double>
            <double>3291070.6104286816</double>
            <double>959189.3312465074</double>
          </coords>
        </dataBounds>
        <gridBounds>
          <coords>
            <double>-2495667.977678598</double>
            <double>-2223677.196231552</double>
            <double>3291070.6104286816</double>
            <double>959189.3312465074</double>
          </coords>
        </gridBounds>
        <zoomStart>0</zoomStart>
        <zoomStop>25</zoomStop>
      </grid>
    </entry>
  </grids>
  <wmsUrl>
    <string>http://sigma.openplans.org/geoserver/wms</string>
  </wmsUrl>
  <wmsLayers>topp:states</wmsLayers>
</wmsLayer>

You can also replace <zoomStart>...</zoomStop> with something like 

        <resolutions>
          <double>15000.0</double>
          <double>12000.0</double>
          <double>4000.0</double>
        </resolutions>

to support specific resolutions. Note that these are also supported by the demos, but the OpenLayers client may require you to zoom in and out before it actually picks up on these settings.

The following is an extensive definition of a layer: 

<wmsLayer>
  <!-- The name of the layer that GeoWebCache will respond to. This value may contain commas, emulating multiple layers. -->
  <name>some:layer</name>
  <!-- The MIME formats that this set of tiles will support. Must be internally supported. -->
  <mimeFormats>
    <string>image/png</string>
    <string>image/jpeg</string>
  </mimeFormats>
  <!-- The format modifier below requests PNG files from the WMS server
         and then compresses those tiles to JPEG to avoid repeated compression.
         Transparency is disabled and the background set to grey, since the
         JPEG encoder would not know how to treat the alpha channel. -->
  <formatModifiers>
    <formatModifier>
      <!-- Mandatory, the format requested by client -->
      <responseFormat>image/jpeg</responseFormat>
      <!-- Optional, the format GWC will use to get metatiles from backend,
        This allows you to avoid lossy compression, such as JPEG, to be
        applied twice. Use image/png; mode=24bit for MapServer -->
      <requestFormat>image/png</requestFormat>
      <!-- Optional, override transparent parameter in WMS request -->
      <transparent>false</transparent>
      <!-- Optional, override or set backgroud color for WMS request.
             The following uses a light grey background -->
      <bgColor>0xDDDDDD</bgColor>
      <!-- Optional, override or set palette parameter for WMS request -->
      <palette>webSafePalette</palette>
      <!-- Optional, adjust the compression ratio used when saving
        the tiles. For minimum compression use 1.0 -->
      <compressionQuality>1.0</compressionQuality>
    </formatModifier>
  </formatModifiers>
  <!-- The following are the grid definitions. You need one entry for every SRS -->  
  <grids>
    <entry>
      <!-- This is actually the dump of a hash table, so the SRS shows up in both the key and the value -->
      <srs>
        <number>2163</number>
      </srs>
      <grid>
        <srs>
          <number>2163</number>
        </srs>
        <!-- This defines the extent of your data and prevents GeoWebCache from 
             requesting blank tiles from the backend, thereby saving storage and
             responding faster. -->
        <dataBounds>
          <coords>
            <double>-2495667.977678598</double>
            <double>-2223677.196231552</double>
            <double>3291070.6104286816</double>
            <double>959189.3312465074</double>
          </coords>
        </dataBounds>
        <!-- Grid bounds define the origin and extent of the grid, they ultimately
             determine what indexes GWC uses for each tile internally. If the SRS
             has a natural "maximum extent", like -180.0,-90.0,180.0,90.0 , then
             that's a good value to use. Otherwise use the max extent that your data
             could possibly grow to. If in doubt, just copy the coords from dataBounds. -->
        <gridBounds>
          <coords>
            <double>-2495667.977678598</double>
            <double>-2223677.196231552</double>
            <double>3291070.6104286816</double>
            <double>959189.3312465074</double>
          </coords>
        </gridBounds>
        <zoomStart>0</zoomStart>
        <zoomStop>25</zoomStop>
      </grid>
    </entry>
  </grids>
  <!-- The following are the URLs to the WMS backend servers. If you specify more
       than one they will be used in a round robin fashion. -->
  <wmsUrl>
    <string>http://sigma.openplans.org/geoserver/wms</string>
    <string>http://atlas.openplans.org/geoserver/wms</string>
  </wmsUrl>
  <!-- This is the name of the WMS layer(s) requested from the backend server.
       Note that this value allows commas, so you can request multiple layers as one. -->
  <wmsLayers>topp:states</wmsLayers>
  <wmsStyles>polygon</wmsStyles>
  <!-- These are the metatiling factors. Larger values reduce label duplication, 
       but also require more memory during processing. It is recommended 
       that width and height be kept the same. -->
  <metaWidthHeight>
    <int>3</int>
    <int>3</int>
  </metaWidthHeight>
  <!-- With metatiling enabled, this value should in most cases be false -->
  <tiled>false</tiled>
  <!-- Transparent tiles are requested by default. -->
  <transparent>true</transparent>
  <!-- The background color. Only applicable when transparent is false or
  in combination with formats that do not support transparency, such as JPEG -->
  <bgColor>0x112233</bgColor>
  <!-- Palette file to be used by the backend -->
  <palette>test_palette</palette>
  <!-- Vendor parameters are appended to every request to the backend -->
  <vendorParameters>foobar1=TRUE&amp;foobar2=FALSE</vendorParameters>
  <!-- Expire header sent to clients. Default is to reuse the value from the 
       backend or, if this is not available, to use 2 hours -->
  <expireClients>240</expireClients>
  <!-- Backend timeout. This is how long GWC will wait for the WMS backend to respond -->
  <backendTimeout>235</backendTimeout>
  <!-- Services like Virtual Earth and Google Maps can be used as uncached translators,
       if the clients append cached=false&metatiled=true (or false) to their request. -->
  <cacheBypassAllowed>false</cacheBypassAllowed>
</wmsLayer>

See the default geowebcache.xml for further examples.

Logging

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