Caches¶

Configuration¶

You can configure a backend for each cache with the cache option. Each backend has a type and one or more options.

caches:
  mycache:
    sources: [...]
    grids: [...]
    cache:
      type: backendtype
      backendoption1: value
      backendoption2: value

The following backend types are available.

• file
• mbtiles
• sqlite
• geopackage
• couchdb
• riak
• redis
• s3
• compact

file¶

This is the default cache type and it uses a single file for each tile. Available options are:

directory_layout:

The directory layout MapProxy uses to store tiles on disk. Defaults to tc which uses a TileCache compatible directory layout (zz/xxx/xxx/xxx/yyy/yyy/yyy.format). mp uses a directory layout with less nesting (zz/xxxx/xxxx/yyyy/yyyy.format`). tms uses TMS compatible directories (zz/xxxx/yyyy.format). quadkey uses Microsoft Virtual Earth or quadkey compatible directories (see http://msdn.microsoft.com/en-us/library/bb259689.aspx). arcgis uses a directory layout with hexadecimal row and column numbers that is compatible to ArcGIS exploded caches (Lzz/Rxxxxxxxx/Cyyyyyyyy.format).

Note

tms, quadkey and arcgis layout are not suited for large caches, since it will create directories with thousands of files, which most file systems do not handle well.

use_grid_names:

When true MapProxy will use the actual grid name in the path instead of the SRS code. E.g. tiles will be stored in ./cache_data/mylayer/mygrid/ instead of ./cache_data/mylayer/EPSG1234/.

New in version 1.5.0.

directory:

Directory where MapProxy should directly store the tiles. This will not add the cache name or grid name (use_grid_name) to the path. You can use this option to point MapProxy to an existing tile collection (created with gdal2tiles for example).

New in version 1.5.0.

tile_lock_dir:

Directory where MapProxy should write lock files when it creates new tiles for this cache. Defaults to cache_data/tile_locks.

New in version 1.6.0.

mbtiles¶

Use a single SQLite file for this cache. It uses the MBTile specification.

Available options:

filename:

The path to the MBTiles file. Defaults to cachename.mbtiles.

tile_lock_dir:

Directory where MapProxy should write lock files when it creates new tiles for this cache. Defaults to cache_data/tile_locks.

New in version 1.6.0.

You can set the sources to an empty list, if you use an existing MBTiles file and do not have a source.

caches:
  mbtiles_cache:
    sources: []
    grids: [GLOBAL_MERCATOR]
    cache:
      type: mbtiles
      filename: /path/to/bluemarble.mbtiles

The note about bulk_meta_tiles for SQLite below applies to MBtiles as well.

sqlite¶

Use SQLite databases to store the tiles, similar to mbtiles cache. The difference to mbtiles cache is that the sqlite cache stores each level into a separate database. This makes it easy to remove complete levels during mapproxy-seed cleanup processes. The sqlite cache also stores the timestamp of each tile.

Available options:

dirname:

The directory where the level databases will be stored.

tile_lock_dir:

Directory where MapProxy should write lock files when it creates new tiles for this cache. Defaults to cache_data/tile_locks.

New in version 1.6.0.

caches:
  sqlite_cache:
    sources: [mywms]
    grids: [GLOBAL_MERCATOR]
    cache:
      type: sqlite
      directory: /path/to/cache

caches:
  sqlite_cache:
    sources: [mytilesource]
    bulk_meta_tiles: true
    grids: [GLOBAL_MERCATOR]
    cache:
      type: sqlite
      directory: /path/to/cache

couchdb¶

Store tiles inside a CouchDB. MapProxy creates a JSON document for each tile. This document contains metadata, like timestamps, and the tile image itself as a attachment.

caches:
  mycouchdbcache:
    sources: [mywms]
    grids: [mygrid]
    cache:
      type: couchdb
      url: http://localhost:9999
      db_name: mywms_tiles
      tile_metadata:
        mydata: myvalue
        tile_col: '{{x}}'
        tile_row: '{{y}}'
        tile_level: '{{z}}'
        created_ts: '{{timestamp}}'
        created: '{{utc_iso}}'
        center: '{{wgs_tile_centroid}}'

{
    "_attachments": {
        "tile": {
            "content_type": "image/png",
            "digest": "md5-ch4j5Piov6a5FlAZtwPVhQ==",
            "length": 921,
            "revpos": 2,
            "stub": true
        }
    },
    "_id": "mygrid-3-1-2",
    "_rev": "2-9932acafd060e10bc0db23231574f933",
    "center": [
        -112.5,
        -55.7765730186677
    ],
    "created": "2011-12-15T12:56:21Z",
    "created_ts": 1323953781.531889,
    "mydata": "myvalue",
    "tile_col": 1,
    "tile_level": 3,
    "tile_row": 2
}

riak¶

Store tiles in a Riak cluster. MapProxy creates keys with binary data as value and timestamps as user defined metadata. This backend is good for very large caches which can be distributed over many nodes. Data can be distributed over multiple nodes providing a fault-tolernt and high-available storage. A Riak cluster is masterless and each node can handle read and write requests.

myriakcache:
  sources: [mywms]
  grids: [mygrid]
  cache:
    type: riak
    nodes:
      - host: 1.example.org
        pb_port: 9999
      - host: 1.example.org
      - host: 1.example.org
    protocol: pbc
    bucket: myriakcachetiles
    default_ports:
      pb: 8087
      http: 8098

redis¶

Store tiles in a Redis in-memory database. This backend is useful for short-term caching. Typical use-case is a small Redis cache that allows you to benefit from meta-tiling.

Your Redis database should be configured with maxmemory and maxmemory-policy options to limit the memory usage. For example:

maxmemory 256mb
maxmemory-policy volatile-ttl

redis_cache:
    sources: [mywms]
    grids: [mygrid]
    cache:
      type: redis
      default_ttl: 600

geopackage¶

Store tiles in a geopackage database. MapProxy creates a tile table if one isn’t defined and populates the required meta data fields. This backend is good for datasets that require portability. Available options:

filename:

The path to the geopackage file. Defaults to cachename.gpkg.

table_name:

The name of the table where the tiles should be stored (or retrieved if using an existing cache). Defaults to the cachename_gridname.

levels:

Set this to true to cache to a directory where each level is stored in a separate geopackage. Defaults to false. If set to true, filename is ignored.

directory:

If levels is true use this to specify the directory to store geopackage files.

You can set the sources to an empty list, if you use an existing geopackage file and do not have a source.

caches:
  geopackage_cache:
    sources: []
    grids: [GLOBAL_MERCATOR]
    cache:
      type: geopackage
      filename: /path/to/bluemarble.gpkg
      table_name: bluemarble_tiles

s3¶

Store tiles in a Amazon Simple Storage Service (S3) or any other S3 compatible object storage.

cache:
  my_layer_20110501_epsg_4326_cache_out:
    sources: [my_layer_20110501_cache]
    cache:
      type: s3
      directory: /1.0.0/my_layer/default/20110501/4326/
      bucket_name: my-s3-tiles-cache

globals:
  cache:
    s3:
      profile_name: default

cache:
  my_layer_20110501_epsg_4326_cache_out:
    sources: [my_layer_20110501_cache]
    cache:
      type: s3
      directory: /1.0.0/my_layer/default/20110501/4326/
      bucket_name: my-s3-tiles-cache

globals:
  cache:
    s3:
      profile_name: default
      region_name: nyc3
      endpoint_url: https://nyc3.digitaloceanspaces.com
      access_control_list: public-read

compact¶

Store tiles in ArcGIS compatible compact cache files. A single compact cache .bundle file stores up to about 16,000 tiles.

Version 1 of the compact cache format is compatible with ArcGIS 10.0 and the default version of ArcGIS 10.0-10.2. Version 2 is supported by ArcGIS 10.3 or higher. Version 1 stores is one additional .bundlx index file for each .bundle data file.

Available options:

directory:

Directory where MapProxy should store the level directories. This will not add the cache name or grid name to the path. You can use this option to point MapProxy to an existing compact cache.

version:

The version of the ArcGIS compact cache format. This option is required. Either 1 or 2.

You can set the sources to an empty list, if you use an existing compact cache files and do not have a source.

The following configuration will load tiles from /path/to/cache/L00/R0000C0000.bundle, etc.

caches:
  compact_cache:
    sources: []
    grids: [webmercator]
    cache:
      type: compact
      version: 2
      directory: /path/to/cache