Tegola is a vector tile server delivering Mapbox Vector Tiles leveraging PostGIS as the data provider.
- 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.
- Cache seeding to fill the cache prior to web requests.
- Parallelized tile serving and geometry processing.
- Support for Web Mercator (3857) and WGS84 (4326) projections.
tegola is a vector tile server
Version: v0.5.0
Usage:
tegola [command]
Available Commands:
cache Manipulate the tile cache
help Help about any command
serve Use tegola as a tile server
version Print the version number of tegola
Flags:
--config string path to config file (default "config.toml")
-h, --help help for tegola
Use "tegola [command] --help" for more information about a command.
- Download the appropriate binary of tegola for your platform via the release page.
- Setup your config file and run. Tegola expects a
config.tomlto be in the same directory as the binary. You can set a different location for theconfig.tomlusing a command flag:
./tegola serve --config=/path/to/config.toml
/
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_nameis the name of the map as defined in theconfig.tomlfile.:zis the zoom level of the map.:xis the row of the tile at the zoom level.:yis 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_nameis the name of the map layer as defined in theconfig.tomlfile.
/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.
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() and the use of the !BBOX! token
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 layerThe 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.
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.
$ SQL_DEBUG=LAYER_SQL tegola -config=/path/to/conf.tomlThe following environment variables can be use to control various runtime options:
TEGOLA_OPTIONS specify a set of options comma (or space) seperated options.
DontSimplifyGeoto turn off simplification for all layers.SimplifyMaxZoom={{int}}to set the max zoom that simplification will apply to. (14 is default)
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 tiledebug_text: a point feature in the middle of the tile with the following tags:zxy: a string with theZ,XandYvalues formatted as:Z:0, X:0, Y:0
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 tegolaYou will now have a binary named tegola in the current directory which is ready for running.
See license file in repo.