# mbtileserver

**Repository Path**: mapbox-gl/mbtileserver

## Basic Information

- **Project Name**: mbtileserver
- **Description**: mbtileserver
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# MBTileServer

Vector maps with GL styles. Lightweight map tile server for MapLibre GL JS, Leaflet, OpenLayers, GIS via WMTS, etc.

> **Note**: This is a light-weight fork of [TileServer GL](https://github.com/maptiler/tileserver-gl), focused on serving vector tiles (MBTiles/PMTiles) **without** server-side raster rendering.

## Features

- **MBTiles** support — Serve vector tiles from local SQLite databases
- **PMTiles** support — Cloud-optimized tile archives with HTTP range requests
- **GeoJSON** support — Serve on-demand vector tiles from folders of `.geojson` files, with automatic layer scanning and `_mbtiles` caching
- **Zero native dependencies** — Pure JavaScript, runs on Windows, macOS, and Linux
- **Built-in preview** — Interactive map viewer powered by MapLibre GL JS 5.x
- **Rich viewer UI** — Layer list, search, drag-and-drop reorder, visibility toggle, inline rename, duplicate, style editor with color picker
- **Style editor** — Edit layer paint/layout properties via JSON, with cascading preset dropdowns (fill/line/circle/symbol)
- **Color picker** — Double-click color swatches to modify colors with native color input
- **Map pick & popup** — Click on map to query rendered features and navigate to layers
- **Style upload/download** — Import/export MapLibre style.json on the fly
- **TileJSON / WMTS** — Standard OGC-compatible service endpoints
- **Static files** — Serve custom fonts, sprites, images via `/files/`
- **Lightweight** — No Canvas, no MapLibre GL Native, no heavy raster rendering pipeline

## Requirements

- Node.js **v20+** (v22 LTS recommended)
- npm

```bash
node --version  # v22.x.x
npm --version   # 10.x.x
```

## Install

### From source (local)

```bash
git clone https://gitee.com/mapbox-gl/mbtileserver.git
cd mbtileserver
npm install -g .
```

### Verify installation

```bash
mbtileserver --version
# 5.6.3
```

## Quick Start

### Serve a single MBTiles file

```bash
mbtileserver zurich_switzerland.mbtiles -p 8080
```

Then open `http://localhost:8080` in your browser.

### Serve with a config file

Create `config.json`:

```json
{
  "options": {
    "port": 8080,
    "cors": true,
    "serveStatic": true,
    "serveStyles": true,
    "servePreview": true,
    "paths": {
      "root": "",
      "fonts": "fonts",
      "styles": "styles",
      "files": "public/files"
    }
  },
  "data": {
    "zurich": {
      "mbtiles": "zurich_switzerland.mbtiles"
    }
  },
  "styles": {}
}
```

Start the server:

```bash
mbtileserver -c config.json -p 8080
```

## Development

Run in development mode with hot-reload (via nodemon):

```bash
npm run dev
```

This watches `src/` and `public/` for changes and auto-restarts the server.

## CLI Options

| Option | Description | Default |
|--------|-------------|---------|
| `--file <file>` | MBTiles or PMTiles file | — |
| `-c, --config <file>` | Configuration file | `config.json` |
| `-p, --port <port>` | Server port | `8080` |
| `-b, --bind <address>` | Bind address | `0.0.0.0` |
| `-u, --public_url <url>` | Public URL (for reverse proxy) | — |
| `-C, --no-cors` | Disable CORS headers | — |
| `--ignore-missing-files` | Skip missing data sources on startup | — |
| `-V, --verbose [level]` | Verbose logging (1-3) | — |
| `-s, --silent` | Less output | — |
| `-v, --version` | Show version | — |
| `-h, --help` | Show help | — |

## API Endpoints

| Endpoint | Description |
|----------|-------------|
| `/` | Home page with map preview |
| `/data` | List all data sources |
| `/data/{id}.json` | TileJSON metadata |
| `/data/{id}/{z}/{x}/{y}.pbf` | Vector tiles |
| `/files/{path}` | Static files (fonts, sprites, images) |
| `/styles/{id}.json` | GL style JSON |

## Viewer Features

The built-in MapLibre viewer (`/data/{id}`) provides a rich layer management UI:

- **Layer list** — Right-side panel showing all layers with type icons (fill/line/circle/symbol)
- **Search & filter** — Quick filter layers by name
- **Visibility toggle** — Checkbox to show/hide individual layers
- **Drag & drop reorder** — Drag layers to change draw order
- **Inline rename** — Double-click layer name to edit its ID
- **Duplicate** — Click `+` to clone a layer with identical style
- **Style editor** — Click layer color box to open modal with:
  - Live JSON editor with syntax highlighting
  - Cascading preset dropdowns (type + category) for quick style defaults
  - Color swatch extraction — double-click to pick colors
  - Native color picker integration
- **Layer order modal** — Top-left button to reorder source-layers via textarea
- **Style upload/download** — Import/export full MapLibre style.json
- **Map click picking** — Click on map to query features and jump to layers

## Data Sources

### MBTiles

Standard SQLite-based tile archive. Download sample data from [OpenMapTiles](https://data.maptiler.com/downloads/planet/) or generate your own.

```bash
mbtileserver data.mbtiles
```

### PMTiles

Cloud-optimized format supporting remote HTTP(S) sources:

```bash
mbtileserver https://example.com/data.pmtiles
```

### GeoJSON

Serve vector tiles from a folder of GeoJSON files. Add a top-level `geojson` section to your `config.json`:

```json
{
  "geojson": {
    "sample": "geojson/sample"
  }
}
```

Each sub-folder is treated as one map, and each `.geojson` file inside becomes a vector layer. Tiles are generated on demand and cached in a `_mbtiles` sub-folder as an MBTiles file. Source file hashes are used to invalidate the cache when files change.

## Static Files

Place custom fonts, sprites, images, or any static assets in `public/files/` (or configure via `options.paths.files`). They become accessible at:

```
http://localhost:8080/files/sprite.png
http://localhost:8080/files/custom-font/{range}.pbf
```

In your `style.json`, reference local files with the `local://files/` protocol:

```json
{
  "sprite": "local://files/sprite",
  "glyphs": "local://fonts/{fontstack}/{range}.pbf"
}
```

## Security: Host Header Poisoning Mitigation

When started **without** `--public_url`, response URLs are built from request headers (`Host`, `X-Forwarded-*`). For production deployments, either:

1. **Set a public URL:**
   ```bash
   mbtileserver --public_url https://tiles.example.com/ --file data.mbtiles
   ```

2. **Restrict allowed hosts:**
   ```bash
   export TILESERVER_GL_ALLOWED_HOSTS="localhost,tiles.example.com"
   mbtileserver --file data.mbtiles
   ```

## License

BSD-2-Clause. See [LICENSE.md](LICENSE.md).

Copyright (c) 2023 MapTiler.com, 2016 Klokan Technologies GmbH.