tile-server-lite: on-the-fly MVT tile server with MapLibre preview and Docker deploy

Author: python-geospatial

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Lint with ruff
+        run: ruff check .
+
+      - name: Run tests
+        run: pytest -q

.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Local data mounted into the server
+/data/
+*.gpkg
+*.geoparquet
+*.parquet
+
+# Editor / OS
+.idea/
+.vscode/
+.DS_Store

Dockerfile

@@ -0,0 +1,26 @@
+# tile-server-lite — single-file container.
+# Build:  docker build -t tile-server-lite .
+# Run:    docker run --rm -v $(pwd)/data:/data -p 8080:8080 tile-server-lite \
+#             serve /data/parcels.gpkg --host 0.0.0.0 --port 8080
+FROM python:3.12-slim
+
+# GeoPandas/pyogrio wheels bundle GDAL, but a couple of runtime libs help.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends libexpat1 \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1
+
+WORKDIR /app
+COPY pyproject.toml README.md ./
+COPY src ./src
+RUN pip install --upgrade pip && pip install .
+
+# Mount your vector files here: -v $(pwd)/data:/data
+VOLUME ["/data"]
+WORKDIR /data
+EXPOSE 8080
+
+ENTRYPOINT ["tile-server-lite"]
+CMD ["--help"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 python-geospatial.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,170 @@
+# tile-server-lite
+
+> From a local vector file to a live slippy map in one command — on-the-fly Mapbox Vector Tiles with a built-in MapLibre preview.
+
+[![CI](https://github.com/python-geospatial/tile-server-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/python-geospatial/tile-server-lite/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+`tile-server-lite` is a minimal [FastAPI](https://fastapi.tiangolo.com/) server that reads any
+[geopandas](https://geopandas.org/)-readable vector file — GeoPackage, GeoParquet, GeoJSON,
+Shapefile — and serves it as XYZ **Mapbox Vector Tiles (MVT)**, cut on the fly. Point it at a file,
+open your browser, and you get a working [MapLibre GL JS](https://maplibre.org/) map fit to your
+data's bounds.
+
+Maintained by [python-geospatial.com](https://python-geospatial.com), a knowledge base for the
+modern Python geospatial stack.
+
+## What & why
+
+Static vector tile pipelines (Tippecanoe, PMTiles) are the right call for large, published datasets.
+But while you are *exploring* — checking a fresh export, sharing a quick preview, iterating on a
+layer — pre-baking tiles is friction. `tile-server-lite` cuts tiles per request straight from your
+file, so there is no build step between "I have a file" and "I have a map".
+
+It complements, rather than replaces, the static [PMTiles](https://python-geospatial.com/web-mapping-interactive-visualization/vector-tile-pipelines-with-pmtiles/)
+workflow covered on the site: use this server for local development and previews, then bake to
+PMTiles for production hosting (see [How it works](#how-it-works)).
+
+## Install
+
+Not published to PyPI — install straight from the repository:
+
+```bash
+pip install "git+https://github.com/python-geospatial/tile-server-lite.git"
+```
+
+Or clone and install in editable mode:
+
+```bash
+git clone https://github.com/python-geospatial/tile-server-lite.git
+cd tile-server-lite
+pip install -e ".[dev]"
+```
+
+## Usage
+
+Serve a single GeoPackage:
+
+```bash
+tile-server-lite serve parcels.gpkg
+```
+
+Serve several files at once (each layer is named after its file stem), on a chosen host/port and
+zoom window:
+
+```bash
+tile-server-lite serve parcels.gpkg sensors.geoparquet \
+    --host 0.0.0.0 --port 8080 --min-zoom 6 --max-zoom 18
+```
+
+Example startup output:
+
+```
+                      tile-server-lite
+┏━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃ Layer   ┃ Geometry ┃ Features ┃ TileJSON                                 ┃
+┡━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│ parcels │ Polygon  │    1 240 │ http://127.0.0.1:8080/tilejson/parcels…  │
+│ sensors │ Point    │      317 │ http://127.0.0.1:8080/tilejson/sensors…  │
+└─────────┴──────────┴──────────┴──────────────────────────────────────────┘
+Preview map: http://127.0.0.1:8080/  · Served by python-geospatial.com
+```
+
+Then:
+
+- open [http://127.0.0.1:8080/](http://127.0.0.1:8080/) for the MapLibre preview,
+- fetch a tile at `GET /tiles/parcels/16/35208/21489.mvt`,
+- fetch the TileJSON at `GET /tilejson/parcels.json`.
+
+Example TileJSON response (abridged):
+
+```json
+{
+  "tilejson": "3.0.0",
+  "name": "parcels",
+  "scheme": "xyz",
+  "tiles": ["http://127.0.0.1:8080/tiles/parcels/{z}/{x}/{y}.mvt"],
+  "minzoom": 6,
+  "maxzoom": 18,
+  "bounds": [13.4028, 52.5185, 13.4098, 52.5232],
+  "vector_layers": [
+    {"id": "parcels", "geometry_type": "Polygon",
+     "fields": {"parcel_id": "Integer", "zoning": "String"}}
+  ]
+}
+```
+
+## Deploy with Docker
+
+A single-file `Dockerfile` is included. Build the image, then mount a directory of vector files at
+`/data`:
+
+```bash
+docker build -t tile-server-lite .
+
+docker run --rm \
+    -v $(pwd)/data:/data \
+    -p 8080:8080 \
+    tile-server-lite serve /data/parcels.gpkg --host 0.0.0.0 --port 8080
+```
+
+The map is then live at [http://localhost:8080/](http://localhost:8080/). Binding to `0.0.0.0`
+inside the container lets the published port reach the server; keep it on `127.0.0.1` when running
+directly on your machine.
+
+## Features
+
+- **Any geopandas-readable input** — GeoPackage, GeoParquet, GeoJSON, Shapefile, and more.
+- **True MVT** — geometries clipped to each tile (with an edge buffer) and encoded with
+  `mapbox-vector-tile` in the standard 0–4096 grid.
+- **Spatial-index-backed selection** — only features intersecting a tile are considered.
+- **Valid TileJSON 3.0.0** — with 4326 bounds, zoom window, and `vector_layers` metadata.
+- **Built-in MapLibre preview** — served at `/`, auto-styled per geometry type, fit to bounds.
+- **Correct CRS handling** — reprojects once to Web Mercator for tiling; refuses files with a
+  missing CRS instead of guessing silently.
+- **One-file Docker deploy** and a friendly `click` + `rich` CLI.
+
+## How it works
+
+For each requested `z/x/y` tile the server:
+
+1. computes the tile's EPSG:3857 bounding box with [`mercantile`](https://github.com/mapbox/mercantile),
+2. queries the layer's spatial index for intersecting features,
+3. clips them to the (buffered) tile box with Shapely,
+4. affine-transforms the clipped coordinates into the MVT 0–4096 grid (origin top-left, y down),
+5. encodes the result with `mapbox-vector-tile`.
+
+The source file is reprojected to **EPSG:3857 exactly once**, at load time, because web map tiles
+are *defined* in Web Mercator. That is correct here — but do not reuse EPSG:3857 for metric analysis
+(areas, distances, buffers), where it distorts badly; use a projected/UTM CRS for measurement
+instead. For production, bake your explored layers into static PMTiles and serve those; this server
+is for the fast local loop before that step.
+
+## Learn more
+
+Deep dives on the concepts behind this tool, from [python-geospatial.com](https://python-geospatial.com):
+
+- [Vector Tile Pipelines with PMTiles](https://python-geospatial.com/web-mapping-interactive-visualization/vector-tile-pipelines-with-pmtiles/)
+- [Generating PMTiles from GeoParquet](https://python-geospatial.com/web-mapping-interactive-visualization/vector-tile-pipelines-with-pmtiles/generating-pmtiles-from-geoparquet/)
+- [Serving GeoJSON to MapLibre GL JS](https://python-geospatial.com/web-mapping-interactive-visualization/maplibre-gl-vector-web-maps/serving-geojson-to-maplibre-gl-js/)
+- [MapLibre GL Vector Web Maps](https://python-geospatial.com/web-mapping-interactive-visualization/maplibre-gl-vector-web-maps/)
+- [Cloud-Native Geospatial Formats](https://python-geospatial.com/geospatial-data-ingestion-processing-workflows/cloud-native-geospatial-formats/)
+
+## Development
+
+```bash
+git clone https://github.com/python-geospatial/tile-server-lite.git
+cd tile-server-lite
+pip install -e ".[dev]"
+
+ruff check .
+pytest -q
+```
+
+Tests generate tiny in-memory geometries in `tmp_path` and run entirely offline — no network access
+and no large fixtures required.
+
+## License
+
+[MIT](LICENSE) · Copyright (c) 2026 python-geospatial.com

pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tile-server-lite"
+version = "0.1.0"
+description = "Minimal FastAPI vector tile server: serve any geopandas-readable vector file as XYZ Mapbox Vector Tiles with a built-in MapLibre preview."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "python-geospatial.com", email = "info@python-geospatial.com" }]
+keywords = [
+    "geospatial",
+    "vector-tiles",
+    "mvt",
+    "maplibre",
+    "fastapi",
+    "geopandas",
+    "web-mapping",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Framework :: FastAPI",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "geopandas>=0.14",
+    "shapely>=2.0",
+    "mercantile>=1.2",
+    "mapbox-vector-tile>=2.0",
+    "click>=8.1",
+    "rich>=13",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4",
+    "ruff>=0.4",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://python-geospatial.com"
+Repository = "https://github.com/python-geospatial/tile-server-lite"
+
+[project.scripts]
+tile-server-lite = "tile_server_lite.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tile_server_lite"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

src/tile_server_lite/__init__.py

@@ -0,0 +1,13 @@
+"""tile-server-lite: serve local vector files as XYZ Mapbox Vector Tiles.
+
+Maintained by python-geospatial.com, a knowledge base for the modern Python
+geospatial stack.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from tile_server_lite.data import LayerSource
+
+__all__ = ["LayerSource", "__version__"]

src/tile_server_lite/__main__.py

@@ -0,0 +1,8 @@
+"""Enable ``python -m tile_server_lite``."""
+
+from __future__ import annotations
+
+from tile_server_lite.cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()