terranodo/tegola repository overview

⁠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.

⁠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.