Repository files navigation

Tegola is a vector tile server deliveringMapbox Vector Tiles with support forPostGIS,GeoPackage andSAP HANA Spatial data providers. User documentation can be found attegola.io

• Native geometry processing (simplification, clipping, make valid, intersection, contains, scaling, translation)
• Mapbox Vector Tile v2 specification compliant.
• An embedded viewer with an automatically generated style for quick data visualization and inspection.
• Support forPostGIS andGeoPackage data providers. Extensible design to support additional data providers.
• Support for several cache backends:file,s3,redis,azure blob store.
• Cache seeding and invalidation via individual tiles (ZXY), lat / lon bounds and ZXY tile list.
• Parallelized tile serving and geometry processing.
• Support for Web Mercator (3857) and WGS84 (4326) projections.
• Support forAWS Lambda.
• Support for serving HTTPS.
• Support forPostGIS ST_AsMVT.
• Support forPrometheus observability.

tegola is a vector tile serverVersion: v0.21.0Usage:  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 tegolaFlags:      --config string   path to config file (default "config.toml")  -h, --help            help for tegolaUse "tegola [command] --help" for more information about a command.

1. Download the appropriate binary of tegola for your platform via therelease page.
2. Set up your config file and run. By default, Tegola looks for aconfig.toml in the same directory as the binary. You can set a different location for theconfig.toml using a command flag:

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

/

The server root will display the built-in viewer with an automatically 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 theconfig.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 theconfig.toml file.

/capabilities

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

/capabilities/:map_name

ReturnTileJSON details about the map.

/maps/:map_name/style.json

Return an auto generatedMapbox GL Style for the configured map.

The tegola config file uses theTOML format. The following example shows how to configure amvt_postgis data provider. Themvt_postgis provider will leverage PostGIS'sST_AsMVT() function for the encoding of the vector tile.

Under themaps section, map layers are associated with data provider layers and theirmin_zoom andmax_zoom values are defined.

# register a MVT data provider. MVT data providers have the prefix "mvt_" in their type# note mvt data providers can not be conflated with any other providers of any type in a map# thus a map may only contain a single mvt provider.[[providers]]name ="my_postgis"# provider name is referenced from map layers (required).type ="mvt_postgis"# the type of data provider must be "mvt_postgis" for this data provider (required)uri ="postgresql://tegola:<password>@localhost:5432/tegola?ssl_mode=prefer"# database connection string  [[providers.layers]]name ="landuse"# MVT data provider must use SQL statements# this table uses "geom" for the geometry_fieldname and "gid" for the id_fieldname so they don't need to be configured# Wrapping the geom with ST_AsMVTGeom is required.sql ="SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX!"# If you want to use the configurable parameters defined in maps.params make sure to include the token in the SQL statementsql ="SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX! !PARAM!"# maps are made up of layers[[maps]]name ="zoning"# used in the URL to reference this map (/maps/zoning)  [[maps.layers]]name ="landuse"# name is optional. If it's not defined the name of the ProviderLayer will be used.provider_layer ="my_postgis.landuse"# must match a data provider layermin_zoom =10# minimum zoom level to include this layermax_zoom =16# maximum zoom level to include this layer# configure addition URL parameters: /maps/:map_name/:layer_name/:z/:x/:y?param=value# which will be passed to the database queries  [[maps.params]]name          ="param"# name used in the URLtoken         ="!PARAM!"# token to replace in providers.layers.sql querytype          ="string"# one of: int, float, string, boolsql           ="AND param = ?"# SQL to replace the token in the query. ? will be replaced with a parameter value. If omitted, defaults to "?"# if neither default_value nor default_sql is specified, the URL parameter is required to be present in all queries# eitherdefault_value ="value"# if parameter is not specified, this value will be passed to .sql parameter# ordefault_sql   =""# if parameter is not specified, this value will replace the .sql parameter. Useful for omitting query entirely

• More information on PostgreSQL SSL modes can be foundhere.
• More information on themvt_postgis provider can be foundhere

Environment variables can be injected into the configuration file. One caveat is that the injection has to be within a string, though the value it represents does not have to be a string.

The above config example could be written as:

# register data providers[[providers]]name ="test_postgis"type ="mvt_postgis"uri ="${POSTGIS_CONN_STR}"# database connection stringsrid =3857max_connections ="${POSTGIS_MAX_CONN}"

The following environment variables can be used for debugging:

TEGOLA_SQL_DEBUG specify the type of SQL debug information to output. Currently, supporting two values:

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

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

The following environment variables can be used to control various runtime options on dataproviders that areNOTmvt_postgis:

TEGOLA_OPTIONS specify a set of options comma or space delimited. Supports the following options

• DontSimplifyGeo to 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 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 variabledebug=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 encoded with a layer that has thename value set todebug and includes the three following features.

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

Tegola is written inGo and requiresGo 1.22 or higher to compile from the source.(We support the two newest versions of Go.)To build tegola from the source, make sure you have Go installed and have cloned the repository.Navigate to the repository then run the following command:

go generate ...&&cd cmd/tegola/&& go build -mod vendor

You will now have a binary namedtegola in the current directory which isready to run.

Build FlagsThe following build flags can be used to turn off certain features of tegola:

• noAzblobCache - turn off the Azure Blob cache back end.
• noS3Cache - turn off the AWS S3 cache back end.
• noRedisCache - turn off the Redis cache back end.
• noPostgisProvider - turn off the PostGIS data provider.
• noGpkgProvider - turn off the GeoPackage data provider. Note, GeoPackage uses CGO and will be turned off if the environment variableCGO_ENABLED=0 is set prior to building.
• noViewer - turn off the built-in viewer.
• pprof - enableGo profiler. Start profile server by setting the environmentTEGOLA_HTTP_PPROF_BIND environment (e.g.TEGOLA_HTTP_PPROF_BIND=localhost:6060).
• noPrometheusObserver - turn off support for the Prometheus metric end point.

Example of using the build flags to turn of the Redis cache back end, the GeoPackage provider and the built-in viewer.

go build -tags'noRedisCache noGpkgProvider noViewer'

Setting Version Information The following flags can be used to set version information:

# first set some env to make it easier to read:BUILD_PKG=github.com/go-spatial/tegola/internal/buildVERSION=1.16.xGIT_BRANCH=$(git branch --no-color --show-current)GIT_REVISION=$(git log HEAD --oneline| head -n 1| cut -d'' -f 1)# build the go binarygo build -ldflags"-w -X${BUILD_PKG}.Version=${VERSION} -X${BUILD_PKG}.GitRevision=${GIT_REVISION} -X${BUILD_PKG}.GitBranch=${GIT_BRANCH}"

Seelicense file in the repo.

After Tegola is running you're likely going to want to work on your map's cartography.Givefresco a try!