OpenStreetMap: Tile Server and Cache with MapProxy

Introduction

All components of OpenStreetMap exist as Free Software and can be self-hosted and customized.

When setting up a custom or self-hosted solution, it is probably easiest to replace components from the top down, i.e. starting with the viewer and ending with the tile server.

This article explains how to easily set up MapProxy to enable interoperability between different applications, cache results, and optionally even reproject tiles.

MapProxy

MapProxy was originally developed by a German company Omniscale.

Its homepage is at https://mapproxy.org/ and the code is at https://github.com/mapproxy.

Installation

MapProxy is very easy to set up. The complete documentation can be found at https://mapproxy.github.io/mapproxy/latest/index.html, but in general, the following should be enough to install MapProxy:

apt install python3-{pip,pyproj}

pip3 install MapProxy

Configuration

MapProxy comes with utility functions that create example configs.

To produce a basic config, run:

~/.local/bin/mapproxy-util create -t base-config mymapproxy

mymapproxy is the name of directory which will be created if missing, and the configuration files will be saved to it.

After generation, the contents will look like this:

ls mymapproxy/

cache_data
full_example.yaml
full_seed_example.yaml
mapproxy.yaml
seed.yaml

One file necessary to run the server is mapproxy.yaml. Files named full_* are generated by mapproxy for reference.

Running

To start MapProxy, run:

cd mymapproxy/

~/.local/bin/mapproxy-util serve-develop mapproxy.yaml

Once MapProxy starts, it automatically initializes the following endpoints for different protocols:

• Demo: http://localhost:8080/demo

• WMS. Capabilities: http://localhost:8080/service?REQUEST=GetCapabilities

• WMTS. Capabilities: http://localhost:8080/wmts/1.0.0/WMTSCapabilities.xml. First tile: http://localhost:8080/wmts/osm/webmercator/0/0/0.png

• Slippy Map Tile service (compatible with OSM). First tile: http://localhost:8080/tiles/osm/webmercator/0/0/0.png

• TMS (not compatible with OSM, Google Maps, etc.). First tile: http://localhost:8080/tms/1.0.0/osm/webmercator/0/0/0.png

• KML. Initial document: http://localhost:8080/kml/osm/webmercator

Omniscale provides an OSM tile server and the default configuration uses it. It does not allow unrestricted access without registration, and an appropriate message about it in English and German shows on the map:

Thank you for using our OpenStreetMap WMS demo!

Please sign up at maps.omniscale.com for unrestricted access.

However, that is quite OK in our case to verify the setup!

Leaflet Map

In OpenStreetMap: Custom Web Map Viewer with Leaflet we have set up a custom HTML page that displays OpenStreetMap map.

We can easily extend the map’s configuration to include an additional data source, the Slippy map coming from MapProxy:

The map.html patch file is very simple:

--- map.html	2024-04-30 18:18:20.564000000 +0000
+++ map.html	2024-04-30 18:34:42.944000000 +0000
@@ -46,9 +46,14 @@
         maxZoom: 19,
         attribution: '&copy; <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors, &copy; <a href="https://carto.com/attribution">CARTO</a>'
       });
+      var mapProxy = L.tileLayer('http://localhost:8080/tiles/osm/webmercator/{z}/{x}/{y}.png', {
+        maxZoom: 19,
+        attribution: '&copy; <a href="https://omniscale.com/legal">Omniscale GmbH & Co. KG</a>'
+      });
       var baseMaps = {
         "CARTO.Positron": positron,
         "<span style='color: red'>OpenStreetMap.HOT</span>": osmHOT,
+        "MapProxy": mapProxy,
         "OpenStreetMap": osm,
       };
 
@@ -63,7 +68,7 @@
       };
 
       // Create map - position it at specified latitude/longitude (0,0) and with a given zoom level (0-19)
-      var map = L.map('map', { minZoom: 0, maxZoom: 19, layers: [positron, osmHOT, osm] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
+      var map = L.map('map', { minZoom: 0, maxZoom: 19, layers: [mapProxy, positron, osmHOT, osm] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
 
       var layerControl = L.control.layers(baseMaps, overlayMaps).addTo(map);
 

Preview

Full content of the map file or a preview of the above page can be seen in map.html.

Note that MapProxy layer on the map will not show data unless you have actually installed MapProxy as per above instructions.