stsdockerhub/openstreetmap-tile-server repository overview

⁠OpenStreetMap Tile Server

This container allows you to easily set up an OpenStreetMap PNG tile server given a .osm.pbf file. Docker image size is about ~1.5 GB. It is based on the latest Ubuntu 22.04 LTS guide⁠ from switch2osm.org⁠ and therefore uses the default OpenStreetMap style.

⁠Components

⁠PostgreSQL⁠ ( v 15.3 )

⁠PostGIS⁠ ( v 3.3.3 )

PostGIS is a spatial database extender for PostgreSQL object-relational database. It adds support for geographic objects allowing location queries to be run in SQL.

⁠Apache⁠ ( v 2.4.52 )

⁠Apache - mod_tile

An Apache module called mod_tile enhances the regular Apache file serving mechanisms to provide:

When tiles have expired it requests the rendering daemon to render (or re-render) the tile. Remapping of the file path to the hashed layout. Prioritizes rendering requests depending on the available resources on the server and how out of date they are. Use tile storage other than a plain posix file system. e.g it can store tiles in a ceph object store, or proxy them from another tile server. Tile expiry. It estimates when the tile is next likely to be rendered and adds the appropriate HTTP cache expiry headers. This is a configurable heuristic. To avoid problems with directories becoming too large and to avoid too many tiny files. They store the rendered tiles in "meta tiles" in a special hashed directory structure. These combine 8x8 actual tiles into a single meta-tile file. This is a more efficient use of disk space and inodes.

The meta-tiles are then stored in the following directory structure: /[base_dir]/[TileSetName]/[Z]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy]/[xxxxyyyy].png

Where base_dir is a configurable base path for all tiles. TileSetName is the name of the style sheet rendered. Z is the zoom level. [xxxxyyyy] is an 8-bit number, with the first 4 bits taken from the x coordinate and the second 4 bits taken from the y coordinate. This attempts to cluster 16x16 square of tiles together into a single sub-directory for more efficient access patterns.

Apache serves the files as if they were present under /[TileSetName]/Z/X/Y.png with the path being converted automatically.

⁠Renderd

The rendering is implemented in a multi-threaded process called renderd which opens either a unix or tcp socket and listens for requests to render tiles. It uses Mapnik to render tiles using the rendering rules defined in the configuration file /etc/renderd.conf. Its configuration also allows to specify the number of rendering threads.

The render daemon implements a queuing mechanism with multiple priority levels to provide an as up-to-date viewing experience given the available rendering resources. The highest priority is for on the fly rendering of tiles not yet in the tile cache, two priority levels for re-rendering out of date tiles on the fly and two background batch rendering queues. The on the fly rendering queues are limited to a short 32 meta-tile size to minimize latency. The size of the main background queue is determined at compile time, see: render_config.h

⁠Osm2pgsql⁠ ( v 1.6.0 )

Osm2pgsql is a tool for loading OpenStreetMap data into a PostgreSQL / PostGIS database suitable for applications like rendering into a map, geocoding with Nominatim, or general analysis.

⁠OpenStreetMap Carto⁠ ( v 5.3.1 )

CartoCSS map stylesheets for the Standard map layer on OpenStreetMap.org⁠. CartoCSS is a language for map design. It is similar in syntax to CSS, but builds upon it with specific abilities to filter map data and by providing things like variables. It targets the Mapnik renderer and is able to generate Mapnik XML and a JSON variant of Mapnik XML. It can run from the command line or in the browser.

⁠Setup

1. Create a Docker volume to hold the PostgreSQL database that will contain the OpenStreetMap data, to make sure data survives container restarts: OpenStreetMap database data will be stored in /data/database/.

   docker volume create osm-data
   

   Copy

2. Create a Docker volume to hold the rendered tiles, to make sure data survives container restarts: Tiles that have already been rendered will be stored in /data/tiles/.

   docker volume create osm-tiles
   

   Copy

3. Download an .osm.pbf extract from geofabrik.de⁠ for the region that you're interested in. You can also download an .osm.pbf from planet.openstreetmap.org⁠ for the complete planet.

4. Start importing it into PostgreSQL by running a container and mounting the file as /data/region.osm.pbf. For example:

   docker run \
       -v /absolute/path/to/luxembourg.osm.pbf:/data/region.osm.pbf \
       -v /absolute/path/to/luxembourg.poly:/data/region.poly \
       -v osm-data:/data/database/ \
       -v osm-tiles:/data/tiles/ \
       stsdockerhub/openstreetmap-tile-server \
       import
   

   Copy

Please note: If you're not importing the whole planet, then the .poly file is necessary to limit automatic updates to the relevant region. Therefore, when you only have a .osm.pbf file but not a .poly file, you should not enable automatic updates.

Note that the import process requires an internet connection. The run process does not require an internet connection. If you want to run the openstreetmap-tile server on a computer that is isolated, you must first import on an internet connected computer, export the osm-data volume as a tarfile, and then restore the data volume on the target computer system.

⁠Run

Your tiles will now be available at http://localhost:8080/tile/{z}/{x}/{y}.png. The demo map in leaflet-demo.html will then be available on http://localhost:8080. Note that it will initially take quite a bit of time to render the larger tiles for the first time.

docker run \
    -p 8080:80 \
    -v osm-data:/data/database/ \
    -v osm-tiles:/data/tiles/ \
    -d \ 
    stsdockerhub/openstreetmap-tile-server \
    run