Storage¶

Additional Information:¶

The S3 objects for tiles are created with public visibility to allow for “standalone” pre-seeded caches to be used directly from S3 without geowebcache as middleware. In the future this behavior could be disabled through a configuration option.

Beware of amazon services costs. Especially in terms of bandwidth usage when serving tiles out of the Amazon cloud, and S3 storage prices. We haven’t conducted a thorough assessment of costs associated to seeding and serving caches. Yet we can provide some general purpose advise:

• Do not seed at high zoom levels (except if you know what you’re doing). The number of tiles grow exponentially as the zoom level increases.

• Use the tile format that produces the smalles possible tiles. For instance, png8 is a great compromise for quality/size. Keep in mind that the smaller the tiles the bigger the size difference between two identical caches on S3 vs a regular file system. The S3 cache takes less space because the actual space used for each tile is not padded to a file system block size. For example, the topp:states layer seeded up to zoom level 10 for EPSG:4326 with png8 format takes roughly 240MB on an Ext4 file system, and about 21MB on S3.

• Use in-memory caching. When serving S3 tiles from GeoWebcache, you can greately reduce the number of GET requests to S3 by configuring an in-memory cache as described in the “In-Memory caching” section bellow. This will allow for frequently requested tiles to be kept in memory instead of retrieved from S3 on each call.

The following is an example OpenLayers 3 HTML/JavaScript to set up a map that fetches tiles from a pre-seeded geowebcache layer directly from S3. We’re using the typical GeoServer topp:states sample layer on a fictitious my-geowebcache-bucket bucket, using test-cache as the cache prefix, png8 tile format, and EPSG:4326 CRS.

<div class="row-fluid">
  <div class="span12">
    <div id="map" class="map"></div>
  </div>
</div>

var map = new ol.Map({
  target: 'map',
  controls: ol.control.defaults(),
  layers: [
    new ol.layer.Tile({
      source: new ol.source.XYZ({
        projection: "EPSG:4326",
        url: 'http://my-geowebcache-bucket.s3.amazonaws.com/test-cache/topp%3Astates/EPSG%3A4326/png8/default/{z}/{x}/{-y}.png'
      })
    })
  ],
  view: new ol.View({
    projection: "EPSG:4326",
    center: [-104, 39],
    zoom: 2
  })
});

Additional Information:¶

The Azure objects for tiles are created with public visibility to allow for “standalone” pre-seeded caches to be used directly from Azure without GeoWebCache as middleware. If

Beware of Azure services costs. Especially in terms of bandwidth usage when serving tiles out of the Azure cloud, and Azure storage prices. We haven’t conducted a thorough assessment of costs associated to seeding and serving caches. Yet we can provide some general purpose advise:

• Do not seed at high zoom levels (except if you know what you’re doing). The number of tiles grow exponentially as the zoom level increases.

• Use the tile format that produces the smalles possible tiles. For instance, png8 is a great compromise for quality/size. Keep in mind that the smaller the tiles the bigger the size difference between two identical caches on Azure vs a regular file system. The Azure cache takes less space because the actual space used for each tile is not padded to a file system block size.

• Use in-memory caching. When serving Azure Blob tiles from GeoWebcache, you can greatly reduce the number of GET requests to Azure by configuring an in-memory cache as described in the “In-Memory caching” section below. This will allow for frequently requested tiles to be kept in memory instead of retrieved from Azure on each call.

The following is an example OpenLayers 3 HTML/JavaScript to set up a map that fetches tiles from a pre-seeded geowebcache layer directly from Azure, assuming that the container access level has been set to “public” or “blob”, so that direct access to the blobs is possible. We’re using the typical GeoServer topp:states sample layer on a fictitious my-geowebcache-container bucket, using test-cache as the cache prefix, png8 tile format, and EPSG:4326 CRS.

<div class="row-fluid">
  <div class="span12">
    <div id="map" class="map"></div>
  </div>
</div>

var map = new ol.Map({
  target: 'map',
  controls: ol.control.defaults(),
  layers: [
    new ol.layer.Tile({
      source: new ol.source.XYZ({
        projection: "EPSG:4326",
        url: 'https://<accountNameHere>.blob.core.windows.net/<containerNameHere>/<prefixIfAny>/<layerId>/EPSG:4326/png8/default/{z}/{x}/{-y}.png'
      })
    })
  ],
  view: new ol.View({
    projection: "EPSG:4326",
    center: [-104, 39],
    zoom: 2
  })
});

The prefix needs to be filled only if used otherwise that part of the path should be empty. The layerId is the layer identifier. In GWC it has been hand-assigned during configuration, if using GWC inside GeoServer it will be the internal layer identifier, e.g., something like LayerInfoImpl--5f036b28:16bbda57c0e:-7ffc which can be retrieved by checking the GeoServer configuration files for the layer in question.

File Path Templates¶

An MBTiles file will correspond to an SQLite database file. In order to limit the amount of contention on each single database file users will be allowed to decide the granularity of the databases files. When GeoWebCache needs to map a tile to a database file it will only look at the databases files paths, it will not take in account the MBTiles metadata (this is why this store is able to handle others formats and projections).

To configure the databases files granularity the user needs to provide a file path template. The default file path template for the MBTiles blob store is this one:

{layer}/{grid}{format}{params}/{z}-{x}-{y}.sqlite

This file template will stores all the tiles belonging to a certain layer in a single folder that will contain sub folders for each given format, projection and set of parameters and will group tiles with the same zoom level, column range and row range in a SQLite file. The column and row range values are passed by configuration, by default those values are equal to 250. The provided files paths templates will always be considered relative to the root directory provided as a configuration option.

Follows an example of what the blob store root directory structure may look like when using the default path template:

.
|-- nurc_Pk50095
|   `-- EPSG_4326image_pngnull
|       |-- 11_2000_1500.sqlite
|       `-- 12_4250_3000.sqlite
`-- topp_states
    |-- EPSG_900913image_jpeg7510004a12f49fdd49a2ba366e9c4594be7e4358
    |   |-- 6_250_500.sqlite
    |   `-- 7_0_0.sqlite
    `-- EPSG_900913image_jpegnull
        |-- 3_500_0.sqlite
        |-- 4_0_250.sqlite
        `-- 8_750_500.sqlite

If no parameters were provided null string will be used. Is the responsibility of the user to define a file path template that will avoid collisions.

The terms that can be used in the file path template are:

• grid: the grid set id

• layer: the name of the layer

• format: the image format of the tiles

• params: parameters unique hash

• x: column range, computed based on the column range count configuration property

• y: row range, computed based on the row range count configuration property

• z: the zoom level

It is also possible to use parameters values, like style for example. If the parameter is not present null will be used.

MBTiles Metadata¶

A valid MBTiles file will need some metadata, the image format and layer name will be automatically added when an MBTiles file is created. The user can provide the remaining metadata using a properties file whose name must follow this pattern:

<layerName>.metadata

As an example, to add metadata description and attribution entries to layer tiger_roads a file named tiger_roads.properties with the following content should be present in the metadata directory:

description=ny_roads
attribution=geoserver

The directory that contains this metadata files is defined by a configuration property.

Vector Tile Compression¶

Some non-standard MBTiles files contain vector tiles, and these are sometimes compressed using gzip. A gzipVector entry to the the store configuration with a value of true will enable this behaviour. Raster tiles will not be affected.

Expiration Rules¶

The MBTiles specification don’t give information about when a tile was created. To allow expire rules, an auxiliary table is used to store tile creation time. In the presence of an MBTiles file generated by a third party tool it is assumed that the creation time of a tile was the first time it was accessed. This feature can be activated or deactivated by configuration. Note that this will not break the MBTiles specification compliance.

Eager Truncate¶

When performing a truncate of the cache the store will try to remove the whole database file avoiding to create fragmented space. This is not suitable for all the situations and is highly dependent on the database files granularity. The configuration property eagerDelete allows the user to disable or deactivate this feature which is disabled by default.

When a truncate request by tile range is received all the the databases files that contains tiles that belong to the tile range are identified. If eager delete is set to true those databases files are deleted otherwise a single delete query for each file is performed.

Configuration Example¶

Follows as an example the default configuration of the MBTiles store:

<MbtilesBlobStore default="true">
  <id>mbtiles-store</id>
  <enabled>true</enabled>
  <rootDirectory>/tmp/gwc-mbtiles</rootDirectory>
  <templatePath>{grid}/{layer}/{format}/{params}/{z}/tiles_{x}_{y}.sqlite</templatePath>
  <rowRangeCount>250</rowRangeCount>
  <columnRangeCount>250</columnRangeCount>
  <poolSize>1000</poolSize>
  <poolReaperIntervalMs>500</poolReaperIntervalMs>
  <eagerDelete>false</eagerDelete>
  <useCreateTime>true</useCreateTime>
  <executorConcurrency>5</executorConcurrency>
  <mbtilesMetadataDirectory>/tmp/gwc-mbtiles/layersMetadata</mbtilesMetadataDirectory>
</MbtilesBlobStore>

The rootDirectory property defines the location where all the files produced by this store will be created. The templatePath property is used to control the granularity of the database files (see section above). Properties rowRangeCount and columnRangeCount will be used by the path template to compute tile ranges.

The poolSize property allows to control the max number of open database files, when defining this property the user should take in account the number open files allowed by the operating system. The poolReaperIntervalMs property controls how often the pool size will be checked to see if some database files connections need to be closed.

Property eagerDelete controls how the truncate operation is performed (see section above). The property useCreateTime can be used to activate or deactivate the insertion of the tile creation time (see section above). Property executorConcurrency controls the parallelism used to perform certain operations, like the truncate operation for example. Property mbtilesMetadataDirectory defines the directory where the store will look for user provided MBTiles metadata.

Replace Operation¶

As said before, if the cache is running SQLite files cannot be simply switched, first all connections need to be closed. The replace operation was created for this propose. The replace operation will first copy the new file side by side the old one, then block the requests to the old file, close the connections tot he old file, delete the old one, rename the new file to current one, reopen the new db file and start serving requests again. Should be almost instant.

A REST entry point for this operation is available, it will be possible to submit a ZIP file or a single file along with the request. The replace operation can also use an already present file or directory. When using a directory the directory structure will be used to find the destination of each file, all the paths will be assumed to be relative to the store root directory. This means that is possible to replace a store content with another store content (a seeded one for example) by zipping the second store root directory and send it as a replacement.

There is four ways to invoke this operation. Follows an example of all those variants invocations using CURL.

Replace a single file uploading the replacement file:

curl -u geowebcache:secured -H 'Content-Type: multipart/form-data'
  -F "file=@tiles_0_0.sqlite"
  -F "destination=EPSG_4326/sf_restricted/image_png/null/10/tiles_0_0.sqlite"
  -F "layer=sf:restricted"
  -XPOST 'http://localhost:8080/geowebcache/rest/sqlite/replace'

Replace a single file using a file already present on the system:

curl -u geowebcache:secured -H 'Content-Type: multipart/form-data'
  -F "source=/tmp/tiles_0_0.sqlite"
  -F "destination=EPSG_4326/sf_restricted/image_png/null/10/tiles_0_0.sqlite"
  -F "layer=sf:restricted"
  -XPOST 'http://localhost:8080/geowebcache/rest/sqlite/replace'

Replace multiple files uploading a ZIP file:

curl -u geowebcache:secured -H 'Content-Type: multipart/form-data'
  -F "file=@tiles.zip"
  -F "layer=sf:restricted"
  -XPOST 'http://localhost:8080/geowebcache/rest/sqlite/replace'

Replace multiple files using a directory already present on the system:

curl -u geowebcache:secured -H 'Content-Type: multipart/form-data'
  -F "source=/tmp/tiles"
  -F "layer=sf:restricted"
  -XPOST 'http://localhost:8080/geowebcache/rest/sqlite/replace'

The layer parameter identifies the layer whose associated blob store content should be replaced. The file parameter is used to upload a single file or a ZIP file. The source parameter is used to reference an already present file or directory. The destination parameter is used to define the file that should be replaced with the provided file.

This are the only valid combinations of this parameters other combinations will ignore some of the provided parameters or will throw an exception.

GuavaCacheProvider¶

GuavaCacheProvider provides local in-memory caching by using a Guava Cache for storing the various GWC Tiles locally on the machine. For configuring a GuavaCacheProvider the user must create a new bean in the Application Context file (like geowebcache-core-context.xml) and then add a reference to a CacheConfiguration instance.

Here is an example of configuration:

<bean id="cacheConfiguration" class="org.geowebcache.storage.blobstore.memory.CacheConfiguration">
  <property name="hardMemoryLimit" value="64"/> <!-- 64 Mb -->
      <property name="policy" value="EXPIRE_AFTER_ACCESS"/> <!-- Cache Eviction Policy is EXPIRE_AFTER_ACCESS. Other values are EXPIRE_AFTER_WRITE, NULL(LRU eviction based on cache size) -->
      <property name="evitionTime" value="240"/> <!-- Eviction time is 240 seconds -->
      <property name="concurrencyLevel" value="4"/> <!-- Concurrency Level of the cache is 4 -->
</bean>

<bean id="guavaCacheProvider" class="org.geowebcache.storage.blobstore.memory.guava.GuavaCacheProvider">
  <property name="configuration" ref="cacheConfiguration"/> <!-- Setting of the configuration -->
</bean>

HazelcastCacheProvider¶

HazelcastCacheProvider is useful for implementing distributed in memory caching for clustering. It internally uses Hazelcast for handling distributed caching. The HazelcastCacheProvider configuration requires another object called HazelcastLoader. This object accepts an Hazelcast instance or loads a file called hazelcast.xml from a proper directory defined by the property “hazelcast.config.dir”. If none of them is present, the CacheProvider object cannot be used.

The user must follow these rules for configuring the Hazelcast instance:

1. The Hazelcast configuration requires a Map object with name CacheProviderMap

2. Map eviction policy must be LRU or LFU

3. Map configuration must have a fixed size defined in Mb

4. Map configuration must have USED_HEAP_SIZE as MaxSizePolicy

Here the user can find both examples:

• From hazelcast.xml:

  <hazelcast xsi:schemaLocation="http://www.hazelcast.com/schema/config hazelcast-config-2.3.xsd"
                     xmlns="http://www.hazelcast.com/schema/config"
                     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <group>
          <name>cacheCluster</name>
          <password>geoserverCache</password>
    </group>
  
    <network>
          <!--
                  Typical usage: multicast enabled with port auto-increment enabled
                  or tcp-ip enabled with port auto-increment disabled. Note that you
                  must choose between multicast and tcp-ip. Another option could be
                  aws, but will not be described here.
  
          -->
          <port auto-increment="false">5701</port>
                  <join>
                           <multicast enabled="false">
                                  <multicast-group>224.2.2.3</multicast-group>
                                  <multicast-port>54327</multicast-port>
                          </multicast>
                          <tcp-ip enabled="true">
                                  <interface>192.168.1.32</interface>
                                  <interface>192.168.1.110</interface>
                          </tcp-ip>
                  </join>
    </network>
    <map name="CacheProviderMap">
                  <eviction-policy>LRU</eviction-policy>
                  <max-size policy="USED_HEAP_SIZE">16</max-size>
    </map>
  
  </hazelcast>
  

  And the related application context will be:

  <bean id="HazelCastLoader1"
          class="org.geowebcache.storage.blobstore.memory.distributed.HazelcastLoader">
  </bean>
  
  <bean id="HazelCastCacheProvider1"
          class="org.geowebcache.storage.blobstore.memory.distributed.HazelcastCacheProvider">
          <constructor-arg ref="HazelCastLoader1" />
  </bean>
  

  Note

  Remember that in this case the user must define the hazelcast.config.dir property when starting the application.

• From application context (See Hazelcast documentation for more info):

  <hz:hazelcast id="instance1">
          <hz:config>
                  <hz:group name="dev" password="password" />
                  <hz:network port="5701" port-auto-increment="true">
                          <hz:join>
                                  <hz:multicast enabled="true" multicast-group="224.2.2.3"
                                          multicast-port="54327" />
                          <hz:tcp-ip enabled="false">
                            <hz:members>10.10.1.2, 10.10.1.3</hz:members>
                          </hz:tcp-ip>
                          </hz:join>
                  </hz:network>
                  <hz:map name="CacheProviderMap" max-size="16" eviction-policy="LRU"
                          max-size-policy="USED_HEAP_SIZE" />
          </hz:config>
  </hz:hazelcast>
  
  <bean id="HazelCastLoader1"
          class="org.geowebcache.storage.blobstore.memory.distributed.HazelcastLoader">
          <property name="instance" ref="instance1" />
  </bean>
  
  <bean id="HazelCastCacheProvider1"
          class="org.geowebcache.storage.blobstore.memory.distributed.HazelcastCacheProvider">
          <constructor-arg ref="HazelCastLoader1" />
  </bean>
  

Optional configuration parameters¶

In this section are described other available configuration parameters to configure:

• Cache expiration time:

  <map name="CacheProviderMap">
  ...
  
      <time-to-live-seconds>0</time-to-live-seconds>
      <max-idle-seconds>0</max-idle-seconds>
  
  </map>
  

  Where time-to-live-seconds indicates how many seconds an entry can stay in cache and max-idle-seconds indicates how many seconds an entry may be not accessed before being evicted.

• Near Cache.

  <map name="CacheProviderMap">
  ...
  <near-cache>
    <!--
      Same configuration parameters of the Hazelcast Map. Note that size indicates the maximum number of
      entries in the near cache. A value of Integer.MAX_VALUE indicates no limit on the maximum
      size.
    -->
    <max-size>5000</max-size>
    <time-to-live-seconds>0</time-to-live-seconds>
    <max-idle-seconds>60</max-idle-seconds>
    <eviction-policy>LRU</eviction-policy>
  
    <!--
      Indicates if a cached entry can be evicted if the same value is modified in the Hazelcast Map. Default is true.
    -->
    <invalidate-on-change>true</invalidate-on-change>
  
    <!--
      Indicates if local entries must be cached. Default is false.
    -->
    <cache-local-entries>false</cache-local-entries>
  </near-cache>
  
  </map>
  

  Near Cache is a local cache for each cluster instance which is used for caching entries in the other cluster instances. This behaviour avoids to request those entries each time by executing a remote call. This feature could be helpful in order to improve Hazelcast Cache performances.

  Note

  A value of max-size bigger or equal to Integer.MAX_VALUE cannot be used in order to avoid an uncontrollable growth of the cache size.

Additional Information:¶

Some links that might be useful:

• The package makes use of the open source multi-cloud toolkit jclouds

• Jclouds documentation for getting started with Openstack

• Jclouds documentation for OpenStack Keystone V3 Support used in config