Tegola

https://tegola.io/documentation/
Admin
Tegola is an open source vector tile server that lets you run your own geospatial data serving...
Tokens:6,975
Snippets:109
Trust Score:7.3
Update:4 months ago
Show doc for...
Tokens:
Raw
### Clone the example repository

Source: https://tegola.io/documentation/getting-started

Clone the Tegola example repository to get started.

```bash
git clone https://github.com/go-spatial/tegola-example-bonn.git
cd tegola-example-bonn
```

--------------------------------

### Start Tegola and Postgres/PostGIS

Source: https://tegola.io/documentation/getting-started

Start Tegola and Postgres/PostGIS in a containerized environment using Docker Compose.

```bash
docker compose up
```

--------------------------------

### Your first vector map client

Source: https://tegola.io/documentation/getting-started

HTML file for a basic client application using OpenLayers to display Tegola vector tiles.

```html
<!DOCTYPE html>
<html>
  <head>
    <title>Tegola Sample</title>
    <link
      rel="stylesheet"
      href="https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.3.0/css/ol.css"
      type="text/css"
    />
    <script src="https://cdn.rawgit.com/openlayers/openlayers.github.io/master/en/v5.3.0/build/ol.js"></script>
    <style>
      #map {
        width: 100%;
        height: 100%;
        position: absolute;
        background: #f8f4f0;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map = new ol.Map({
        layers: [
          new ol.layer.VectorTile({
            source: new ol.source.VectorTile({
              attributions:
                '© <a href="http://www.openstreetmap.org/copyright">
' +
                "OpenStreetMap contributors"
              },
              format: new ol.format.MVT(),
              tileGrid: ol.tilegrid.createXYZ({ maxZoom: 22 }),
              tilePixelRatio: 16,
              url: "/maps/bonn/{z}/{x}/{y}.vector.pbf?debug=true",
            }),
          }),
        ],
        target: "map",
        view: new ol.View({
          //coordinates the map will center on initially
          center: [790793.4954921771, 6574927.869849075],
          zoom: 14,
        }),
      });
    </script>
  </body>
</html>

```

--------------------------------

### Example Webserver config

Source: https://tegola.io/documentation/configuration

This is an example of a webserver configuration in TOML syntax.

```toml
[webserver]
port = ":8080"
hostname = "tiles.example.com"

  [webserver.headers]
  # redefine default cors origin
  Access-Control-Allow-Origin = "http://map.example.com"

  # define CDN max age
  Cache-Control = "s-maxage=300"

```

--------------------------------

### Full Configuration Example

Source: https://tegola.io/documentation/configuration

A comprehensive example demonstrating various Tegola configuration options.

```toml
tile_buffer = 64

[webserver]
port = ":9090"

[cache]
type="file"		# cache type
basepath="/tmp/tegola"	# cache specific config

```

--------------------------------

### PostGIS connection string example

Source: https://tegola.io/documentation/configuration

This is an example of a PostGIS connection string.

```sql
postgres://tegola:supersecret@localhost:5432/tegola?sslmode=prefer&pool_max_conns=10
```

--------------------------------

### Simple Seed Example

Source: https://tegola.io/documentation/cache-seeding-and-purging

This example demonstrates how to seed tiles within a specified geographic bounding box.

```bash
$ ./tegola cache seed --bounds "-117.25,32.5,-117.0,32.75"
```

--------------------------------

### Map Configuration Example

Source: https://tegola.io/documentation/configuration

Example of how to configure a map with name, attribution, and center.

```toml
[[maps]]
name = "zoning"		# used in the URL to reference this map (/maps/:map_name)
attribution = "Natural Earth v4"
center = [-76.275329586789, 39.153492567373, 5.0]

```

--------------------------------

### Simple Purge Example

Source: https://tegola.io/documentation/cache-seeding-and-purging

This example demonstrates how to purge tiles within a specified geographic bounding box.

```bash
$ ./tegola cache purge --bounds "-117.25,32.5,-117.0,32.75"
```

--------------------------------

### Simple Seed Tile Name Example

Source: https://tegola.io/documentation/cache-seeding-and-purging

This example shows how to seed a specific tile using its coordinates.

```bash
$ ./tegola cache seed tile-name 0/0/0
```

--------------------------------

### Example PostGIS Provider config

Source: https://tegola.io/documentation/configuration

This is an example of a PostGIS provider configuration.

```toml
[[providers]]
name = "test_postgis"       # provider name is referenced from map layers (required)
type = "postgis"            # the type of data provider must be "postgis" for this data provider (required)

uri = "postgres://tegola:supersecret@localhost:5432/tegola?sslmode=prefer" # PostGIS connection string (required)
srid = 3857             # The default srid for this provider. If not provided it will be WebMercator (3857)

```

--------------------------------

### Example GeoPackage Provider config

Source: https://tegola.io/documentation/configuration

This is an example of a GeoPackage provider configuration.

```toml
[[providers]]
name = "sample_gpkg"
type = "gpkg"
filepath = "/path/to/my/sample_gpkg.gpkg"

```

--------------------------------

### Map Layer Configuration Example

Source: https://tegola.io/documentation/configuration

Example of configuring a map layer with provider, zoom levels, and tags.

```toml
[[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

```

--------------------------------

### Example mvt_postgis and map config

Source: https://tegola.io/documentation/configuration

This example shows a configuration for the mvt_postgis provider, emphasizing the use of ST_AsMVTGeom and the !BBOX! token in the SQL query.

```toml
[[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!"

```

--------------------------------

### Example minimum Provider Layer config with `sql` defined

Source: https://tegola.io/documentation/configuration

This example demonstrates a PostGIS provider layer configuration using a custom SQL query, including the required !BBOX! token.

```toml
[[providers.layers]]
name = "landuse"
# note that the geometry field is wrapped in ST_AsBinary() and the use of the required !BBOX! token
sql = "SELECT gid, ST_AsBinary(geom) AS geom FROM gis.rivers WHERE geom && !BBOX!"

```

--------------------------------

### Example of enabling client-side debugging

Source: https://tegola.io/documentation/debugging

This example shows how to enable client-side debugging by adding the debug=true query string variable to the URL template.

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

```

--------------------------------

### Example GeoPackage Provider Layer with `sql`

Source: https://tegola.io/documentation/configuration

This example illustrates a GeoPackage provider layer configuration using a custom SQL query, including necessary joins and selected fields for spatial indexing.

```toml
[[providers.layers]]
name = "a_points"
sql = """
    SELECT
        fid, geom, amenity, religion, tourism, shop, si.minx, si.miny, si.maxx, si.maxy
    FROM
        land_polygons lp
    JOIN
        rtree_land_polygons_geom si ON lp.fid = si.id
    WHERE
        !BBOX!
"""

```

--------------------------------

### Map Layer Default Tags Example

Source: https://tegola.io/documentation/configuration

Example of setting default tags for a map layer.

```toml
[maps.layers.default_tags]
class = "park"		# a default tag to encode into the feature

```

--------------------------------

### Example minimum Provider Layer config with `tablename` defined

Source: https://tegola.io/documentation/configuration

This example shows a basic PostGIS provider layer configuration using a tablename.

```toml
[[providers.layers]]
name = "landuse"
# this table uses 'geom' for the geometry_fieldname and 'gid' for the id_fieldname (the defaults)
tablename = "gis.zoning_base_3857"

```

--------------------------------

### Set Log Levels

Source: https://tegola.io/documentation/logging

Log levels can be set on start up.

```bash
/opt/tegola serve --log-level INFO

```

--------------------------------

### Example of setting TEGOLA_SQL_DEBUG environment variable

Source: https://tegola.io/documentation/debugging

This example shows how to set the TEGOLA_SQL_DEBUG environment variable to LAYER_SQL to print layer SQL as they are parsed from the config file.

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

```

--------------------------------

### Environment Variable Usage in Configuration

Source: https://tegola.io/documentation/configuration

Example of using environment variables within Tegola configuration files.

```toml
tile_buffer = "${TEGOLA_TILE_BUFFER}"     # note that tile buffer expects an integer, tegola will handle the conversion

[cache]
type = "redis"
password = "${SECRET_REDIS_PASSWORD}"

```

--------------------------------

### Capabilities Endpoint Response

Source: https://tegola.io/documentation/http-endpoints

Example response from the /capabilities endpoint, detailing available maps and layers.

```json
{
  "version": "v0.6.1",
  "maps": [{
    "name": "bonn_osm",
    "uri": "/maps/bonn_osm",
    "layers": [{
        "name": "building",
        "uri": "/maps/bonn_osm/building",
        "minZoom": 14,
        "maxZoom": 20
      },{
        "name": "road",
        "uri": "/maps/bonn_osm/road",
        "minZoom": 10,
        "maxZoom": 20
      }]
  }]
}
```

--------------------------------

### S3 Cache Credentials via Environment Variables

Source: https://tegola.io/documentation/configuration

Example of setting AWS credentials and region using environment variables for S3 cache.

```bash
$ export AWS_REGION=us-west-2
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY

```

--------------------------------

### Map Configuration

Source: https://tegola.io/documentation/configuration

Example TOML configuration for defining maps, which are composed of layers referencing data providers.

```toml
[[maps]]
name = "zoning"                             # used in the URL to reference this map (/maps/:map_name)
tile_buffer = 0                             # number of pixels to extend a tile's clipping area

    [[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

```

--------------------------------

### PostGIS Data Provider Configuration

Source: https://tegola.io/documentation/configuration

Example TOML configuration for a PostGIS data provider, including connection details and layer definitions.

```toml
[[providers]]
name = "test_postgis"   # provider name is referenced from map layers
type = "postgis"        # the type of data provider. currently only supports postgis
uri = "postgres://tegola:supersecret@localhost:5432/tegola?sslmode=prefer" # PostGIS connection string (required)
srid = 3857             # The default srid for this provider. If not provided it will be WebMercator (3857)

    # Example data
    [[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 the geometry field if different than

    [[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
    # Custom sql to be used for this layer.
    # Note that the geometry field is wrapped in a ST_AsBinary()
    sql = "SELECT gid, ST_AsBinary(geom) AS geom FROM gis.rivers WHERE geom && !BBOX!"

```

--------------------------------

### Map Capabilities Endpoint Response (TileJSON 2.1)

Source: https://tegola.io/documentation/http-endpoints

Example response from the /capabilities/:map.json endpoint, providing map details in TileJSON 2.1 format.

```json
{
  "attribution": "Open Street Map",
  "bounds": [-180, -85.0511, 180, 85.0511],
  "center": [-76.275329586789, 39.153492567373, 8],
  "format": "pbf",
  "minzoom": 0,
  "maxzoom": 20,
  "name": "osm",
  "description": null,
  "scheme": "xyz",
  "tilejson": "2.1.0",
  "tiles": ["https://tegola-osm-demo.go-spatial.org/v1/maps/osm/{z}/{x}/{y}.pbf"],
  "grids": [],
  "data": [],
  "version": "1.0.0",
  "template": null,
  "legend": null,
  "vector_layers": [{
    "version": 2,
    "extent": 4096,
    "id": "populated_places",
    "name": "populated_places",
    "geometry_type": "point",
    "minzoom": 0,
    "maxzoom": 20,
    "tiles": ["https://tegola-osm-demo.go-spatial.org/v1/maps/osm/populated_places/{z}/{x}/{y}.pbf"]
  }, {
    "version": 2,
    "extent": 4096,
    "id": "country_lines",
    "name": "country_lines",
    "geometry_type": "line",
    "minzoom": 0,
    "maxzoom": 10,
    "tiles": ["https://tegola-osm-demo.go-spatial.org/v1/maps/osm/country_lines/{z}/{x}/{y}.pbf"]
  }]
}
```

--------------------------------

### Tile List Command Flags Help

Source: https://tegola.io/documentation/cache-seeding-and-purging

This command displays the available flags for the 'tile-list' command, used for specifying tiles from a file.

```bash
Flags:
      --format string   4 character string where the first character is a non-numeric delimiter followed by 'z', 'x' and 'y' defining the coordinate order (default "/zxy")
  -h, --help            help for tile-list
      --max-zoom uint   max zoom to seed cache to
      --min-zoom uint   min zoom to seed cache from


```

--------------------------------

### Global Flags Help

Source: https://tegola.io/documentation/cache-seeding-and-purging

This command displays the available subcommands and global flags for the cache command.

```bash
./tegola cache -h
```

--------------------------------

### Tile Name Command Flags Help

Source: https://tegola.io/documentation/cache-seeding-and-purging

This command displays the available flags for the 'tile-name' command, used for specifying individual tiles.

```bash
Flags:
      --format string   4 character string where the first character is a non-numeric delimiter followed by 'z', 'x' and 'y' defining the coordinate order (default "/zxy")
  -h, --help            help for tile-name
      --max-zoom uint   max zoom to seed cache to
      --min-zoom uint   min zoom to seed cache from


```

--------------------------------

### Seed Command Flags Help

Source: https://tegola.io/documentation/cache-seeding-and-purging

This command displays the available commands and flags specific to the 'seed' subcommand.

```bash
Available Commands:
  tile-list   operate on a list of tile names separated by new lines
  tile-name   operate on a single tile formatted according to --format

Flags:
      --bounds string     lng/lat bounds to seed the cache with in the format: lng, lat, lng, lat (default "-180,-85.0511,180,85.0511")
      --concurrency int   the amount of concurrency to use. defaults to the number of CPUs on the machine (default 8)
  -h, --help              help for seed
      --map string        map name as defined in the config
      --max-zoom uint     max zoom to seed cache to (default 22)
      --min-zoom uint     min zoom to seed cache from
      --overwrite         overwrite the cache if a tile already exists (default false)


```

--------------------------------

### Seed Cache from Tile List (z/x/y format)

Source: https://tegola.io/documentation/cache-seeding-and-purging

Seeds the cache with tiles listed in `expired_tiles.txt` using the `/zxy` format.

```bash
15/0/0
15/0/1
15/1/1

```

```bash
$ ./tegola cache seed tile-list expired_tiles.txt

```

--------------------------------

### Seed Cache with Single Tile Name and Custom Format

Source: https://tegola.io/documentation/cache-seeding-and-purging

Seeds the cache with a single tile specified as `0-0-18`, interpreting it using the `-xyz` format as (z:18, x:0, y:0).

```bash
$ ./tegola cache seed tile-name "0-0-18" --format="-xyz"

```

--------------------------------

### Seed Cache with Single Tile Name and Space Delimited Format

Source: https://tegola.io/documentation/cache-seeding-and-purging

Seeds the cache with a single tile specified as `18 0 0`, interpreting it using the ` zxy` format as (z:18, x:0, y:0).

```bash
$ ./tegola cache seed tile-name "18 0 0" --format=" zxy"

```

--------------------------------

### Seed Cache from Tile List (custom format)

Source: https://tegola.io/documentation/cache-seeding-and-purging

Seeds the cache with tiles listed in `expired_tiles.txt` using a custom `-xyz` format and overwrites existing tiles.

```bash
0-0-15
0-1-15
1-1-15

```

```bash
$ ./tegola cache seed --tile-name-format="-xyz" --tile-list="expired_tiles.txt" --overwrite

```

--------------------------------

### Seed Cache from Tile List with Minimum Zoom

Source: https://tegola.io/documentation/cache-seeding-and-purging

Seeds the cache with tiles from zoom level 14-22 that are above and below the specified tile in `expired_tiles.txt`.

```bash
15/0/0

```

```bash
$ ./tegola cache seed tile-list expired_tiles.txt --min-zoom=14

```
Tokens:
Raw