LOD: Levels of Detail
An intelligent map tile proxy cache for the edge.
LOD (Levels of Detail) is a thin map tile proxy with in-memory caching and a slim authentication backend. It will sit in front of any tile server and will aggressively cache tiles in memory, optionally storing them in a configured Redis cluster for faster fetching later. LOD is cluster-aware and uses Redis message queueing for intra-cluster communication when multiple instances are deployed together.
LOD is written in Go 1.17 using fiber. TOML is used for configuration. Go templates are used for templating. Internal in-memory caching is built upon the bigcache library by allegro.
Download a build from the releases page or just run:
$ go install github.com/tile-fund/lod@latestFlags:
--conf Path to TOML configuration file. Default: config.toml
--dev Whether to enable developer mode. Default: false
--debug Optional comma separated debug flags. Ex: foo,bar,baz
--help Shows this help menu.
Usage:
lod [--conf config.toml] [--dev]Or just use our Docker image!
You can create your own Dockerfile that adds a config.toml from the
8000
context into the config directory, like so:
FROM tilefund/lod:0.4.6
COPY /path/to/your_config.toml /opt/lod_cfg/config.toml
CMD [ "/opt/lod", "--conf", "/opt/lod_cfg/config.toml" ]Alternatively, you can specify something along the same lines with Docker run options:
$ docker run -v /path/to/lod-config:/opt/lod_config -p 1337:1337 lod --conf /opt/lod_config/config.toml- Lightweight, parallel, and non-blocking
- Tileserver agnostic (Tegola, flat file NGINX, etc.)
- Tile format and content agnostic
- Vector (Mapbox Vector Tiles or other vector formats)
- Raster (PNG/JPG/TIFF)
- And more...
- Supports XYZ (Slippy) and TMS tile indexing schemes
- Multi-level caching
- In-memory, tunable LRU cache as first level
- Redis cluster with configurable TTL as second level
- Configurable header proxying and deletion
-
Content-TypeandContent-Encodingadded by default
-
- Internal stats tracking
- Hits, misses, hit-rate
- Tiles per second (load averages)
- Tile upstream fetch times (avg, 75th, 99th)
- Expose Prometheus endpoint
- Supports multiple configured tileserver proxies
- Separate authentication (bearer tokens and CORS)
- Separate internal cache instances per proxy
- Allow configurable query parameters for tile URLs
- Add to cache key for separate caching (osm/4/5/6/osm_id=19)
- Separate stats tracking
- Administrative endpoints
- Reload the instance configuration
- Flush the instance caches
- Invalidate a given tile and re-prime it
- Iteratively invalidate all tiles under a given tile (all zoom levels)
- Iteratively prime all tiles under a given tile
- Cluster-wide operations
- Flush the instance caches across all instances
- Invalidate a given tile and re-prime it across the cluster
[instance]
port = 1337 # port to bind to
[[proxies]]
# name of this proxy, available at http://lod/{name}/{z}/{x}/{y}.pbf
name = "osm"
# url of the upstream tileserver
tile_url = "https://tile.example.com/osm/{z}/{x}/{y}.pbf"
# comma-separated list of allowed CORS origins
cors_origins = "https://example.com"
# auth bearer token to require for requests to upstream tileserver
access_token = "MyTilesArePrivate"
# headers to pull and cache from the tileserver response
add_headers = [ "X-We-Want-This", "X-This-One-Too" ]
# headers to delete from the tileserver response
del_headers = [ "X-Get-Rid-Of-Me" ]
[proxies.cache]
mem_cap = 100 # maximum capacity in MB of the in-memory cache
# Cache TTLs are set using Go's built-in time.ParseDuration
# Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
# For example: 1h, 5m, 300s, 1000ms, 2h35m, etc.
mem_ttl = "1h" # in-memory cache TTL
redis_ttl = "24h" # redis tile cache TTL, or "0" for no expiry
redis_url = "redis://localhost:6379/0" # redis connection URL
key_template = "{z}/{x}/{y}" # cache key template string, supports parameter names
# Supports many configured proxy instances for caching multiple tileservers
[[proxies]]
name = "another"
# etc.LOD is licensed under the GNU Affero General Public License 3 or any later version at your choice. See COPYING for details.