Configuring MS4W and MapCache for use in OpenLayers 3

This was spawned by an MS4W user asking how to setup OpenLayers3 for an MS4W MapCache's WMS service (​thread), with the following incorrect Javascript code, which did not write tiles to MS4W's cache directory:

See Step4 below for correct OpenLayers3 code

new ol.layer.Tile({
title: 'Chabahar',    
source: new ol.source.TileWMS({
url: 'http://localhost:100/cgi-bin/mapserv.exe?map=D:/WEB_GIS/code_test/wms/HTML5Application/public_html/chabahar.map&',
params: {
    'LAYERS': 'chabahar',
    'FORMAT': 'image/png',
    'TILED': true
},
serverType: 'mapserver'
})
                                        })  ,

Background Links

• ​MS4W homepage (Windows installer for MapServer)
• ​MapServer documentation (Open Source web mapping engine)
• ​MapCache (MapServer's tile caching engine)
• ​OpenLayers3 API (front-end Javascript framework)

Step 0: Install MS4W

• install ​MS4W (if you haven't already done so)

Step 1: Initialize MapCache Module

• follow all of the steps in MS4W's ​README to initialize the MapCache module
• confirm that tiles are being generated inside the folder: /ms4w/tmp/ms_tmp/cache/

Step 2: Install MS4W's OpenLayers3 Package

• if you haven't installed MS4W's OpenLayers 3 package (we'll use its sample WMS mapfile), please install it:
  • save the OpenLayers zip locally from: ​http://ms4w.com/download.html#applications-packaged-for-ms4w
  • extract its contents to the root of your MS4W installation
  • restart Apache: as Administrator, execute: /ms4w/apache-restart.bat
  • on your Web browser's MS4W homepage, click on the "MapServer WMS Example" link, in the OpenLayers section
  • this example uses a local WMS service, it should display the world countries as below:

Step 3: Configure mapcache.xml to use this WMS as a Source

• add the following to your mapcache.xml file (and if necessary change the <url> and <map> paths):

  <source name="ms4wserver" type="wms">
    <http>
      <url>http://127.0.0.1/cgi-bin/mapserv.exe</url>
    </http>
    <getmap>
      <params>
        <map>C:/ms4w/apps/openlayers-3.15.1/examples/map/wms-server.map</map>
        <layers>countries</layers>
      </params>
    </getmap>
  </source> 
  

• edit the existing <tileset> section of mapcache.xml, so that it includes:

  <tileset name="test">
    <source>ms4wserver</source>
    <cache>disk</cache>
    <grid>GoogleMapsCompatible</grid>
    <format>PNG</format>
    <metatile>5 5</metatile>
    <metabuffer>10</metabuffer>
    <expires>3600</expires>
  </tileset>
  

  • we use the "GoogleMapsCompatible" grid here, because OpenLayers assumes the ​EPSG:3857 projection. Read more about the various "Preconfigured Grids" for MapCache at: ​http://www.mapserver.org/mapcache/config.html#grid

• delete the existing cache folder: /ms4w/tmp/ms_tmp/cache/test

• restart Apache: as Administrator, execute: /ms4w/apache-restart.bat

• on your Web browser's MS4W homepage, click on the "Demo" link in the "MapCache URLs" section. Then click on the "wmts" link. A world countries map should appear, and if you expand the "+" button on the top right, it should list a layer named "test-GoogleMapsCompatible WMTS", as below:

• zoom in a few times, and check your cache folder (/ms4w/tmp/ms_tmp/cache/test), you will notice that tile images are saved there.

Step 4: Configure OpenLayers 3 to use this WMS Service

We will use one of the existing OpenLayers examples' html and javascript, but you can adapt this for your own page.

• copy the file /ms4w/apps/openlayers/examples/getfeatureinfo-tile.js and rename it to mapcache-getfeatureinfo-tile.js

• copy the file /ms4w/apps/openlayers/examples/getfeatureinfo-tile.html and rename it to mapcache-getfeatureinfo-tile.html

• edit the file /ms4w/apps/openlayers/examples/getfeatureinfo-tile.html and change the source on line#178 such as:

  <script src="loader.js?id=mapcache-getfeatureinfo-tile"></script>
  

• load that page in your Web browser using the appropriate URL (such as: ​http://127.0.0.1/openlayers/examples/mapcache-getfeatureinfo-tile.html) You should see a countries map with labels, such as:

• delete the existing cache folder: /ms4w/tmp/ms_tmp/cache/test

• edit the file /ms4w/apps/openlayers/examples/mapcache-getfeatureinfo-tile.html.js and change the wmsSource variable (at the top of the file) to:

var wmsSource = new ol.source.TileWMS({
  url: 'http://127.0.0.1/mapcache/',
  params: {
                'LAYERS': 'test',
                'VERSION': '1.1.1',
                'FORMAT': 'image/jpeg'
              },
  serverType: 'mapserver',
  crossOrigin: 'anonymous'
});

Note that for the 'LAYERS' parameter we must use the name that we defined earlier as the <tileset> in our mapcache.xml file.

• finally, refresh its html page in your Web browser (such as: ​http://127.0.0.1/openlayers/examples/mapcache-getfeatureinfo-tile.html) You should see the countries map (with no labels) such as:

• zoom in a few times, and check your cache folder (/ms4w/tmp/ms_tmp/cache/test), you will notice that tile images are saved there in a "GoogleMapsCompatible" subdirectory, as below:

Getting Additional Help

• feel free to ask your questions on the MS4W mailing list (​subscribe)
• for professional support, please contact ​Gateway Geomatics (the original author of this tutorial)