Tileserver RS
Getting Started

Installation

How to install and set up Tileserver RS

There are several ways to install and run Tileserver RS.

Using Homebrew (macOS)

The easiest way to install on macOS:

# Add the tap and install
brew tap vinayakkulkarni/tileserver-rs https://github.com/vinayakkulkarni/tileserver-rs
brew install vinayakkulkarni/tileserver-rs/tileserver-rs

# Run the server
tileserver-rs --config config.toml

Pre-built Binaries

Download the latest release from GitHub Releases.

macOS ARM64 (Apple Silicon)

curl -L https://github.com/vinayakkulkarni/tileserver-rs/releases/latest/download/tileserver-rs-macos-arm64.tar.gz | tar xz
chmod +x tileserver-rs

# Remove macOS quarantine (required for unsigned binaries)
xattr -d com.apple.quarantine tileserver-rs

# Run
./tileserver-rs --config config.toml
macOS Security Note: If you download via a browser, macOS Gatekeeper will block the unsigned binary. Either use the curl command above, or after downloading, run xattr -d com.apple.quarantine tileserver-rs to remove the quarantine flag. Alternatively, right-click the binary in Finder and select "Open".

Using Docker (Recommended for Linux)

The easiest way to get started is using Docker:

docker pull ghcr.io/vinayakkulkarni/tileserver-rs:latest

docker run -p 8080:8080 \
  -v /path/to/your/tiles:/data:ro \
  -v /path/to/config.toml:/app/config.toml:ro \
  ghcr.io/vinayakkulkarni/tileserver-rs:latest

Using Docker Compose

Create a compose.yml file:

services:
  tileserver:
    image: ghcr.io/vinayakkulkarni/tileserver-rs:latest
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data:ro
      - ./config.toml:/app/config.toml:ro
    environment:
      - RUST_LOG=info

Then run:

docker compose up -d

Building from Source

Prerequisites

  • Rust 1.75 or later
  • Node.js 22 or later (for the frontend)
  • Bun (package manager)

For Native Rendering (Optional)

Native raster tile rendering uses MapLibre Native (C++). If you don't need raster tiles, the server runs without it.

macOS:

# Install build dependencies
brew install ninja ccache libuv glfw bazelisk cmake

# Build MapLibre Native
cd maplibre-native-sys/vendor/maplibre-native
git submodule update --init --recursive
cmake --preset macos-metal
cmake --build build-macos-metal --target mbgl-core mlt-cpp -j8

Linux (Ubuntu/Debian):

# Install build dependencies
apt-get install ninja-build ccache libuv1-dev libglfw3-dev cmake

# Build MapLibre Native
cd maplibre-native-sys/vendor/maplibre-native
git submodule update --init --recursive
cmake --preset linux
cmake --build build-linux --target mbgl-core mlt-cpp -j8

Build Steps

  1. Clone the repository:
git clone https://github.com/vinayakkulkarni/tileserver-rs.git
cd tileserver-rs
  1. Build the Rust backend:
cargo build --release
  1. Build the frontend:
bun install
bun run build:client
  1. Run the server:
./target/release/tileserver-rs --config config.toml

Next Steps

Quick Start

Serve your first map tiles in 5 minutes