Quick start (Docker)

Pull the published image and serve a single dataset. Data is mounted at /data; nothing is baked into the image.

# the published image, linux/amd64 + linux/arm64, no login needed
docker pull ghcr.io/terraops-org/terraserve:0.2.0

# serve a Cloud-Optimized GeoTIFF as WMS + tiles
docker run -p 8080:8080 -v "$PWD/data:/data:ro" ghcr.io/terraops-org/terraserve:0.2.0 \
  serve --cog /data/ortho.cog.tif --style /data/rgb.json \
        --host 0.0.0.0 --port 8080

Then point QGIS at http://localhost:8080/wms, or open the built-in viewer at http://localhost:8080/viewer. To serve a vector dataset instead of a raster, swap --cog/--style for --vector/--vec-style (see the live examples for real commands).

Where the image lives. GitHub files container images somewhere almost nobody finds on the first try, so here is the direct link: github.com/terraops-org/TerraServe/pkgs/container/terraserve. Tags are 0.2.0 (pinned), latest, and edge (built from main). Prefer to build it yourself? docker build -t terraserve . from the repo root does the same thing.

docker-compose

For anything long-lived, a compose file is cleaner: one service per dataset (their flags are often mutually exclusive, and isolating them means one busy layer can't take another down).

services:
  terraserve:
    image: terraserve:latest
    ports: ["8080:8080"]
    volumes:
      - ./data:/data:ro
    ulimits:
      nofile: { soft: 65536, hard: 65536 }   # a public tile server holds many handles
    command:
      - serve
      - --host
      - "0.0.0.0"
      - --cog
      - /data/ortho.cog.tif
      - --style
      - /data/rgb.json
      - --public-url
      - https://maps.example.org/wms        # see Pitfalls
    restart: unless-stopped

Data & styling

For how to write these styles, RGB, colour ramps, SLD, and MapLibre styles, with examples, see the Styling guide.

Serving & network

Caching & tiles

Vector tuning

Tile grids

Most tile servers speak one grid, Web Mercator, and everything else is somebody else's problem. TerraServe treats the grid as data: hand it an OGC TileMatrixSet 2.0 JSON file and it serves tiles on that grid, for both vector tiles and pre-rendered pictures. No code, no plugin, no rebuild. A layer can publish on several at once.

layers:
  - name: buildings
    vector: /data/buildings.fgb
    vec_style: /data/buildings.vec.json
    src_crs: EPSG:3035
    # the same layer, on two grids at once
    grids: [WebMercatorQuad, /data/grids/EuropeanETRS89_LAEAQuad.json]

Every published grid is served as its own document at /tileMatrixSets/{id}, and both viewers build their map straight from that response, so the client never guesses at tile geometry. The demos use this for the Swiss national grid (swissLV95, EPSG:2056) and for the EU's own EuropeanETRS89_LAEAQuad (EPSG:3035), the equal-area grid INSPIRE specifies for pan-European data.

PostGIS as a source (EXPERIMENTAL)

A layer's data can be a PostGIS table instead of a file. The split of work is deliberate and worth stating plainly: PostGIS stores, TerraServe renders. Each tile becomes one bounding-box query over the table's spatial index; the geometry comes back as WKB and every reprojection, simplification, styling and encoding step runs in the engine, exactly as it would from a file. Nothing is pushed into SQL that would make the database do rendering work.

layers:
  - name: buildings
    vector: postgis://postgres:${PGPASS}@db:5432/osm/public.osm_buildings
    vec_style: /data/buildings.vec.json
    src_crs: EPSG:3035
    extent: [3155046.0, 2026265.0, 4673364.0, 3550864.0]   # required
    grids: [WebMercatorQuad, /data/grids/EuropeanETRS89_LAEAQuad.json]

This is the setup behind the EU demo: 154.8 million OpenStreetMap features across five countries, served live out of a 63 GB database, with the heavy zoom levels pre-baked to tile archives so the database is never asked a continental question at request time.

Multi-layer YAML

Serve many layers from one process with --config layers.yaml. Each layer sets its own data, projection and style; a raster layer uses cog:, a vector layer uses vector: + vec_style:.

layers:
  # NDVI computed live from a Sentinel-2 stack on S3
  - name: ndvi
    cog: s3://your-bucket/s2_stack.cog.tif
    src_crs: EPSG:32629
    s3_endpoint: https://s3.gra.io.cloud.ovh.net
    s3_region: gra
    nodata: -32768
    bands: { B02: 1, B03: 2, B04: 3, B08: 4 }
    expression: "(B08 - B04) / (B08 + B04)"
    style: fixtures/styles/ndvi.json

  # A plain RGB orthophoto from a local COG
  - name: cascais
    cog: ../cogs/cascais.cog.deflate.tif
    src_crs: EPSG:3763
    style: fixtures/styles/rgb.json

docker run … terraserve serve --config /data/layers.yaml. A client picks a layer with LAYERS=ndvi (WMS) or /mvt/ndvi/… (tiles). S3 credentials come from the environment (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY).

Serve from object storage (S3)

Any path can be an s3://… URL, not only the data. TerraServe reads the FlatGeoBuf, its style and the label font straight from the bucket, so a container can ship with nothing on disk. A windowed layer still reads only the byte ranges it needs, so it stays light even when the file lives in the cloud.

terraserve serve \
  --vector    s3://your-bucket/vector/roads.fgb \
  --vec-style s3://your-bucket/style/roads.style.json \
  --font      s3://your-bucket/font/DejaVuSans.ttf \
  --name roads --port 8080

The folders above are just key prefixes, so organise the bucket however you like. In a --config YAML, point vector: and vec_style: at s3://… too. Credentials come from the environment (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY), the endpoint and region from AWS_ENDPOINT_URL / AWS_REGION, or the --s3-endpoint / --s3-region flags.

Python bindings

A terraserve wheel wraps the same render core as a plain Python function: render_png() takes a COG window and returns PNG bytes, byte-identical to the CLI. Preview, v0.2.0, raster only (vector/labels and NDVI aren't wired into the binding yet). Walkthrough with a real render: the Python example.

# not on PyPI yet: install straight from the GitHub release (abi3 + aarch64 wheels too)
pip install https://github.com/terraops-org/TerraServe/releases/download/v0.2.0/terraserve-0.2.0-cp39-abi3-manylinux_2_28_x86_64.whl

import terraserve

png = terraserve.render_png(
    cog_path="cascais.cog.deflate.tif", bbox=(-9.45, 38.68, -9.38, 38.72),
    crs="EPSG:4326", src_crs="EPSG:3763", width=512, height=512,
    style="rgb.json", resample="bilinear",
)
open("cascais.png", "wb").write(png)

The wheel also ships a drop-in type: map provider for pygeoapi's OGC API - Maps, referenced by its dotted path, no pygeoapi core change needed:

providers:
  - type: map
    name: terraserve.pygeoapi.TerraServeProvider
    data: /data/cascais.cog.tif
    options:
      src_crs: EPSG:3763
      style: /data/rgb.json

Endpoints

Rendering

Rendering runs on two separate paths, one for raster and one for vector. They only meet at the finished PNG or tile.

Raster. A Cloud-Optimized GeoTIFF is decoded, reprojected and resampled by TerraServe's own kernels: the tile is read from the COG, warped from its source CRS into the grid you asked for (nearest or bilinear), then coloured, RGB passthrough, a pseudocolor ramp, or on-the-fly band math. No third-party imaging library touches this path; it is the engine core in render.rs.

Vector. Drawing geometry is a different problem: filling polygons, stroking lines and placing markers with clean anti-aliased edges. That rasterization is done with tiny-skia (in vector/raster.rs). The vector tile formats built on top, MVT and PMTiles, are written from scratch: a hand-rolled protobuf encoder (varints, tags, zigzag-delta geometry) and a bespoke PMTiles reader and writer, no prost and no tile library.

Pitfalls

The things that cost someone a night. Read these before you deploy.

Other commands

serve is one of five subcommands. The others draw a single PNG, bake an offline tile pyramid, or inspect a coverage. Each has a runnable example and its flags on the CLI reference.

CLI reference ->See real commands on the examples ->