Skip to content

Generate Map

generate-map is a tool for generating vector maps in MBTiles format from OpenStreetMap data provided by Geofabrik.

The script uses Planetiler executed in a Docker container to produce optimized maps that can be directly used by TileServer GL.

The goal is to allow generating or updating the maps embedded in a RecoveryBox without manual intervention.

Key features include:

  • automatic download of OpenStreetMap data;
  • generation of .mbtiles files via Planetiler;
  • choice of geographic area (continent or country);
  • choice of detail level (maximum zoom);
  • automatic merging with an existing map;
  • optional restart of the tile server.

The script is fully interactive and guides the user throughout the generation process.

How it works

The script automates the entire map generation pipeline.

1. Area selection

The user chooses whether the map should be generated for:

  • a complete continent;
  • a country.

Data is then automatically downloaded from the Geofabrik repository as a .osm.pbf file.

2. Detail level selection

The script offers four zoom levels corresponding to the maximum level generated by Planetiler.

Level Zoom Usage
Overview 6 Global view, minimal storage
Tactical 10 Road network and navigation
Operational 12 Urban details
High Precision 14 Buildings and full details

The higher the zoom level:

  • the longer the generation time;
  • the higher the memory consumption;
  • the larger the final MBTiles file.

Level 14 can produce a file several tens of times larger than level 6.

3. Map generation

Once the data is downloaded, Planetiler is executed in a Docker container.

The amount of Java memory allocated is calculated automatically based on the available memory on the machine.

The generated file is produced in the format:

<zone>.mbtiles

4. Map merging

If no map exists yet on the RecoveryBox:

map.mbtiles

is created directly.

If a map already exists, the script automatically merges the two files using tile-join.

This operation allows adding a new geographic area without regenerating existing maps.

In case of merge failure, a rollback mechanism automatically restores the previous map.

5. Tile Server restart

Once generation is complete, the script offers to automatically restart the service:

tileserver-gl.service

so that the new map is immediately available.

File interactions

The script uses several working directories.

Planetiler working directory

/data/planetiler

Temporarily contains:

  • downloaded .osm.pbf files;
  • Planetiler temporary files;
  • MBTiles files before installation.

This directory is automatically cleaned up at the end of execution.

Tile Server directory

/data/tileserver

Contains the maps used by TileServer GL.

The main file is:

map.mbtiles

During a merge, a temporary file is created:

world.mbtiles

which is deleted after the merge.

Data download

OpenStreetMap data is automatically retrieved from:

https://download.geofabrik.de/

The script downloads the latest available version of the selected area in the format:

<zone>-latest.osm.pbf

Docker container

Generation is performed using the official Docker image:

ghcr.io/onthegomap/planetiler:latest

The working directory is mounted in the container to directly retrieve the generated files.

Debugging

Several checks can help diagnose issues during generation.

Verify the download

Ensure the PBF file has been downloaded:

ls -lh /data/planetiler/*.osm.pbf

Verify Docker

The script requires Docker and the Planetiler image.

docker images

docker run --rm ghcr.io/onthegomap/planetiler:latest --help

Verify disk space

High-resolution maps may require several tens of gigabytes.

df -h

Verify available memory

Planetiler uses a large amount of RAM.

free -h

The script automatically adjusts the available Java memory based on the detected physical memory.

Verify generated maps

List the maps present:

ls -lh /data/tileserver

The active map must be:

map.mbtiles

Verify the TileServer service

After generation:

systemctl status tileserver-gl.service

or

journalctl -u tileserver-gl.service

allows verifying that the server has correctly loaded the new map.

Automatic cleanup

At the end of execution (even in case of error), the script automatically deletes:

  • Planetiler temporary files;
  • downloaded PBF files;
  • intermediate sources;
  • generated weight files.

This limits the disk space used after each generation.

Tools

The script uses the Planetiler container to generate the .mbtiles file from the .pbf.

To merge maps, the script uses tile-join from tippecanoe.