VersaTiles

VersaTiles is a Rust-based tool for processing and serving tile data efficiently. It supports multiple tile formats and offers functionalities for seamless tile handling.

Table of Contents

• Installation
  • Linux
  • MacOS
  • NixOS
  • Docker
  • npm (Node.js)
  • Building with Cargo
  • Building from Source
• Quick Start
• Usage
  • Core Concepts
  • Commands
  • VersaTiles Pipeline Language
  • Data Source Syntax
• Configuration
• GDAL Support
• Development
  • Prerequisites
  • Setup
  • Development Workflow
  • Pre-commit Hooks (Recommended)
  • Node.js Bindings Development
  • Contributing
• Repository Structure
• Using as a Library
• Additional Information
• For Maintainers
• License

Installation

Linux

Install VersaTiles using the provided installation script (that downloads the correct precompiled binary):

curl -Ls "https://github.com/versatiles-org/versatiles-rs/releases/latest/download/install-unix.sh" | sudo sh

MacOS

Install VersaTiles via Homebrew:

brew tap versatiles-org/versatiles
brew install versatiles

NixOS

VersaTiles is available via nixpkgs (starting from version 24.05):

Add this snippet to configuration.nix:

environment.systemPackages = with pkgs; [ versatiles ];

Alternatively, use it in a shell environment:

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [ versatiles ];
}

Find more details on Nix search.

Docker

Pull the latest Docker image for easy deployment:

docker pull versatiles-org/versatiles

npm (Node.js)

Install the Node.js bindings for use in JavaScript/TypeScript projects:

npm install @versatiles/versatiles-rs

Prerelease Versions

Test upcoming features with prerelease tags:

# Alpha (bleeding edge)
npm install @versatiles/versatiles-rs@alpha

# Beta (feature complete, testing)
npm install @versatiles/versatiles-rs@beta

# Release Candidate (final testing)
npm install @versatiles/versatiles-rs@rc

See all available versions:

npm view @versatiles/versatiles-rs versions

Building with Cargo

Ensure you have Rust installed, then run:

cargo install versatiles

Building from Source

Clone the repository and build VersaTiles manually:

git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs
cargo build --bin versatiles --release
cp ./target/release/versatiles /usr/local/bin/

Building from Source on Debian/Ubuntu (with GDAL)

# Install system dependencies and Rust
sudo apt-get update
sudo apt-get install -y build-essential pkg-config libssl-dev git curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Clone, install GDAL, and build
git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs
./scripts/install-gdal.sh
cargo build --bin versatiles --release -F gdal

# Add to PATH
sudo ln -sf "$(pwd)/target/release/versatiles" /usr/local/bin/versatiles

Quick Start

Get started with VersaTiles in 3 steps:

1. Verify Installation

versatiles --version

2. Download Sample Data

# Download a small region (Berlin, ~60MB)
versatiles convert --bbox=13.0,52.3,13.8,52.7 --bbox-border=3 https://download.versatiles.org/osm.versatiles berlin.versatiles

3. Explore Your Data

# View tile information
versatiles probe berlin.versatiles

# Serve tiles locally
versatiles serve berlin.versatiles

# Access at http://localhost:8080

Common Workflows

Convert tile formats:

versatiles convert input.mbtiles output.versatiles

Filter by zoom level:

versatiles convert --min-zoom=5 --max-zoom=12 input.versatiles output.versatiles

Extract a region:

versatiles convert --bbox=13.0,52.3,13.8,52.7 world.versatiles berlin.versatiles

Usage

Core Concepts

VersaTiles works with tile containers - files or directories containing map tiles organized by zoom level (z), column (x), and row (y).

Supported formats:

• .versatiles - Native format (best compression, fastest access)
• .mbtiles - SQLite-based (widely compatible)
• .pmtiles - Cloud-optimized single-file format
• .tar - Simple archive format
• Directories - Folder structure: z/x/y.ext

Remote access: VersaTiles can read remote .versatiles and .pmtiles files via HTTPS, and write to remote servers via SFTP (requires ssh2 feature):

versatiles serve https://download.versatiles.org/osm.versatiles

Commands

Run versatiles to see available commands:

Usage: versatiles [OPTIONS] <COMMAND>

Commands:
  convert  Convert between different tile containers
  probe    Show information about a tile container
  serve    Serve tiles via HTTP
  dev      Developer tools (unstable)
  help     Show detailed help

convert - Convert Between Tile Formats

Convert tiles between formats, filter by region or zoom, and transform coordinates.

Basic conversion:

versatiles convert input.mbtiles output.versatiles

Advanced options:

The output path can also be an SFTP URL (sftp://[user[:pass]@]host[:port]/path) to write directly to a remote server. This requires the ssh2 feature. Only formats that support streaming writes (.versatiles, .pmtiles) are supported over SFTP.

Real-world examples:

# Extract city region from world tiles
versatiles convert --bbox=13.0,52.3,13.8,52.7 \
  world.versatiles berlin.versatiles

# Compress tiles with maximum compression
versatiles convert --compress=brotli \
  uncompressed.tar compressed.versatiles

# Convert image format for smaller file size
versatiles convert --tile-format=webp \
  tiles.mbtiles tiles-webp.versatiles

# Fix coordinate system (TMS to XYZ)
versatiles convert --flip-y \
  tms-tiles.mbtiles xyz-tiles.versatiles

# Remote conversion with zoom filtering
versatiles convert --min-zoom=1 --max-zoom=10 \
  https://download.versatiles.org/osm.versatiles \
  local-osm-filtered.versatiles

# Write directly to a remote server via SFTP (requires ssh2 feature)
versatiles convert tiles.mbtiles \
  sftp://user@host/path/to/output.versatiles

probe - Inspect Tile Containers

Analyze tile containers to understand their contents and structure.

Basic usage:

versatiles probe tiles.versatiles

Depth levels:

Examples:

# Quick metadata check
versatiles probe tiles.versatiles -d

# Find actual zoom range with tiles
versatiles probe tiles.versatiles -dd

# Deep inspection with tile statistics
versatiles probe tiles.versatiles -ddd

# Probe remote container
versatiles probe https://download.versatiles.org/osm.versatiles -d

serve - HTTP Tile Server

Run a local or production tile server with advanced configuration.

Basic usage:

versatiles serve tiles.versatiles
# Access at http://localhost:8080

Server options:

Custom tile IDs:

Assign custom IDs to tile sources using bracket or hash syntax:

# Bracket prefix: [id]source
versatiles serve [osm]tiles.versatiles

# Bracket suffix: source[id]
versatiles serve tiles.versatiles[osm]

# Hash syntax: source#id
versatiles serve tiles.versatiles#osm

Access tiles at: http://localhost:8080/{id}/{z}/{x}/{y}.{ext}

Static content serving:

# Serve tar archive at root
versatiles serve -s "static.tar.br" tiles.versatiles

# Serve with custom prefix
versatiles serve -s "[/assets]static.tar.gz" tiles.versatiles
# Access: http://localhost:8080/assets/...

# Multiple static sources (first match wins)
versatiles serve \
  -s "[/styles]styles.tar.br" \
  -s "[/fonts]fonts.tar.gz" \
  tiles.versatiles

Supported static formats: .tar, .tar.gz, .tar.br, directories

Remote serving:

# Serve remote tiles directly
versatiles serve https://download.versatiles.org/osm.versatiles

# Mix local and remote sources
versatiles serve \
  [local]local.versatiles \
  [osm]https://download.versatiles.org/osm.versatiles

Configuration file:

For production deployments, use YAML configuration (see Configuration section):

versatiles serve -c production.yaml

For a full description of all configuration options:

versatiles help config

dev - Developer Tools (Unstable)

Experimental tools for tile analysis and debugging.

measure-tile-sizes - Generate a visual heatmap of tile sizes:

versatiles dev measure-tile-sizes tiles.versatiles output.png

# With options
versatiles dev measure-tile-sizes \
  --level=14 \
  --scale=4 \
  tiles.versatiles output.png

Output: PNG image where brightness = 10*log2(tile_size). Use to identify large tiles or data quality issues.

export-outline - Export tile coverage as GeoJSON:

versatiles dev export-outline tiles.versatiles coverage.geojson

# Specify zoom level (default: max zoom)
versatiles dev export-outline --level=10 tiles.versatiles coverage.geojson

Output: GeoJSON polygon showing which areas have tiles. Useful for visualizing coverage in QGIS/Mapbox.

print-tilejson - Print TileJSON metadata:

# Compact JSON
versatiles dev print-tilejson tiles.versatiles

# Pretty-printed JSON
versatiles dev print-tilejson -p tiles.versatiles

Output: Standard TileJSON 3.0.0 format with attribution, bounds, zoom levels, etc.

help - Detailed Help Topics

Get detailed help for specific topics:

# Pipeline language reference
versatiles help pipeline

# Configuration file reference
versatiles help config

# Data source syntax (bracket notation, inline VPL, JSON)
versatiles help source

# Raw markdown output (for documentation)
versatiles help pipeline --raw

VersaTiles Pipeline Language

The VersaTiles Pipeline Language (VPL) allows you to define tile-processing pipelines. Operations include merging multiple tile sources, filtering, and modifying tile content.

Example of combining multiple vector tile sources:

from_merged_vector [
   from_container filename="world.versatiles",
   from_container filename="europe.versatiles" | filter level_min=5,
   from_container filename="germany.versatiles"
]

More details can be found in versatiles_pipeline/README.md.

Data Source Syntax

All commands accept flexible data source expressions. You can override the auto-detected name and container type using bracket notation:

[name,type]path     # prefix notation
path[name,type]     # postfix notation

This also enables inline VPL pipelines — define a pipeline directly on the command line without creating a .vpl file:

versatiles convert \
  "[,vpl](from_container filename='input.versatiles' | filter level_max=12)" \
  output.versatiles

Run versatiles help source for the full syntax reference including JSON format.

Configuration

For production deployments, use YAML configuration files for fine-grained control over the tile server.

Basic Configuration

server:
  ip: 0.0.0.0
  port: 8080
  minimal_recompression: false  # true = faster, larger responses
  disable_api: false             # true = disable /api endpoints

tiles:
  - name: osm
    src: "./tiles/osm.versatiles"
  - name: satellite
    src: "https://tiles.example.com/sat.versatiles"

static:
  - src: "./static"
    prefix: "/"

Start with config:

versatiles serve -c config.yaml

Key Features

CORS Configuration - Control cross-origin access:

cors:
  allowed_origins:
    - "https://example.org"          # Exact domain
    - "*.dev.example.org"            # Subdomain wildcard
    - "https://example.*"            # TLD wildcard
    - "/^https://.*\\.example\\.org$/" # Regex pattern
  max_age_seconds: 86400

Custom Response Headers - Add caching and CDN headers:

extra_response_headers:
  Cache-Control: "public, max-age=86400, immutable"
  Surrogate-Control: "max-age=604800"      # For Varnish
  CDN-Cache-Control: "max-age=604800"      # For CDNs

Multiple Tile Sources - Serve multiple tile sets:

tiles:
  # Local file
  - name: city
    src: "./city.versatiles"

  # Remote HTTPS
  - name: osm
    src: "https://download.versatiles.org/osm.versatiles"

  # MBTiles format
  - name: elevation
    src: "./terrain.mbtiles"

  # VPL pipeline (processed on-the-fly)
  - name: processed
    src: "./pipeline.vpl"

Access tiles at: http://localhost:8080/{name}/{z}/{x}/{y}.{ext}

Static Content - Serve styles, fonts, and sprites:

static:
  # Tar archive at root
  - src: "./static.tar.br"
    prefix: "/"

  # Directory at custom path
  - src: "./public"
    prefix: "/assets"

Supported formats: directories, .tar, .tar.gz, .tar.br

Complete Example

server:
  ip: 0.0.0.0
  port: 8080
  minimal_recompression: false

cors:
  allowed_origins:
    - "https://myapp.com"
    - "*.myapp.dev"
  max_age_seconds: 86400

extra_response_headers:
  Cache-Control: "public, max-age=86400"

tiles:
  - name: basemap
    src: "https://download.versatiles.org/osm.versatiles"
  - name: satellite
    src: "./satellite.mbtiles"

static:
  - src: "./styles.tar.br"
    prefix: "/styles"
  - src: "./fonts.tar.gz"
    prefix: "/fonts"

Full Reference

For complete configuration documentation, see:

• versatiles/CONFIG.md - Full reference (auto-generated)

Or run:

versatiles help config

Environment Variables

VersaTiles supports the following environment variables:

• VERSATILES_CACHE_DIR - Enable disk-based tile caching. This is useful if you want to convert large tile sets with the from_gdal_raster VPL operation but have limited memory. Example: VERSATILES_CACHE_DIR=/tmp/versatiles_cache
• VERSATILES_SSH_IDENTITY - SSH identity (private key) file used for SFTP authentication.

Network resilience for remote reads/writes (HTTP and SFTP) over long-running transfers:

• VERSATILES_NET_MAX_RETRIES - Retries after the first attempt for each network read/write (default 32).
• VERSATILES_NET_RETRY_BASE_MS - Initial retry backoff in milliseconds; doubles each retry (default 1000).
• VERSATILES_NET_RETRY_MAX_MS - Upper bound for a single retry backoff in milliseconds (default 60000). With the defaults, a single operation tolerates roughly 25–30 minutes of continuous failure before giving up, so a long unattended transfer survives a storage/CDN outage instead of aborting.

SFTP connection tuning:

• VERSATILES_SFTP_TIMEOUT_MS - Per-operation SFTP API timeout in milliseconds (default 30000). Raise it if you see "API timeout expired" / "draining incoming flow" errors on congested links.
• VERSATILES_SFTP_KEEPALIVE_SECS - TCP and SSH keepalive interval in seconds (default 15), keeping connections alive across idle gaps.
• VERSATILES_SFTP_MAX_CONNECTIONS - Maximum number of pooled SFTP connections per server.

Memory for tile-gathering operations:

• VERSATILES_MAX_TILES_IN_FLIGHT - Upper bound on the number of raw source tiles held in memory at once by operations that combine sources (from_merged_vector, from_stacked, from_stacked_raster); default 2048. Peak memory ≈ this × the largest tile size, so lower it for very large tiles or many sources (e.g. 512), or raise it for more read-ahead on small tiles.

Memory for reading containers (PMTiles / VersaTiles):

• VERSATILES_CHUNK_MAX_BYTES - Maximum size of a single coalesced byte-range read when streaming tiles, in bytes (default 67108864 = 64 MiB). Each chunk is read as one in-memory blob.
• VERSATILES_CHUNK_READ_MEMORY - Budget for total in-flight chunk-read bytes (default 268435456 = 256 MiB). The number of chunks read concurrently is budget / chunk_size, so peak read memory stays near this value regardless of CPU count. Lower it on memory-constrained machines, or raise it to read further ahead on fast links.

Memory for writing .versatiles containers:

• VERSATILES_WRITE_TILE_BUFFER - Number of compressed tiles buffered between the parallel compressor and the serial writer (default 64). Tiles are streamed straight to the output, so peak writer memory is ≈ this × the tile size — independent of how large a block is. Lower it for very large tiles on memory-constrained machines, or raise it for more write-ahead.

Example usage:

# In one line
VERSATILES_CACHE_DIR=/var/cache/versatiles versatiles serve tiles.versatiles

# or
export VERSATILES_CACHE_DIR=/tmp/versatiles_cache
versatiles serve https://download.versatiles.org/osm.versatiles

GDAL support

versatiles supports GDAL since v1.0.0. However, this is still experimental.

Building with GDAL support

If you require GDAL support:

1. Install GDAL via your system package manager: ./scripts/install-gdal.sh (Supports Debian/Ubuntu, Alpine, and macOS via Homebrew)
2. Build with the gdal feature: cargo build -F gdal --release

Development

VersaTiles is built with Rust and includes Node.js bindings (NAPI-RS).

Prerequisites

Required:

• Rust 1.92+ (installation)
• Node.js 20+ (for Node.js bindings)

Optional:

• Lefthook - Pre-commit hooks
• GDAL 3.x - For GDAL support (build instructions)

Setup

# Clone repository
git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs

# Build debug version
cargo build --bin versatiles

# Run tests
cargo test

# Run binary
./target/debug/versatiles --version

Development Workflow

Running All Checks

Verify code quality before committing:

./scripts/check.sh

This runs:

• Rust: formatting (rustfmt), linting (clippy), type-checking, tests, doc tests
• Node.js: formatting (Prettier), linting (ESLint), type-checking (TypeScript), tests (Vitest)

Quick Fixes

Rust:

# Auto-format
cargo fmt

# Auto-fix clippy warnings
cargo clippy --fix

# Run specific tests
cargo test raster_overscale
cargo test --package versatiles_pipeline

Node.js:

cd versatiles_node

# Auto-fix all issues
npm run fix

# Individual tasks
npm run format        # Prettier
npm run lint:fix      # ESLint auto-fix
npm run typecheck     # TypeScript check
npm test              # Vitest

Building

Debug build (fast compilation, slow execution):

cargo build --bin versatiles
# Output: ./target/debug/versatiles

Release build (slow compilation, fast execution):

cargo build --bin versatiles --release
# Output: ./target/release/versatiles

With GDAL support:

# Install GDAL (via system package manager)
./scripts/install-gdal.sh

# Build with GDAL feature
cargo build --bin versatiles --release -F gdal

Testing

# All tests
cargo test

# Specific package
cargo test --package versatiles_core
cargo test --package versatiles_pipeline

# Specific test
cargo test raster_overscale

# With output
cargo test -- --nocapture

# Ignored tests (long-running)
cargo test -- --ignored

Documentation

# Generate docs
cargo doc --no-deps --open

# Test docs
cargo test --doc

Pre-commit Hooks (Recommended)

Install Lefthook for automatic quality checks:

# macOS
brew install lefthook

# Linux
curl -fsSL https://raw.githubusercontent.com/evilmartians/lefthook/main/install.sh | sh

# Windows
scoop install lefthook

# Enable hooks
lefthook install

Hook behavior:

• pre-commit: Fast checks (formatting, basic linting)
• pre-push: Full checks (all tests, clippy, type-checking)

Skip hooks when needed:

# Skip pre-commit
LEFTHOOK=0 git commit -m "message"

# Skip pre-push
git push --no-verify

Node.js Bindings Development

See versatiles_node/CONTRIBUTING.md for detailed workflow.

Quick reference:

cd versatiles_node

# Install dependencies
npm install

# Build Rust bindings
npm run build

# Build debug (faster compilation)
npm run build:debug

# Run tests
npm test

# Full check before commit
npm run check

Contributing

We welcome contributions! Please:

1. Fork and create a feature branch:

   git checkout -b feature/my-feature

2. Make changes and test:

   ./scripts/check.sh

3. Commit with clear messages:

   git commit -m "feat: add new feature"

4. Push and create pull request:

   git push origin feature/my-feature

Commit message format:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Formatting, no code change
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance tasks

Repository Structure

Code

• /versatiles/ - Main library and binary
• /versatiles_container/ - Handles tile containers (*.versatiles, *.mbtiles, *.pmtiles, etc.)
• /versatiles_core/ - Core data types and utilities
• /versatiles_derive/ - Derive macros for the library
• /versatiles_geometry/ - Handles geometric data (OSM, GeoJSON, vector tiles, etc.)
• /versatiles_image/ - Manages image data (PNG, JPEG, WEBP)
• /versatiles_pipeline/ - VersaTiles Pipeline for efficient tile processing

Dependencies of the versatiles packages:

---
config:
  layout: elk
---
flowchart TB
    versatiles --> versatiles_container
    versatiles --> versatiles_core
    versatiles --> versatiles_derive
    versatiles --> versatiles_geometry
    versatiles --> versatiles_image
    versatiles --> versatiles_pipeline
    versatiles_container --> versatiles_core
    versatiles_container --> versatiles_derive
    versatiles_container --> versatiles_geometry
    versatiles_container --> versatiles_image
    versatiles_core --> versatiles_derive
    versatiles_geometry --> versatiles_core
    versatiles_geometry --> versatiles_derive
    versatiles_image --> versatiles_core
    versatiles_image --> versatiles_derive
    versatiles_node --> versatiles
    versatiles_node --> versatiles_container
    versatiles_node --> versatiles_core
    versatiles_pipeline --> versatiles_container
    versatiles_pipeline --> versatiles_core
    versatiles_pipeline --> versatiles_derive
    versatiles_pipeline --> versatiles_geometry
    versatiles_pipeline --> versatiles_image

Helpers

• /docker/ - Dockerfile for Linux builds
• /testdata/ - Test files for validation
• /scripts/ - Development and CI/CD automation scripts — see scripts/README.md for the full reference. Most commonly used: check.sh, build-release-with-gdal.sh.

Using as a Library

VersaTiles can be used as a command-line tool or integrated into Rust projects as a library. Check out crates.io and docs.rs for more details.

Additional Information

For advanced usage, guides, and detailed documentation, visit the official documentation.

For Maintainers

Creating a Release

See RELEASING.md for the complete release process.

Quick version:

# Interactive mode - select release type from menu
./scripts/release-package.sh

# Or use command-line argument
./scripts/release-package.sh patch  # or minor/major/alpha/beta/rc/dev

# Push to trigger automated release
git push origin main --follow-tags

The GitHub Actions workflow will automatically:

• Build CLI binaries for 8 platforms (Linux gnu/musl x64/arm64, macOS x64/arm64, Windows x64/arm64)
• Build NAPI-RS bindings for Node.js (8 platform-specific packages)
• Publish to npmjs.com (@versatiles/versatiles-rs + 8 platform-specific packages)
• Create GitHub release with CLI binaries
• Trigger Docker and Homebrew updates

Contributing

VersaTiles is actively developed, and contributions are welcome! If you find bugs, need features, or want to contribute, please check the GitHub repository and submit an issue or pull request.

License

This project is licensed under the MIT License. See the LICENSE file for details.