Tegola

Tegola is a vector tile server delivering Mapbox Vector Tiles leveraging PostGIS as the data provider.

Features

• Native geometry processing (simplification, clipping, make valid, intersection, contains, scaling, translation)
• Mapbox Vector Tile v2 specification compliant .
• Embedded viewer with auto generated style for quick data visualization and inspection.
• Support for PostGIS as a data provider. Extensible to support additional data providers.
• Local filesystem caching. Extensible design to support additional cache backends.
• Parallelized tile serving and geometry processing.
• Support for Web Mercator (3857) and WGS84 (4326) projections.

Running Tegola

1. Download the appropriate binary of tegola for your platform via the release page.
2. Setup your config file and run. Tegola expects a config.toml to be in the same directory as the binary. You can set a different location for the config.toml using a command flag:

./tegola -config=/path/to/config.toml

Server Endpoints

/

The server root will display a built in viewer with an auto generated style. For example:

/maps/:map_name/:z/:x/:y

Return vector tiles for a map. The URI supports the following variables:

• :map_name is the name of the map as defined in the config.toml file.
• :z is the zoom level of the map.
• :x is the row of the tile at the zoom level.
• :y is the column of the tile at the zoom level.

/maps/:map_name/:layer_name/:z/:x/:y

Return vector tiles for a map layer. The URI supports the same variables as the map URI with the additional variable:

• :layer_name is the name of the map layer as defined in the config.toml file.

/capabilities

Return a JSON encoded list of the server's configured maps and layers with various attributes.

/capabilities/:map_name

Return TileJSON details about the map.

/capabilities/:map_name/style.json

Return an auto generated Mapbox GL Style for the configured map.

Configuration

The tegola config file uses the TOML format. The following example shows how to configure a PostGIS data provider with two layers. The first layer includes a tablename, geometry_field and an id_field. The second layer uses a custom sql statement instead of the tablename property.

Under the maps section, map layers are associated with data provider layers and their min_zoom and max_zoom values are defined. Optionally, default_tags can be setup which will be encoded into the layer. If the same tags are returned from a data provider, the data provider's values will take precedence.

[webserver]
port = ":9090"              # port to bind the web server to. defaults ":8080"

[cache]                     # configure a tile cache
type = "file"               # a file cache will cache to the local file system
basepath = "/tmp/tegola"    # where to write the file cache

# register data providers
[[providers]]
name = "test_postgis"       # provider name is referenced from map layers (required)
type = "postgis"            # the type of data provider. currently only supports postgis (required)
host = "localhost"          # postgis database host (required)
port = 5432                 # postgis database port (required)
database = "tegola"         # postgis database name (required)
user = "tegola"             # postgis database user (required)
password = ""               # postgis database password (required)
srid = 3857                 # The default srid for this provider. Defaults to WebMercator (3857) (optional)
max_connections = "50"      # The max connections to maintain in the connection pool. Default is 100. (optional)

	[[providers.layers]]
	name = "landuse"                    # will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857"  # sql or table_name are required
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"                # geom id field. default is gid
	srid = 4326                         # the srid of table's geo data. Defaults to WebMercator (3857)

	[[providers.layers]]
	name = "roads"                      # will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857"  # sql or table_name are required
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"                # geom id field. default is gid
	fields = [ "class", "name" ]        # Additional fields to include in the select statement.

	[[providers.layers]]
	name = "rivers" 					# will be encoded as the layer name in the tile
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"              # geom id field. default is gid
	# Custom sql to be used for this layer. Note: that the geometery field is wraped
	# in a ST_AsBinary, as tegola only understand wkb.
	sql = """
        SELECT
            gid,
            ST_AsBinary(geom) AS geom
        FROM
            gis.rivers
        WHERE
            geom && !BBOX!
	"""

# maps are made up of layers
[[maps]]
name = "zoning"                              # used in the URL to reference this map (/maps/:map_name)

	[[maps.layers]]
	provider_layer = "test_postgis.landuse"	 # must match a data provider layer
	min_zoom = 12                            # minimum zoom level to include this layer
	max_zoom = 16                            # maximum zoom level to include this layer

		[maps.layers.default_tags]		     # table of default tags to encode in the tile. SQL statements will override
		class = "park"

	[[maps.layers]]
	provider_layer = "test_postgis.rivers"   # must match a data provider layer
	min_zoom = 10                            # minimum zoom level to include this layer
	max_zoom = 18                            # maximum zoom level to include this layer

Supported PostGIS SQL tokens

The following tokens are supported in custom SQL queries for the PostGIS data provider:

• !BBOX! - [required] Will convert the z/x/y values into a bounding box to query the feature table with.
• !ZOOM! - [optional] Pass in the zoom value for the request. Useful for filtering feature results by zoom.

Command line flags

Tegola supports the following command flags:

• config - Location of config file in TOML format. Can be absolute, relative or remote over http(s).
• port - Port for the webserver to bind to. i.e. :8080
• log-file - Path to write webserver tile request logs
• log-format - The format that the logger will log with. Available fields:
  • {{.Time}} : The current Date Time in RFC 2822 format.
  • {{.RequestIP}} : The IP address of the the requester.
  • {{.Z}} : The Zoom level.
  • {{.X}} : The X Coordinate.
  • {{.Y}} : The Y Coordinate.

Debugging

Environment Variables

The following environment variables can be used for debugging:

SQL_DEBUG specify the type of SQL debug information to output. Currently support two values:

• LAYER_SQL: print layer SQL as they are parsed from the config file.
• EXECUTE_SQL: print SQL that is executed for each tile request and the number of items it returns or an error.

TEGOLA_OPTIONS specify a set of options comma (or space) seperated options.

• DontSimplifyGeo to turn off simplification for all layers.
• SimplifyMaxZoom={{int}} to set the max zoom that simplification will apply to. (14 is default)

Usage

$ SQL_DEBUG=LAYER_SQL tegola -config=/path/to/conf.toml

Client side

When debugging client side, it's often helpful to to see an outline of a tile along with it's Z/X/Y values. To encode a debug layer into every tile add the query string variable debug=true to the URL template being used to request tiles. For example:

http://localhost:8080/maps/mymap/{z}/{x}/{y}.vector.pbf?debug=true

The requested tile will be encode a layer with the name value set to debug and include two features:

• debug_outline: a line feature that traces the border of the tile
• debug_text: a point feature in the middle of the tile with the following tags:
  • zxy: a string with the Z, X and Y values formatted as: Z:0, X:0, Y:0

Building from source

Tegola is written in Go and requires Go 1.8+ to compile from source. To build tegola from source, make sure you have Go installed and have cloned the repository to your $GOPATH. Navigate to the repository then run the following commands:

cd cmd/tegola/
go build -o tegola

You will now have a binary named tegola in the current directory which is ready for running.

License

See license file in repo.