Documentation

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
Warning

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".

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:
# API-only (no web UI — does not require building the frontend):
cargo build --release

# With embedded web UI (requires building the frontend first):
bun install
bun run build:client
cargo build --release --features frontend
Info

The frontend feature embeds the Nuxt web UI into the binary. Without it, the server still serves all tile and API endpoints — only the browser-based map viewer at / is omitted.

  1. Run the server:
./target/release/tileserver-rs --config config.toml

Next Steps