tilegroxy — Tile G(o) (P)roxy

Tilegroxy lives between your map and your mapping providers to deliver a consistent, cached API for all your layers.

🚀 Built in Go.
🔌 Features a flexible plugin system powered by Yaegi.
💡 Inspired by tilestache
🛠️ This project is still a work in progress. Changes may occur prior to the 1.0 release.

Why tilegroxy?

Tilegroxy shines when you consume maps from multiple sources. It isn’t tied to any one mapping backend and can pull data from any protocol, whether the standard alphabet soup or a proprietary, authenticated API. Rather than make your frontend aware of every single vendor and exposing your keys, utilize tilegroxy and provide a uniform API with a configuration-driven backend that can be augmented by code when necessary.

Features

• Proxy to ZXY, WMS, TMS, WMTS, or other protocol map layers
• Cache tiles in disk, memory, s3, redis, and/or memcached
• Require authentication using static key, JWT, or custom logic
• Restrict access to a given layer and/or geographic region based on auth token
• Create your own custom provider to pull in non-standard and proprietary imagery sources
• Tweak your map layer with 18 standard effects or by providing your own pixel-level logic
• Combine multiple map layers with adjustable rules and blending methods
• Act as an HTTP server for MapServer and any other CGI application that generates tiles
• Commands for seeding and testing your layers
• Support for both raster and vector format tiles
• Run as HTTPS including Let’s Encrypt support
• Configurable timeout, logging, and error handling rules
• Override configuration via environment variables
• Externalize passwords/keys using AWS Secrets Manager
• Container deployment
• Traces, metrics, and logs available via OpenTelemetry
• Usable as an application or a library

Documentation

Prebuilt Documentation for the most recent release is available here.

Documentation is served by tilegroxy at /docs (disable this behaviour by setting Server.Production=true). Documentation is powered by Antora with raw AsciiDoc located in docs

How to get it

Tilegroxy is available as a standalone executable or a container image. It’s recommended you utilize a container for any serious deployment while the standalone executable can be useful to run locally while building your configuration.

Building

Tilegroxy builds as an executable binary with minimal dynamic dependencies. Prebuilt binaries are available from Github.

Building tilegroxy yourself requires a bash-like shell with go 1.22, node 20, git, make, and standard POSIX utilities like date. It uses a conventional Makefile workflow:

Build with

make

then install with

sudo make install

Once installed, tilegroxy can be invoked via the available commands such as tilegroxy serve. A systemd unit file for operation as a server daemon is left as an exercise for the reader.

Tests

The build includes integration tests that use testcontainers. This requires you have either docker or podman installed and running. If you encounter difficulties running these tests it’s recommended you use a prebuilt binary. That said, you can also build with just unit tests using:

make clean build unit

See developer documentation for more details.

Docker

Tilegroxy is available as a container image on the Github container repository.

You can pull the most recent versioned release with the latest tag and the very latest (and maybe buggy) build with the edge tag. Tags are also available for version numbers. See here for a full list.

For example:

docker pull ghcr.io/michad/tilegroxy:latest

To then run tilegroxy:

docker run --rm -v ./test_config.yml:/tilegroxy/tilegroxy.yml:Z ghcr.io/michad/tilegroxy seed -l osm -z 0 -v

You can of course build the docker image yourself:

docker build . -t tilegroxy

An example docker-compose.yml is included that can be used to start the tilegroxy server. It assumes using a configuration file named "test_config.yml" is located in the current working directory.

Extending tilegroxy

One of the top design goals of tilegroxy is to be highly flexible. If there’s functionality you need, there’s a couple different ways you can add it in. See the extensibility documentation for instructions.

Contributing

As this is a young project any contribution via an Issue or Pull Request is very welcome.

A few please and thank yous:

• Follow go conventions and the patterns you see elsewhere in the codebase. Linters are configured in Github Actions, they can be run locally with make lint

• Use semantic / conventional commit messages.

• Open an issue for discussion before making large, fundamental change/refactors

• Ensure you add tests. You can use make coverage to ensure you’re not dropping coverage.

Very niche providers might be declined. Those are best suited as custom providers outside the core platform.