This section describes how to get started quickly with GeoWebCache without knowing much about the Configuration.

All servers that conform to the OGC Web Map Service specification must publish what is known as a capabilities document (sometimes also known as a GetCapabilities document after the request used to fetch it). This is an XML file that describes every layer that is available to the user. GeoWebCache can use this information to configure itself automatically.

View preconfigured layers

GeoWebCache comes preconfigured with three layers. To view them, navigate to your GeoWebCache demo page at http://GEOWEBCACHE_URL/demo (often this is http://localhost:8080/geowebcache/demo). Click on any of the links next to the OpenLayers column.

These layers are all served from the WMS available at http://demo.opengeo.org/geoserver/.

Layer Name (Title) WMS layer(s)
img states nurc:Img_Sample,topp:states
raster test layer nurc:Img_Sample
topp:states topp:states


This information is set in the geowebcache.xml file, which is typically available at opt/apache-tomcat-6.0.29/webapps/geowebcache/WEB-INF/classes or C:\Program Files\Apache Software Foundation\Tomcat 6.0.29\webapps\geowebcache\WEB-INF\classes. See the section on Configuring Layers for more information on customizing this file.

View layers from a WMS

The file geowebcache-core-context.xml is a configuration file that controls how the application is loaded. It is located inside the WEB-INF folder, typically /opt/apache-tomcat-6.0.29/webapps/geowebcache/WEB-INF/ or C:\Program Files\Apache Software Foundation\Tomcat 6.0.29\webapps\geowebcache\WEB-INF along with many other configuration files.

  1. Open geowebcache-core-context.xml in a text editor.


    If using Windows, it is recommended to use an enhanced text editor such as Notepad++ or jEdit instead of the standard Windows Notepad.

  2. Find the block beginning with:

    <bean id="gwcWMSConfig" class="org.geowebcache.config.GetCapabilitiesConfiguration">

    On the second line you will see a value that contains a URL:

    <constructor-arg value="http://localhost:8282/geoserver/wms?request=getcapabilities&amp;version=1.1.0&amp;service=wms" />
  3. Replace the value with a URL pointing to a valid WMS capabilities document, such as:

    <constructor-arg value="http://demo.opengeo.org/geoserver/ows?service=WMS&amp;request=GetCapabilities&amp;version=1.1.0" />


    The ampersand sign, & has to be written out as &amp; in XML files. Also, make sure to omit the line breaks.

  4. Since GeoWebCache is not configured to look to a WMS by default, we need to enable this. Find the block beginning with:

    <bean id="gwcTLDispatcher" class="org.geowebcache.layer.TileLayerDispatcher">
  5. Inside the constructor-arg <list> locate the line that says:

    <!-- ref bean="gwcWMSConfig" / -->

    and uncomment the line

    <ref bean="gwcWMSConfig" />


    The line immediately underneath this, <ref bean="gwcXmlConfig" />, is what loads the three layers as mentioned in the View preconfigured layers section. Commenting this line out will remove those layers from the layer list.

  6. Save the file and reload the servlet using Tomcat’s Manager, or by restarting the servlet container.

  7. Navigate to or reload your GeoWebCache demo page. You should see the list of layers as advertised in the WMS capabilities document.

Special cases

The following are some extra parameters may need or want to add to get your WMS layers loading properly in GeoWebCache.

Map vendor parameters

If your WMS server requires additional vendor parameters to be passed with every request, such as MapServer’s map argument, set this in the fifth constructor-arg value. Replace:

<constructor-arg value=""/>


<constructor-arg value="map=name&amp;otherkey=othervalue"/>

Other image formats

To get 24 bit PNGs from MapServer or ArcIMS (image/png; mode=24bit and image/png24 respectively), or any other image format, you will need to specify those as output formats. This is set in the fourth constructor-arg value. Replace:

<constructor-arg value="image/png,image/jpeg"/>


<constructor-arg value="image/png; mode=24bit,image/png24,image/jpeg"/>

Other MIME types can be specified here as well.

Metatile factor

It is possible to change the metatiling factor by changing the third constructor-arg value. This will affect all layers derived from this document. See the Metatiles section for more information.

Multiple capabilities documents

GeoWebCache can be configured from multiple capabilities documents. To do this, you can duplicate the gwcWMSConfig bean, change the id, and add it to the list inside the gwcTLDispatcher bean, for example:

<bean id="gwcTLDispatcher" class="org.geowebcache.layer.TileLayerDispatcher">
  <constructor-arg ref="gwcGridSetBroker"/>
      <ref bean="gwcWMSConfig"/>
      <ref bean="gwcWMSConfig2"/>
      <ref bean="gwcWMSConfig3"/>

Additional information

All layers known to GeoWebCache should be available on the demo page, along with automatically configured OpenLayers clients. The KML demos use the same sets of tiles as the OpenLayers EPSG:4326 demo.

According to the WMS standard, the capabilities document is only guaranteed to contain the WGS84 (lat/lon) bounds for a layer, hence EPSG:4326, though in rare cases the WMS server will not be able to provide responses for this projection. If the capabilities document contains bounding boxes for additional projections, often the native reference system for the data, then these will be included as well. Finally, GeoWebCache will convert the EPSG:4326 bounding box to spherical mercator (EPSG:900913, now officially known as EPSG:3857). That said, the WMS server isn’t guaranteed to be able to provide a successful response to these requests.

If you need to support other projections, you can do so by defining grid sets manually and adding them to these layers. The same is true for supporting specific resolutions, output formats or tile sizes. See the Configuration section for more information.