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

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, an existing HTTP endpoint, API keys stored in a database, or custom logic
• Restrict access to a given layer and/or geographic region based on auth token
• Rate limit users, tenants, or IP addresses, from per-second bursts to monthly quotas
• Create your own custom provider to pull in non-standard and proprietary imagery sources
• Support for raster tiles and both the Mapbox Vector Tile (MVT) and MapLibre Tile (MLT) vector formats
• Tweak your raster layers with 18 standard effects or by providing your own pixel-level logic
• Combine raster or vector tile layers
• Act as an HTTP server for MapServer and any other CGI application that generates tiles
• Commands for seeding and testing your layers
• Run as HTTPS including Let’s Encrypt (ACME) support
• Configurable via file or etcd with environment variable override, externalizable secrets, and zero-downtime reload
• Container deployment
• Minimal HTTP footprint to decrease security exposure
• Traces, metrics, and logs available via OpenTelemetry
• Per-layer usage analytics recorded to ClickHouse, PostgreSQL, or a custom destination
• Usable as an application or a library
• Supports TileJSON

Documentation

Prebuilt Documentation for the most recent release is available here.

Documentation is served by tilegroxy at /docs when running in dev (enable this behaviour by setting Server.Production=false in config or SERVER_PRODUCTION=false as an environment variable). Documentation is powered by Antora with raw AsciiDoc located in docs

A Skill is available to help you get started with generating your configuration. However, do make sure you understand what it produces before you run it.

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, node, git, make, and standard POSIX utilities like date. It uses a conventional Makefile workflow.

Build and install

make
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. Tags for just the major version, such as 1, pick up new releases without crossing a breaking change as described in Compatibility.

Pull the latest release

docker pull ghcr.io/michad/tilegroxy:latest

Run a command in the container

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:

Build the image

docker build . -t tilegroxy

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

Kubernetes

A Helm chart is included in the repository:

helm install tilegroxy ./charts/tilegroxy -f my-values.yaml

The chart takes the entire tilegroxy configuration under a single config key and renders it into a ConfigMap, so anything in the configuration reference can be used as-is:

config:
  server:
    port: 8080
    production: true
  health:
    enabled: true
    checks:
      - name: cache
  cache:
    name: redis
    host: redis.example.svc.cluster.local
  layers:
    - id: osm
      provider:
        name: proxy
        url: https://tile.openstreetmap.org/{z}/{x}/{y}.png

The values outside of config cover the usual deployment concerns such as replicas, resources, ingress, autoscaling, storage, and scheduling.

Warning

Avoid placing credentials in config since it becomes a ConfigMap. Instead reference them as env.VAR_NAME in the configuration and supply the value using the chart’s secrets or existingSecretKeys values.

Probes are wired to the health endpoints when config.health.enabled is true, an init container validates the configuration before the server starts, and tilegroxy seed can be run as a Job after install and upgrade. See the chart README for the full list of values.

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

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.