You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+91-87Lines changed: 91 additions & 87 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -101,19 +101,22 @@ Return [TileJSON](https://github.com/mapbox/tilejson-spec) details about the map
101
101
Return an auto generated [Mapbox GL Style](https://www.mapbox.com/mapbox-gl-js/style-spec/) for the configured map.
102
102
103
103
## Configuration
104
+
104
105
The tegola config file uses the [TOML](https://github.com/toml-lang/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.
105
106
106
107
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.
107
108
109
+
### Example config file:
110
+
108
111
```toml
109
112
[webserver]
110
113
port = ":9090"# port to bind the web server to. defaults ":8080"
111
114
ssl_cert = "fullchain.pem"# ssl cert for serving by https
112
115
ssl_key = "privkey.pem"# ssl key for serving by https
# this table uses "geom" for the geometry_fieldname and "gid" for the id_fieldname so they don't need to be configured
182
-
sql = "SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX!"
136
+
ssl_mode = "prefer"# PostgreSQL SSL mode*. Default is "disable". (optional)
137
+
138
+
[[providers.layers]]
139
+
name = "landuse"# will be encoded as the layer name in the tile
140
+
tablename = "gis.zoning_base_3857"# sql or tablename are required
141
+
geometry_fieldname = "geom"# geom field. default is geom
142
+
id_fieldname = "gid"# geom id field. default is gid
143
+
srid = 4326# the srid of table's geo data. Defaults to WebMercator (3857)
144
+
145
+
[[providers.layers]]
146
+
name = "roads"# will be encoded as the layer name in the tile
147
+
tablename = "gis.zoning_base_3857"# sql or tablename are required
148
+
geometry_fieldname = "geom"# geom field. default is geom
149
+
geometry_type = "linestring"# geometry type. if not set, tables are inspected at startup to try and infer the gemetry type
150
+
id_fieldname = "gid"# geom id field. default is gid
151
+
fields = [ "class", "name" ] # Additional fields to include in the select statement.
152
+
153
+
[[providers.layers]]
154
+
name = "rivers"# will be encoded as the layer name in the tile
155
+
geometry_fieldname = "geom"# geom field. default is geom
156
+
id_fieldname = "gid"# geom id field. default is gid
157
+
# Custom sql to be used for this layer. Note: that the geometery field is wraped
158
+
# in a ST_AsBinary() and the use of the !BBOX! token
159
+
sql = "SELECT gid, ST_AsBinary(geom) AS geom FROM gis.rivers WHERE geom && !BBOX!"
160
+
161
+
[[providers.layers]]
162
+
name = "buildings"# will be encoded as the layer name in the tile
163
+
geometry_fieldname = "geom"# geom field. default is geom
164
+
id_fieldname = "gid"# geom id field. default is gid
165
+
# Custom sql to be used for this layer as a sub query. ST_AsBinary and
166
+
# !BBOX! filter are applied automatically.
167
+
sql = "(SELECT gid, geom, type FROM buildings WHERE scalerank = !ZOOM! LIMIT 1000) AS sub"
183
168
184
169
# maps are made up of layers
185
170
[[maps]]
186
-
name = "zoning"# used in the URL to reference this map (/maps/:map_name)
171
+
name = "zoning"# used in the URL to reference this map (/maps/zoning)
187
172
188
-
[[maps.layers]]
189
-
name = "landuse"# name is optional. If it's not defined the name of the ProviderLayer will be used.
173
+
[[maps.layers]]
174
+
name = "landuse"# name is optional. If it's not defined the name of the ProviderLayer will be used.
190
175
# It can also be used to group multiple ProviderLayers under the same namespace.
191
-
provider_layer = "test_postgis.landuse"# must match a data provider layer
192
-
min_zoom = 12# minimum zoom level to include this layer
193
-
max_zoom = 16# maximum zoom level to include this layer
194
-
195
-
[maps.layers.default_tags] # table of default tags to encode in the tile. SQL statements will override
196
-
class = "park"
176
+
provider_layer = "test_postgis.landuse"# must match a data provider layer
177
+
min_zoom = 12# minimum zoom level to include this layer
178
+
max_zoom = 16# maximum zoom level to include this layer
179
+
180
+
[maps.layers.default_tags] # table of default tags to encode in the tile. SQL statements will override
181
+
class = "park"
182
+
183
+
[[maps.layers]]
184
+
name = "rivers"# name is optional. If it's not defined the name of the ProviderLayer will be used.
185
+
# It can also be used to group multiple ProviderLayers under the same namespace.
186
+
provider_layer = "test_postgis.rivers"# must match a data provider layer
187
+
dont_simplify = true# optionally, turn off simplification for this layer. Default is false.
188
+
dont_clip = true# optionally, turn off clipping for this layer. Default is false.
189
+
min_zoom = 10# minimum zoom level to include this layer
190
+
max_zoom = 18# maximum zoom level to include this layer
191
+
```
197
192
198
-
[[maps.layers]]
199
-
name = "rivers"# name is optional. If it's not defined the name of the ProviderLayer will be used.
200
-
# It can also be used to group multiple ProviderLayers under the same namespace.
201
-
provider_layer = "test_postgis.rivers"# must match a data provider layer
202
-
dont_simplify = true# optionally, turn off simplification for this layer. Default is false.
203
-
dont_clip = true# optionally, turn off clipping for this layer. Default is false.
204
-
min_zoom = 10# minimum zoom level to include this layer
205
-
max_zoom = 18# maximum zoom level to include this layer
193
+
\* more on PostgreSQL SSL mode [here](https://www.postgresql.org/docs/9.2/static/libpq-ssl.html). The `postgis` config also supports "ssl_cert" and "ssl_key" options are required, corresponding semantically with "PGSSLKEY" and "PGSSLCERT". These options do not check for environment variables automatically. See the section [below](#environment-variables) on injecting environment variables into the config.
206
194
195
+
### Example config using Postres 12 / PostGIS 3.0 ST_AsMVT():
207
196
208
-
# note that this map is only using mvt_test_postgis provider.
209
-
# it can not conflate any other providers
210
-
[[maps]]
211
-
name = "landuse_mvt"
197
+
```toml
198
+
# register a MVT data provider. MVT data providers have the prefix "mvt_" in their type
199
+
# note mvt data providers can not be conflated with any other providers of any type in a map
200
+
# thus a map may only contain a single mvt provider.
201
+
[[providers]]
202
+
name = "my_postgis"# provider name is referenced from map layers (required).
203
+
type = "mvt_postgis"# the type of data provider must be "mvt_postgis" for this data provider (required)
provider_layer = "mvt_test_postgis.landuse"# note the mvt data provider name is prefixed with `mvt_`
216
-
min_zoom = 12# minimum zoom level to include this layer
217
-
max_zoom = 16# maximum zoom level to include this layer
210
+
[[providers.layers]]
211
+
name = "landuse"
212
+
# MVT data provider must use SQL statements
213
+
# this table uses "geom" for the geometry_fieldname and "gid" for the id_fieldname so they don't need to be configured
214
+
# Wrapping the geom with ST_AsMVTGeom is required.
215
+
sql = "SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX!"
218
216
217
+
# maps are made up of layers
218
+
[[maps]]
219
+
name = "zoning"# used in the URL to reference this map (/maps/zoning)
219
220
221
+
[[maps.layers]]
222
+
name = "landuse"# name is optional. If it's not defined the name of the ProviderLayer will be used.
223
+
provider_layer = "my_postgis.landuse"# must match a data provider layer
224
+
min_zoom = 10# minimum zoom level to include this layer
225
+
max_zoom = 16# maximum zoom level to include this layer
220
226
```
221
227
222
-
\* more on PostgreSQL SSL mode [here](https://www.postgresql.org/docs/9.2/static/libpq-ssl.html). The `postgis` config also supports "ssl_cert" and "ssl_key" options are required, corresponding semantically with "PGSSLKEY" and "PGSSLCERT". These options do not check for environment variables automatically. See the section [below](#environment-variables) on injecting environment variables into the config.
223
-
224
228
## Environment Variables
225
229
226
230
#### Config TOML
@@ -241,7 +245,8 @@ srid = 3857
241
245
max_connections = "${POSTGIS_MAX_CONN}"
242
246
```
243
247
244
-
#### SQL Debugging
248
+
## SQL Debugging
249
+
245
250
The following environment variables can be used for debugging:
246
251
247
252
`TEGOLA_SQL_DEBUG` specify the type of SQL debug information to output. Currently support two values:
@@ -262,7 +267,6 @@ The following environment variables can be used to control various runtime optio
262
267
-`DontSimplifyGeo` to turn off simplification for all layers.
263
268
-`SimplifyMaxZoom={{int}}` to set the max zoom that simplification will apply to. (14 is default)
264
269
265
-
266
270
## Client side debugging
267
271
268
272
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:
@@ -279,12 +283,10 @@ The requested tile will be encode a layer with the `name` value set to `debug` a
279
283
280
284
## Building from source
281
285
282
-
Tegola is written in [Go](https://golang.org/) and requires Go 1.x to compile from source. (We support the three newest versions of Go.) 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:
283
-
286
+
Tegola is written in [Go](https://golang.org/) and requires Go 1.14 to compile from source. (We support the two newest versions of Go.) To build tegola from source, make sure you have Go installed and have cloned the repository. Navigate to the repository then run the following command:
284
287
285
288
```bash
286
-
cd cmd/tegola/
287
-
go build
289
+
cd cmd/tegola/ && go build -mod vendor
288
290
```
289
291
290
292
You will now have a binary named `tegola` in the current directory which is [ready for running](#running-tegola).
@@ -307,7 +309,9 @@ go build -tags 'noRedisCache noGpkgProvider noViewer'
307
309
```
308
310
309
311
## License
312
+
310
313
See [license](LICENSE.md) file in repo.
311
314
312
315
## Looking for a vector tile style editor?
316
+
313
317
Once you have tegola running you're likely going to want to work on your map's cartography. Give [fresco](https://github.com/go-spatial/fresco) a try!
-`name` (string): [Required] provider name is referenced from map layers. please note that when referencing an mvt_provider form a map layer the provider name must be prexied with `mvt_`. See example config below.
21
+
-`name` (string): [Required] provider name is referenced from map layers.
22
22
-`type` (string): [Required] the type of data provider. must be "postgis" to use this data provider
-`port` (int): [Required] PostGIS database port (required)
@@ -35,7 +35,9 @@ In addition to the connection configuration above, Provider Layers need to be co
35
35
```toml
36
36
[[providers.layers]]
37
37
name = "landuse"
38
+
# MVT data provider must use SQL statements
38
39
# this table uses "geom" for the geometry_fieldname and "gid" for the id_fieldname so they don't need to be configured
40
+
# Wrapping the geom with ST_AsMVTGeom is required.
39
41
sql = "SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX!"
40
42
```
41
43
@@ -59,11 +61,7 @@ sql = "SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom
59
61
-`!GEOM_FIELD!` - [Optional] the geom field name
60
62
-`!GEOM_TYPE!` - [Optional] the geom type if defined otherwise ""
61
63
62
-
## Example mvt_provider and map config
63
-
64
-
**Important**: When referencing the `provider` in the `map` section of the config, you MUST prepend `mvt_` to the `provider_layer` value. This indicates to tegola that the provider is an MVT provider so tegola knows which provider section to perform the lookup.
65
-
66
-
Example:
64
+
## Example mvt_postgis and map config
67
65
68
66
```toml
69
67
[[providers]]
@@ -83,26 +81,11 @@ password = ""
83
81
name = "cities"
84
82
center = [-90.2,38.6,3.0] # where to center of the map (lon, lat, zoom)
85
83
86
-
[[maps.layers]]
87
-
name = "landuse"
88
-
provider_layer = "test_postgis.landuse"
89
-
min_zoom = 0
90
-
max_zoom = 14
91
-
```
92
-
93
-
## Environment Variable support
94
-
95
-
Helpful debugging environment variables:
96
-
97
-
-`TEGOLA_SQL_DEBUG`: specify the type of SQL debug information to output. Supports the following values:
98
-
-`LAYER_SQL`: print layer SQL as they’re parsed from the config file.
99
-
-`EXECUTE_SQL`: print SQL that is executed for each tile request and the number of items it returns or an error.
100
-
-`LAYER_SQL:EXECUTE_SQL`: print `LAYER_SQL` and `EXECUTE_SQL`.
0 commit comments