.. _mapcache_sources:

*****************************************************************************
Data Sources
*****************************************************************************

:Author: Thomas Bonfort
:Contact: tbonfort at terriscope.fr

MapCache uses the concept of a "source" as a service that is able to return
image data given a set of parameters (namely an extent, an image size, and a
projection). Typically, a source is the third-party WMS server that you want
to put a tile cache in front of.


.. _mapcache_source_wms:

WMS Sources
--------------------------------------------------------------------------------

A WMS server is the main upstream server type used by MapCache. When processing a
given tile, if it is not found in its cache, MapCache will query a WMS server with
a GetMap request, split the returned image data into individual tiles, and store
those tiles in its cache for subsequent requests.



.. code-block:: xml

  <source name="mywmsserver" type="wms">
    <http> .... </http>
    <getmap>
      <params>
        <map>/path/to/mapserver/mapfile.map</map>
        <layers>value2</layers>
      </params>
    </getmap>
  </source>


.. seealso:: :ref:`mapcache_http` to configure how the `<http>` block should be expressed

.. warning:: You should usually only supply vendor-specific parameters to the
             `<params>` block.  **Never** include any hardcoded BBOX, WIDTH, HEIGHT, SRS or
             any parameters related to dimensions inside this block, as these are calculated
             by MapCache itself at runtime.


.. _mapcache_source_mapfile:

MapFile Sources
--------------------------------------------------------------------------------

Experimental

WMTS Sources
--------------------------------------------------------------------------------
MapCache WMTS source uses GDAL WMTS driver under the hood. Note that GDAL version must be > 2.1 to be able to enable the driver correctly. GDAL WMTS driver documentation can be found on: http://www.gdal.org/frmt_wmts.html

GDAL WMTS xml file is needed, example command to construct such a file directly from wmts source equipped with basic auth & user/pass is: 
gdal_translate "WMTS:https://<url to capabilities>,layer=<layer id>" gdal_wmts.xml -of WMTS --config GDAL_HTTP_AUTH BASIC --config GDAL_HTTP_USERPWD <user:pass> 

After GDAL WMTS xml file is constructed, it's validity can be checked with command "gdalinfo <name of xml file>".

last step is to enable the new WMTS source with following configuration in mapcache.xml. 

.. code-block:: xml

  <source type="gdal" name="foo">
    <data>/path/to/gdal/file (gdal_wmts.xml)</data>
  </source>




