OpenStreetMap Tile Server on macOS

These notes are about options for running the OpenStreetMap mod_tile Tile Server on a macOS operating system, using Docker, Vagrant or directly on native macOS.

Docker and Vagrant are by far the easiest to implement, especially as there is a container available for download.

The overall process of setting up your own tile server is explained in the Switch2OSM Serving Tiles documentation.

Docker

I found the performance appeared very poor when run under Docker Desktop, but this could well be an issue with Big Sur and having a fusion drive.

I would still recommend trying Docker first, with a small data set. It's also useful to be able to refer to a working setup to analyse problems.

Vagrant

I haven't tried any of the Vagrant based solutions, but again, this should be a good option to follow as an alternative to Docker. It may not exhibit the performance issues I had with Docker and macOS. It's also easier to fiddle with a Vagrant setup or even simply install Debian or Ubuntu in a VirtualBox VM, which is what Vagrant is doing after all, just in a reliable and repeatable way.

Searching the web for 'Installing mod_tile with Vagrant' should bring up some good hits.

Installing the mod_tile Tile Server on macOS

Installing on macOS doesn't currently appear to be supported according to a comment on GitHub OpenStreetMap issue 106, so it may become more difficult to install in the future.

Note: this guide shows commands operated as the root user. It is unwise to use them directly. You should copy and paste them into a safe environment first, such as an editor, and ensure you are confident of the outcome, before copying them again from the editor. Additionally, understand the risks of Pastejacking, especially if using Vim as your editor.

Beware that the amount of processing and disk resources necessary to import data is significant and for many, importing the whole planet is unlikely to be a practical choice. It may be better using one of the free or commercial tile servers listed at https://wiki.openstreetmap.org/wiki/Tile_servers.

This install relies on using MacPorts to install the required applications and libraries.

These notes were written up after achieving a working system. I apologise if I have missed some steps.

As mixing user builds and MacPorts builds can cause problems, we will mitigate a little by putting non-MacPorts assets under /usr/local and any configuration and data relating to MacPorts installed packages under /opt/local. Additionally, as it appears you cannot exclude directories under /usr from Time Machine backups, we put the tile cache directory under /opt/local/var/lib/mod_tile in case we wish to exclude it from backups.

  1. Install MacPorts following the [MacPorts Installation Guide][macports install guide].

  2. Install the mod_tile port:

    $ sudo port install mod_tile

  3. Read the notes and instructions in /opt/local/share/doc/mod_tile/README_MacPorts.md assuming installed with the default /opt/local prefix.

  4. Configuring Apache

    There are many ways of using Apache. The following configuration will give you a working mod_tile server:

    If using MacPorts with the default prefix, the configuration file is /opt/local/etc/apache2/httpd.conf.

    Confirm that the mod_headers.so module is configured to be loaded. The entry should be uncommented, similar to the following:

    LoadModule headers_module lib/apache2/modules/mod_headers.so

    Add an entry to load the mod_tile module, perhaps somewhere after loading the mod_alias.so module.

    LoadModule tile_module lib/apache2/modules/mod_tile.so

    Add a <Virtualhost> section after the <Directory> directive:

    <VirtualHost *:80>
    Define ALLOW_CORS
    ServerAdmin webmaster@localhost
    ModTileTileDir /opt/local/var/lib/mod_tile
    LoadTileConfigFile /opt/local/etc/renderd/renderd.conf
    ModTileRenderdSocketName /opt/local/var/run/renderd/renderd.sock
    ModTileRequestTimeout 0
    ModTileMissingRequestTimeout 30
    # DocumentRoot /var/www/html
    # ErrorLog ${APACHE_LOG_DIR}/error.log
    # CustomLog ${APACHE_LOG_DIR}/access.log combined
    <IfDefine ALLOW_CORS>
        Header set Access-Control-Allow-Origin "*"
    </IfDefine>
</VirtualHost>

    Consider changing the LogLevel to aid diagnosing any problems:

    LogLevel info

  5. Restart the Apache server

    $ sudo port reload apache2

  6. Test the Tile Server

    Test basic web server functionality with: http://localhost/ - for a default Apache installation the returned web page should say "It works!". If it fails, check the Apache access and error logs.

    Test mod_tile with http://localhost/tile/0/0/0.png - this should use renderd to return an image map of the world. if it fails, check that renderd is running. if it is running, check its output. When this test works, you should have a fully functional tile server!

Pre-rendering Tiles

It can be useful to pre-render some of the higher zoom levels. The OSM Tile Calculator can be used to determine how many tiles would be pre-rendered for a specific zoom level.

mod_tile includes a utility named render_list that can pre-render tiles. A specific range of zoom levels can be specified, the default is all. Rather than pre-rendering the whole world, you can constrain it to specific X and Y tile coordinates. However you need to re-calculate the X and Y coordinates for each zoom level.

The OSM Tile Calculator can be used to show the x, y & z tile coordinates by clicking on the layers icon at the top right of the map (plus sign) and selecting the 'Tile coordinates' Overlay.

The following would pre-render Monaco at zoom level 14:

$ sudo -u nobody \
render_list -a -n 4 -m ajt \
-s /usr/local/var/run/renderd/renderd.sock \
-t /opt/local/var/lib/mod_tile \
-x 8529 -y 5973 -X 8530 -Y 5974 -z 14 -Z 14

But at zoom level 15 the tile coordinates are :

-x 17058 -y 11946 -X 17061 -Y 11949 -z 15 -Z 15

renderlistgeo.pl is a Perl script that uses specified geographic coordinates and calls render_list with the correct X and Y tile coordinates. You can use the 'CD' tab of the OSM Tile Calculator to quickly discover the geographic coordinates for an area.

Download and install renderlistgeo.pl:

$ cd ~/Downloads
$ curl -LO https://github.com/alx77/render_list_geo.pl/raw/master/render_list_geo.pl
$ sudo mv ~/Downloads/render_list_geo.pl /usr/local/bin/
$ sudo chown root:wheel /usr/local/bin/render_list_geo.pl
$ sudo chmod 755 /usr/local/bin/render_list_geo.pl

E.g. for Monaco you could use the following result from the OSM Tile Calculator:

7.4 43.72 7.45 43.76

Which defines the bottom left of a box as 43.72°N 7.4°E and top right as 43.76°N 7.45°E.

To pre-render zoom levels 0 to 1 for Monaco, execute:

$ sudo -u nobody \
render_list_geo.pl -n 4 -m ajt \
-s /usr/local/var/run/renderd/renderd.sock \
-t /opt/local/var/lib/mod_tile \
-x 7.4 -y 43.72 -X 7.45 -Y 43.76 \
-z 0 -Z 1

TimeMachine

As they can be quite large and volatile, you could consider excluding the tile cache directory /opt/local/var/lib/mod_tile/ajt and database directories /opt/local/var/db from TimeMachine backups. Bear in mind that this will exclude all databases from the backups. Consider separately backing up any other databases with the pg_dump utility.

Go to System Preferences... > Time Machine > Options to add those folders.

  1. Click Options....

  2. Click the plus sign at the bottom left of the dialog.

  3. Click Options and check the Show invisible items checkbox.

  4. Navigate to and select each folder to be excluded

  5. Click Exclude

  6. Click Save

-- Frank Dean - 03 Dec 2021

Related Topics: DockerTips, InstallingMacPorts, VirtualBox