Skip to content

Tileserver Map Building

This guide covers building map tiles for different countries using the scripts located in bin. The scripts utilize Docker to run the map building process in a containerized environment using the tilemaker image.

Build Maps for Countries

Single Country Build (Shell Script)

# Build France map
bin/build-map.sh europe france

# Build Serbia map
bin/build-map.sh europe serbia

The results will be saved in the ./offline_tiles/ directory by default. You can specify a different output directory as a third argument:

# Build India map and save to custom directory
bin/build-map.sh asia india /path/to/custom/output

Available countries and continents can be found at download.geofabrik.de.

Batch Build Multiple Countries (Python Script)

For building maps for multiple countries or entire continents, use the build_maps.py script. This script automatically discovers available regions from Geofabrik and supports concurrent builds, state management, and resume functionality.

Prerequisites

Install required dependencies:

cd bin
poetry install

Basic Usage

# Build a specific country
poetry run python3 build_maps.py --continent europe --country france

# Build multiple countries in a continent
poetry run python3 build_maps.py --continent europe --country france serbia germany

# Build all countries in a continent
poetry run python3 build_maps.py --continent asia

# Build all countries in all continents
poetry run python3 build_maps.py

# Specify custom output directory
poetry run python3 build_maps.py --continent europe --country germany --output-dir /custom/path

# Use more concurrent threads (default: 4)
poetry run python3 build_maps.py --continent europe --threads 8

# Auto-detect CPU cores and use all of them
poetry run python3 build_maps.py --continent asia --threads auto

Advanced Features

Resume Interrupted Builds

The script automatically tracks build progress in .build_state.json. If a build is interrupted, you can resume from where it left off:

poetry run python3 build_maps.py --resume

This will skip any countries that were already successfully built and continue with the remaining ones.

Retry Failed Builds

If some builds failed (e.g., due to network issues), you can retry only the failed ones:

poetry run python3 build_maps.py --retry-failed

Combining Options

# Build all European countries with 6 threads, resuming from last run
poetry run python3 build_maps.py --continent europe --threads 6 --resume

Command-Line Options

Option Description Default
--continent Continent to build maps for (e.g., 'europe', 'asia') All continents
--country Country or countries to build maps for (e.g., 'france' or 'france serbia germany'). Requires --continent All countries in continent
--threads Number of concurrent builds. Use 'auto' to match CPU count 4
--output-dir Output directory for built maps ./offline_tiles/
--resume Resume from last incomplete build False
--retry-failed Retry only failed builds False

State Tracking

Build progress is saved in .build_state.json with the following information:

  • Build status (completed/failed)
  • Timestamp of each build
  • Original region steps
  • Normalized filename key

This allows you to:

  • Resume interrupted batch builds
  • Retry failed builds without rebuilding successful ones
  • Track build history and timestamps

Notes

  • Multiple countries: You can specify multiple countries for a continent by listing them after --country (e.g., --country france serbia germany)
  • Thread optimization:
    • Use --threads auto to automatically use all CPU cores
    • Check available cores: python3 -c "import os; print(os.cpu_count())"
    • Recommended: CPU count (conservative) to 2x CPU count (aggressive)
    • The script shows CPU recommendations in --help
  • Region normalization: Region names with dashes (e.g., central-america) are automatically normalized to underscores (central_america) in filenames
  • Dynamic region discovery: The script fetches available regions dynamically from Geofabrik, so it always has the latest region list
  • Isolated builds: Each build runs in isolation using the build-map.sh script
  • Error recovery: Failed builds are logged and can be retried later without affecting successful builds

Upload to S3 storage

Prerequisites

  1. Generate Account API Token
    • Create an S3 credential via the hetzner cloud console dashboard.
    • Note down the access_key and secret_key - these will be needed for rclone configuration

Installation and Configuration

  1. Install rclone 

    # On Ubuntu/Debian
apt install rclone

# On macOS
brew install rclone

  2. Create rclone configuration 

    # Open rclone config file in a text editor
nano ~/.config/rclone/rclone.conf

# Add the following configuration, replacing placeholders with your actual values
[hetzner-open-mbtiles]
type = s3
provider = Other
access_key_id = <access_key>
secret_access_key = <secret_key>
region = hel1
endpoint = hel1.your-objectstorage.com

# Save and exit the editor

Uploading Tiles

  1. Upload all files in storage 

    rclone sync ./offline_tiles/ hetzner-open-mbtiles:open-mbtiles

  2. Upload specific file 

    rclone copy asia_india.mbtiles hetzner-open-mbtiles:open-mbtiles

  3. Flags to see progress and details 

    rclone sync ./offline_tiles/ hetzner-open-mbtiles:open-mbtiles --progress --stats=1s --stats-one-line

Note: Built maps are not versioned. Uploading a new map will overwrite the existing one in the storage ensuring only the latest version is available.