Configuration file

The configuration file defines the behavior of the application. It’s a regular JSON file.

Example:

{
  "options": {
    "paths": {
      "root": "",
      "fonts": "fonts",
      "sprites": "sprites",
      "styles": "styles",
      "mbtiles": ""
    },
    "domains": [
      "localhost:8080",
      "127.0.0.1:8080"
    ],
    "formatQuality": {
      "jpeg": 80,
      "webp": 90,
      "pngQuantization": false,
      "png": 90
    },
    "maxScaleFactor": 3,
    "maxSize": 2048,
    "pbfAlias": "pbf",
    "serveAllFonts": false,
    "serveStaticMaps": true
  },
  "styles": {
    "basic": {
      "style": "basic.json",
      "tilejson": {
        "type": "overlay",
        "bounds": [8.44806, 47.32023, 8.62537, 47.43468]
      }
    },
    "hybrid": {
      "style": "satellite-hybrid.json",
      "serve_rendered": false,
      "tilejson": {
        "format": "webp"
      }
    }
  },
  "data": {
    "zurich-vector": {
      "mbtiles": "zurich.mbtiles"
    }
  }
}

options

paths

Defines where to look for the different types of input data.

The value of root is used as prefix for all data types.

domains

You can use this to optionally specify on what domains the rendered tiles are accessible. This can be used for basic load-balancing or to bypass browser’s limit for the number of connections per domain.

frontPage

Path to the html (relative to root path) to use as a front page.

Use true (or nothing) to serve the default TileServer GL front page with list of styles and data. Use false to disable the front page altogether (404).

formatQuality

Quality of the compression of individual image formats. [0-100]

The value for png is only used when pngQuantization is true.

maxScaleFactor

Maximum scale factor to allow in raster tile and static maps requests (e.g. @3x suffix). Also see maxSize below. Default value is 3, maximum 9.

maxSize

Maximum image side length to be allowed to be rendered (including scale factor). Be careful when changing this value since there are hardware limits that need to be considered. Default is 2048.

watermark

Optional string to be rendered into the raster tiles (and static maps) as watermark (bottom-left corner). Can be used for hard-coding attributions etc. (can also be specified per-style). Not used by default.

styles

Each item in this object defines one style (map). It can have the following options:

  • style – name of the style json file [required]
  • serve_rendered – whether to render the raster tiles for this style or not
  • serve_data – whether to allow acces to the original tiles, sprites and required glyphs
  • tilejson – properties to add to the TileJSON created for the raster data
    • format and bounds can be especially useful

data

Each item specifies one data source which should be made accessible by the server. It has the following options:

  • mbtiles – name of the mbtiles file [required]

The mbtiles file does not need to be specified here unless you explicitly want to serve the raw data.

Referencing local files from style JSON

You can link various data sources from the style JSON (for example even remote TileJSONs).

MBTiles

To specify that you want to use local mbtiles, use to following syntax: mbtiles://switzerland.mbtiles. The TileServer-GL will try to find the file switzerland.mbtiles in root + mbtiles path.

For example:

"sources": {
  "source1": {
    "url": "mbtiles://switzerland.mbtiles",
    "type": "vector"
  }
}

Alternatively, you can use mbtiles://{zurich-vector} to reference existing data object from the config. In this case, the server will look into the config.json to determine what mbtiles file to use. For the config above, this is equivalent to mbtiles://zurich.mbtiles.

Sprites

If your style requires any sprites, make sure the style JSON contains proper path in the sprite property.

It can be a local path (e.g. my-style/sprite) or remove http(s) location (e.g. https://mycdn.com/my-style/sprite). Several possible extension are added to this path, so the following files should be present:

  • sprite.json
  • sprite.png
  • sprite@2x.json
  • sprite@2x.png

You can also use the following placeholders in the sprite path for easier use:

  • {style} – gets replaced with the name of the style file (xxx.json)
  • {styleJsonFolder} – gets replaced with the path to the style file

Fonts (glyphs)

Similarly to the sprites, the style JSON also needs to contain proper paths to the font glyphs (in the glyphs property) and can be both local and remote.

It should contain the following placeholders:

  • {fontstack} – name of the font and variant
  • {range} – range of the glyphs

For example "glyphs": "{fontstack}/{range}.pbf" will instruct TileServer-GL to look for the files such as fonts/Open Sans/0-255.pbf (fonts come from the paths property of the config.json example above).