tessera

tessera is a tilelive-based tile server.

Using the power of the tilelive ecosystem, it is capable of serving and rendering tiles from many sources.

Installation

npm install -g tessera
npm install -g <tilelive modules...>

How to Use

tessera does not install tilelive providers itself; it is up to you to (globally) install any modules that you wish to use (along with dependencies present in your configuration; e.g. a TM2 style that loads data tiles from an HTTP source).

Modules listed in tilelive-modules will be auto-detected and loaded if they have been installed. For other modules, you will need to --require them explicitly.

To serve up an MBTiles archive using node-mbtiles:

npm install -g mbtiles
tessera mbtiles://./whatever.mbtiles

To serve up a TileMill (or Carto) project using tilelive-carto:

tessera carto+file://./project.mml

To serve up a TM2 style using tilelive-tmstyle:

tessera tmstyle://./

Note: non-mapbox: sources may need to have their protocols changed; tessera requires that styles using HTTP-accessible data have tilejson+http: as their protocol where TM2 expects http:. See mojodna/tilelive-http#2 for more information.

To serve up a TM2 data source (it will use data.yml as the source of truth) using tilelive-tmsource:

tessera tmsource://./

To serve up a bare Mapnik stylesheet using tilelive-mapnik:

tessera mapnik://./stylesheet.xml

To serve up files from a filesystem using tilelive-file:

tessera file://./tiles

To proxy HTTP-accessible tiles using tilelive-http:

tessera http://tile.stamen.com/toner/{z}/{x}/{y}.png

To proxy Mapbox-hosted tiles using tilelive-mapbox:

tessera mapbox:///mapbox.mapbox-streets-v4

To proxy tiles with available TileJSON using node-tilejson:

tessera tilejson+http://a.tiles.mapbox.com/v3/mapbox.mapbox-streets-v4.json

A TileJSON endpoint is available at localhost:8080/index.json with various bits of metadata about the tiles being served.

Configuration

Tessera has command-line options:

Usage: node tessera.js [uri] [options]

uri     tilelive URI to serve

Options:
   -C SIZE, --cache-size SIZE          Set the cache size (in MB)  [10]
   -c CONFIG, --config CONFIG          Provide a configuration file
   -p PORT, --port PORT                Set the HTTP Port  [8080]
   -r MODULE, --require MODULE         Require a specific tilelive module
   -S SIZE, --source-cache-size SIZE   Set the source cache size (in # of sources)  [10]
   -v, --version                       Show version info

A tilelive URI or configuration file is required.

Commonly used options can be set using the TESSERA_OPTS environment variable.

This is what a configuration file looks like:

{
  "/": {
    "source": "mbtiles:///Users/seth/archive.mbtiles",
    "cors": false,
    "timing": false
  },
  "/a": {
    "source": "mbtiles:///Users/seth/archive.mbtiles",
    "headers": {
      "Cache-Control": "public,max-age={{#tileJSON}}86400{{/tileJSON}}{{#tile}}3600{{/tile}}",
      "Surrogate-Control": "max-age=86400",
      "Surrogate-Keys": "{{#tile}}z{{zoom}} x{{x}} y{{y}}{{/tile}}"
    }
  },
  "/b": "mbtiles:///Users/seth/archive.mbtiles"
}

Header values are treated as Mustache (technically Handlebars) templates, which allow them to vary by request. The following variables are available to header templates:

• tile.retina - for retina (@2x) requests
• tile.zoom - zoom (for tile requests)
• tile.x - row (for tile requests)
• tile.y - column (for tile requests)
• tile.format - requested format
• tileJSON - for TileJSON requests
• 200 - HTTP 200
• 404 - HTTP 404
• invalidFormat - the requested format did not match what the tilelive source provides
• invalidZoom - the requested zoom is outside the available range
• invalidCoordinates - the requested coordinates are outside the available bounds

CORS and X-Response-Time can be disabled per-style:

{
  "cors": false,
  "timing": false
}

(Note that enabling for / will propagate to all subdirectories, as they act as middleware.)

Custom tile paths may be set per-style:

{
  "tilePath": "/{z}/{x}/{y}-debug.{format}"
}

The default tile path is:

{
  "tilePath": "/{z}/{x}/{y}.{format}"
}

(Note: the final . will be expanded to transparently support retina requests (effectively /{z}/{x}/{y}@2x.{format}).)

Environment Variables

• PORT - Port to bind to. Defaults to 8080.
• CACHE_SIZE - Cache size (in MB) for tilelive-cache. Defaults to 10MB.
• SOURCE_CACHE_SIZE - Number of sources to cache (for tilelive-cache). Defaults to 6. NOTE: implicit retina versions count as an extra source.
• TESSERA_OPTS - Additional command-line arguments.