versatiles/versatiles-planetiler repository overview

⁠Docker Image: versatiles/versatiles-planetiler

This Docker image provides a self-contained toolchain to generate OpenStreetMap based vector tiles in the Shortbread schema⁠ using Planetiler⁠ (the VersaTiles fork⁠ of Planetiler together with the Shortbread profile⁠), then packs the result into an efficient .versatiles, .pmtiles or .mbtiles container.

It is part of the versatiles-docker⁠ project.

⁠🧩 Features

• Fully automated OSM → Shortbread tiles → VersaTiles pipeline
• Based on Planetiler and versatiles-rs
• Interactive wizard or fully scriptable via flags / environment variables
• Optional land cover injection from landcover-vectors.versatiles⁠ (merged on the fly, no extra download)
• OSM ID renumbering (osmium renumber, on by default) for faster builds and slightly smaller tiles
• Optional checksums (.md5 + .sha256) written next to the output
• Output as versatiles (brotli), pmtiles or mbtiles
• Renders the whole planet or any Geofabrik sub-region
• Graceful shutdown on Ctrl-C (tini enabled)

⁠🚀 Quick Start

⁠Interactive

Run with an attached terminal (-it) and no arguments to launch the wizard. It asks whether to render the whole planet or a sub-region, whether to inject land cover, which container format to use, and the output filename. Mount one host directory at /app/data — it holds the source cache, temp files and the results:

docker run -it --rm \
  -v $(pwd)/planetiler:/app/data \
  versatiles/versatiles-planetiler:latest

⁠Non-interactive (flags)

Only --area is required; everything else has a default:

docker run --rm \
  -v $(pwd)/planetiler:/app/data \
  versatiles/versatiles-planetiler:latest \
  --area monaco --landcover

⁠Non-interactive (docker-compose)

services:
  planetiler:
    image: versatiles/versatiles-planetiler:latest
    environment:
      AREA: planet
      LANDCOVER: "1"
      FORMAT: versatiles
      JAVA_OPTS: -Xmx20g
    volumes:
      - ./planetiler:/app/data

The final file is written to ./planetiler/result/<name>.<format>.

⁠⚙️ How interactive vs. non-interactive is decided

The container chooses its mode from two signals:

The terminal check ([ -t 0 ]) prevents a detached or CI run from hanging on a prompt. Use -i / INTERACTIVE=1 to force the wizard.

⁠🎛️ Options

Flags take precedence over environment variables, which take precedence over the built-in defaults.

⁠Tuning variables

⁠🧠 Memory

Planetiler does not auto-abort on low memory — it only logs a warning and continues — so plan capacity yourself.

With the default --storage=mmap --nodemap_type=array, Planetiler keeps node locations in memory-mapped files, so the JVM heap can stay modest and the dominant requirement is free RAM for the OS page cache. Rule of thumb: ≥ 0.5× the .osm.pbf size as free RAM (the whole planet is a ~70 GB pbf → 64 GB+ RAM recommended).

JVM heap (-Xmx): In a container the JVM otherwise grabs only ~25 % of the cgroup limit. This image instead derives a sensible default (~40 % of the memory available to the container, capped at 32 GB) and prints it on startup. Override it with --xmx 20g / XMX=20g, or set the full JAVA_OPTS (an explicit -Xmx there wins).

Big machines: to keep everything in RAM for maximum speed, switch storage and raise the heap:

docker run --rm \
  -e PLANETILER_EXTRA_FLAGS="--storage=ram --nodemap_type=array" \
  -e XMX=110g \
  -v $(pwd)/planetiler:/app/data \
  versatiles/versatiles-planetiler:latest --area planet

See Planetiler's PLANET.md⁠ for details.

⁠🌍 Planet download

For --area planet, Planetiler downloads the ~70 GB planet extract over HTTP by default. With --torrent (or TORRENT=1) the image instead fetches it via BitTorrent using aria2c and feeds it to Planetiler with --osm_path — usually faster and more reliable. The other sources (water polygons, Natural Earth) are still fetched by Planetiler.

docker run --rm \
  -v $(pwd)/planetiler:/app/data \
  versatiles/versatiles-planetiler:latest --area planet --torrent

The pbf is cached under /app/data/sources/planet-<date>.osm.pbf (resumable, reused on re-runs). Override the snapshot with PLANET_DATE=YYMMDD, or the source with PLANET_PBF_BASE. --torrent is ignored for sub-regions (those download from Geofabrik via --area).

⁠🧱 Technical Overview

The container runs generate_tiles.sh⁠, which performs:

1. (on by default; disable with --no-renumber) Renumber the OSM input with osmium renumber so node/way IDs are dense. This shrinks Planetiler's node map (faster, less I/O) and shortens the feature IDs encoded in each tile (slightly smaller output). For the whole planet this adds time and needs RAM ≈ the pbf size, so disable it there if resources are tight.
2. Render Shortbread tiles with planetiler shortbread-1.1 --area=<area> into an intermediate PMTiles file (flat layout → fast sequential reads).
3. Convert the PMTiles to the chosen container with versatiles convert. When land cover is enabled, the VPL from_merged_vector operation folds the remote land cover container's features into the Shortbread layers (range-read on demand, nothing downloaded).
4. Store the final result in /app/data/result/<name>.<format>.
5. (optional, --checksum) Checksum — write <name>.<format>.md5 and <name>.<format>.sha256 next to the result.

.versatiles output is compressed with brotli; .pmtiles / .mbtiles keep their default compression.

⁠💾 Disk & host mounts

Mount one host directory at /app/data; it holds everything — the source cache (sources/), Planetiler's temp files (tmp/), the intermediate tiles and the results (result/). Keeping the cache on the host means re-runs reuse already-downloaded sources.

Rendering the whole planet is heavy: budget ~400 GB+ free disk and a few hours (see Memory⁠ for RAM). Test with a small region first, e.g. --area monaco. To put results elsewhere, set RESULT_DIR.

⁠🪄 Graceful Shutdown

This image uses tini⁠ as PID 1 to correctly handle SIGINT / SIGTERM signals. You can safely interrupt the container with Ctrl-C.

⁠📄 License

Distributed under the MIT License. Project: versatiles.org⁠