= Installation von !GeoWebCache =

[wiki:configuration en]

'''Dies ist eine angefangene Übersetzung der englischsprachigen Originalseite'''

== Vorwort ==

Zwei Versionen von !GeoWebCache existieren:
  * Standalone version, die du von dieser Seite downloaden kannst. Sie kann mit jedem WMS 1.1.x fähigen Server verwendet werden. Diese Seite beschäftigt sich hauptsächlich mit dieser Version.
  * !GeoWebCache ist in GeoServer 1.7.1a und höher enthalten. Diese Version ist etwas einfacher zu benutzen mit !GeoServer, und reduziert etwas die memory footprint. Beachte, dass du $GEOSERVER_DATA_DIR/gwc/geowebcache.xml hinzufügen kannst um die gleiche Flexibilität zu erhalten wie unten beschrieben. Siehe dazu auch http://geoserver.org.

== 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

= Konfiguration !GeoWebCache =

== Überblick ==
Es gibt drei Komponenten zum Konfigurieren von !GeoWebCache. Die folgenden Pfade gehen davon aus, dass das .war-File neben dem Servlet-Kontainer ausgepackt wurde (Jetty, Tomcat or JBoss).

  * WEB-INF/web.xml
    * Das ist die Konfiguration für das servlet. Es macht ziemlich wenig, aber du kannst bestimmen, wo GWC seinen Speicher anlegen soll.
  * WEB-INF/geowebcache-servlet.xml
    * Diese Datei wird vom Spring framework genutzt, um Javaklassen zu nehmen und die Anwendung zu generieren, die du als GWC kennst. Das wichtigste, dass du vielleicht hierdrin ändern möchtest ist, wo GWC die Konfigurationsdatei erwartet, oder fest zu legen, dass sie automatisch über das WMS-capabilities-Dokument generiert wird. In der Zukunft wirst du auch fähig sein neue Dienste als beans hinzuzufügen.
  * WEB-INF/classes/geowebcache.xml
    * Dies ist die Haupt-Konfigurationsdatei für manuell definierte Layer. Falls du !TileCache gewohnt bist, musst du dich wahrscheinlich nicht groß umgewöhnen.
  * WEB-INF/users.properties
    * Diese Datei steuert, wer seeden darf und wer das RESTful-Interface benutzen darf. Du gibst einen User per Zeile ein. Das Format ist {{{ username=password,ROLE_ADMINISTRATOR }}}

== web.xml ==
Du kannst optional bestimen, wo GWC den Cache für die Layer speichern soll, bei denen es nicht explizit definiert ist. Z.B:

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

Seit GeoWebCache 1.1.3 kann man auch GWC_BLANK_TILE_PATH definieren, welches eine PNG-Datei sein soll, die erzeugt wird, wenn ein Request für eine Kachel sich außerhalb der Abgrenzung befindet. Es ist ebenfalls möglich GWC_METASTORE_DISABLED auf TRUE zu setzen. Dies unterbindet den H2-Datastore, was praktisch sein kann, wenn man mehrere GWC-Instanzen gegen das selbe Verzeichnis laufen lässt. However, this will also disable modifiable parameters and future improvements.

== geowebcache-servlet.xml ==
Bitte die Kommentare in der Datei ansehen. Bei {{{<list>...<list>}}} it is possible to pass in several variables. Aufpassen mit Log, wenn Du Änderungen in der Datei machst, beim Starten und bei den ersten wenigen Requests.

Wenn Du möchtest, dann kannst du !GeoWebCache versuchen lassen sich eigenständig gegen ein WMS-GetCapabilities-Dokument zu konfigurieren. Der Nachteil ist die reduzierte Kontrolle, jeder Layer wird in EPSG:4326 und EPSG:900913 verfügbar gemacht. Um das zu tun, öffne geowebcache-servlet.xml und ändere das Folgende:

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 ==
Dies ist die Datei, in der Du manuell Layer konfigurieren kannst. Es ist eine kommentierte XML-Datei, bitte öffne sie in Deinem bevorzugtem Editor. Wenn Du einen neuen Layer anlegen möchtest, empfehl ich Dir ein Beispiel zu kopieren und abzuändern. Wir hoffen, Du hast ein hübsches AJAX-basierendes Konfigruationssytem bereit für 1.0, wir hatten sie aber nicht und wir denken, Du wirst es gut meistern.

Beachte, dass du einen XML-Editor wie jEdit oder das Plugin für Eclipse benutzen kannst, um automatsch die Online-XSD zu checken um Fehler abzufangen.

Die Basisstruktur der Datei , es gibt derzeit keinen serverweiten Einstellungen in der Datei:
{{{ 
<?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>
}}}


Dies ist die Minimalkonfiguration eines Layers. Sie bietet EPSG:4326 and EPSG:900913, in PNG und JPEG an:
{{{
<wmsLayer>
  <name>some:layer</name>
  <wmsUrl>
    <string>http://sigma.openplans.org/geoserver/wms</string>
  </wmsUrl>
  <wmsLayers>topp:states</wmsLayers>
</wmsLayer>
}}}


In den meisten Fällen möchtest Du jedoch auch das Gitter definieren:
{{{
<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>
}}}

Du kannst auch  {{{<zoomStart>...</zoomStop>}}} ersetzen mit etwas wie
{{{
        <resolutions>
          <double>15000.0</double>
          <double>12000.0</double>
          <double>4000.0</double>
        </resolutions>
}}}
um bestimmte Auflösungen zu unterstützen. Eine Auflösung wird über Koordinatensytem-Einheiten/-Pixel definiert. Wenn die Kachel 180 Grad breit und 256 Pixel breit ist, wäre die Auflösung 180.0 / 256 = 0.703125. Beachte, dass das auch bei Demos angeboten wird, aber die OpenLayers-Clients können Dir abverlangen rein und raus zu zoomen, bevor diese Einstellungen übernommen werden.

Dies ist eine umfangreiche Definition eines Layers:
{{{
<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>
}}}

Siehe unter [http://geowebcache.org/trac/browser/trunk/geowebcache/src/main/resources/geowebcache.xml geowebcache.xml] nach den Defaults und weiteren Beispielen.

= Logging =
Dieser Abschnitt ist derzeit undokumentiert, siehe log4j.properties oder frage nach Hilfe auf der Mailingliste