====== Self-hosted Map Tile Server ======

===== Introduction =====

A tile server is required for VuFind®'s [[configuration:geographic_features|geographic map display features]]. While a tile server is technically not a part of VuFind®, here are some pointers to how one can self-host a tile server alongside VuFind® instead of paid tile service subscription.

===== Tileset =====

First part of hosting a tile server is obtaining a tileset in [[https://docs.mapbox.com/help/glossary/mbtiles/|mbtiles format]]. At the time of writing of this article, there is a tileset from 2020 available from [[https://archive.org/details/osm-vector-mbtiles|The Internet Archive]]. If you want to host a newer tileset or regularly update one, you will need a relatively beefy server or workstation to create planet.mbtiles from the full [[https://planet.openstreetmap.org/|OSM planet PBF]]. There are several ways to do the conversion, but [[https://github.com/onthegomap/planetiler|Planetiler]] is probably the leanest one (though also not as customizable as some other approaches). It will be able to do the job on a system with 64 GB memory and about 700 GB disk space. Depending on available CPU capacity, memory and disk performance the process may take anything from a couple of hours to a couple of days to complete.

Planetiler has fairly good instructions and [[https://github.com/onthegomap/planetiler/blob/main/PLANET.md|examples]], and following them should get the job done. Here is an example command that has been used with success:

<code>
java -Xmx30g -jar planetiler.jar --area=planet --bounds=planet --download --fetch-wikidata --output=planet.mbtiles --nodemap-type=array --storage=mmap
</code>

Add the ''--osm-path=path/to/file.osm.pbf'' parameter if you've already downloaded a pbf file separately.

:!: Note that you should be prepared to update the maps at desired intervals, depending on your requirements.

===== Tile Server =====

The second part is the ongoing process of serving the tileset. [[https://github.com/maptiler/tileserver-gl|tileserver-gl]] is a well-known tile server able to serve the tiles in raster or vector format. It is relatively lightweight, but requires Docker unless you feel adventurous. Follow the [[https://github.com/maptiler/tileserver-gl#getting-started-with-docker|Getting Started with Docker example]] to get your own tile server up and running. You will need a map style in addition to the mbtiles vector maps. tileserver-gl has the osm-bright style in the [[https://github.com/maptiler/tileserver-gl/releases/download/v1.3.0/test_data.zip|test data]] package. You'll just need to ensure tileserver-gl's config.json references the correct style and mbtiles. Note that the style specifies "openmaptiles" as the source, and the name must be reflected in config.json as well, Here is an example config.json:

<code>
{
  "options": {
    "paths": {
      "root": "data",
      "fonts": "fonts",
      "styles": "styles"
    },
    "formatEncoding": {
      "png": 6,
      "jpeg": 80,
      "webp": 90
    }
  },
  "styles": {
    "osm-bright": {
      "style": "osm-bright/style.json",
      "tilejson": {
        "type": "overlay"
      }
    }
  },
  "data": {
    "openmaptiles": {
      "mbtiles": "planet.mbtiles"
    }
  }
}
</code> 

By default tileserver-gl listens at TCP port 8080, and it's better to not open it up for the whole world so that the server is not used for unauthorized third parties. You can proxy access through Apache server and add an access rule that requires the referrer to be your VuFind® instance. Apache can also cache the response data if desired. Here is an example virtual host configuration for Apache:

<code>
<VirtualHost *:443>
  ServerName map-api.vufind.org

  SSLEngine on

  CacheRoot   "/data/apache/"
  CacheEnable disk /
  CacheDirLevels 2
  CacheDirLength 1

  RewriteEngine On

  # Always use a robots.txt that disallows everything
  RewriteRule ^/robots.txt$ /data/vufind/public/robots-disallow-all.txt [END]
  <Directory "/data/vufind/public">
    <Files "robots*.txt">
      Require all granted
    </Files>
  </Directory>

  RewriteRule ^/v1/rendered/(.*)$ http://localhost:8080/styles/osm-bright/$1   [P]
  RewriteRule ^/v1/vector/(.*)$ http://localhost:8080/data/openmaptiles/$1   [P]
  RewriteRule .* - [F]

  # Any IP addresses or address prefixes that can always connect:
  #SetEnvIf X-Forwarded-For ^192\.168\.0 allow_connect
  #SetEnvIf Remote_Addr ^192\.168\.0 allow_connect
  
  # Allowed referrers:
  SetEnvIf Referer vufind\.org allow_connect
  SetEnvIf Referer demo\.vufind\.org allow_connect

  <Location />
    Require env allow_connect
  </Location>
</VirtualHost>
</code> 

The above configuration serves the raster maps at /v1/rendered and /v1/vector to hide implementation details (and potential issues if e.g. the theme used is changed).

==== Customizing the Map Style ====

[[https://maputnik.github.io/editor/|Maputnik]] can be used to modify the map style. It allows you to see the results in real time. Here is an example modification to osm-bright style to make "place-other" styled place names (islands, suburbs etc.) less prominent and only displayed when zoom level is at least 11:

<code>
{
  "id": "place-other",
  "type": "symbol",
  "metadata": {"mapbox:group": "1444849242106.713"},
  "source": "openmaptiles",
  "source-layer": "place",
  "minzoom": 11,
  "filter": [
    "!in",
    "class",
    "city",
    "town",
    "village",
    "country",
    "continent"
  ],
  "layout": {
    "text-field": "{name:latin}\n{name:nonlatin}",
    "text-font": ["Noto Sans Regular"],
    "text-letter-spacing": 0.1,
    "text-max-width": 9,
    "text-size": {"base": 1.2, "stops": [[12, 10], [15, 14]]},
    "text-transform": "none",
    "visibility": "visible"
  },
  "paint": {
    "text-color": "#633",
    "text-halo-color": "rgba(255,255,255,0.8)",
    "text-halo-width": 1
  }
},
</code>

It's recommended to save the modified style with a different name alongside the original one so that any changes are easy to see by comparing the two later on.

===== Attribution =====

Note that you must display proper attribution with the map. See basemap_attribution in VuFind®'s geofeatures.ini. At the time of writing the process on this page requires the following attribution:

  © OpenMapTiles © OpenStreetMap contributors