A tilelive-based tile server.
JavaScript HTML CSS
Clone or download
Pull request Compare This branch is 1 commit ahead, 106 commits behind mojodna:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
lib
public
.bowerrc
.gitignore
.npmignore
CHANGELOG.md
README.md
bower.json
package.json
server.js

README.md

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.