tilegroxy

= tilegroxy -- Tile G(o) (P)roxy

image:https://github.com/Michad/tilegroxy/actions/workflows/docker-image.yml/badge.svg[Docker Image CI,link=https://github.com/Michad/tilegroxy/actions/workflows/docker-image.yml] image:https://img.shields.io/ossf-scorecard/github.com/Michad/tilegroxy?label=openssf%20scorecard&style=flat[OpenSSF Scorecard,link=https://scorecard.dev/viewer/?uri=github.com%2FMichad%2Ftilegroxy] image:https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/michad/d1b9e082f6608635494188d0f52bae69/raw/coverage.json[Coverage] image:https://img.shields.io/endpoint?url=https://gist.githubusercontent.com/michad/d1b9e082f6608635494188d0f52bae69/raw/libyears.json[Libyears,link=https://libyear.com/]  +
image:https://img.shields.io/github/go-mod/go-version/michad/tilegroxy[Go Version] image:https://img.shields.io/badge/License-Apache_2.0-blue.svg[License,link=https://opensource.org/licenses/Apache-2.0] xref:CODE_OF_CONDUCT.adoc[image:https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg[Contributor Covenant]]

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 https://github.com/traefik/yaegi[Yaegi]. +
💡 Inspired by https://github.com/tilestache/tilestache[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

+++<ul><li>+++
link:https://tilegroxy.com/operation/configuration/provider/proxy.html[Proxy] to ZXY, WMS, TMS, WMTS, or other protocol map layers
+++</li><li>+++
Cache tiles in link:https://tilegroxy.com/operation/configuration/cache/disk.html[disk], link:https://tilegroxy.com/operation/configuration/cache/memory.html[memory], link:https://tilegroxy.com/operation/configuration/cache/s3.html[s3], link:https://tilegroxy.com/operation/configuration/cache/redis.html[redis], and/or link:https://tilegroxy.com/operation/configuration/cache/memcached.html[memcached]
+++</li><li>+++
Require authentication using link:https://tilegroxy.com/operation/configuration/authentication/static_key.html[static key], link:https://tilegroxy.com/operation/configuration/authentication/jwt.html[JWT], link:https://tilegroxy.com/operation/configuration/authentication/passthrough.html[an existing HTTP endpoint], link:https://tilegroxy.com/operation/configuration/authentication/bearer.html[API keys stored in a database], or link:https://tilegroxy.com/operation/configuration/authentication/custom.html[custom] logic
+++</li><li>+++
link:https://tilegroxy.com/operation/configuration/authentication/jwt.html[Restrict access] to a given layer and/or geographic region based on auth token
+++</li><li>+++
Create your own link:https://tilegroxy.com/operation/extensibility.html[custom provider] to pull in non-standard and proprietary imagery sources
+++</li><li>+++
Support for raster tiles and both the Mapbox Vector Tile (MVT) and MapLibre Tile (MLT) vector formats
+++</li><li>+++
Tweak your raster layers with link:https://tilegroxy.com/operation/configuration/provider/effect.html[18 standard effects] or by providing your own link:https://tilegroxy.com/operation/configuration/provider/transform.html[pixel-level logic]
+++</li><li>+++
Combine link:https://tilegroxy.com/operation/configuration/provider/blend.html[raster] or link:https://tilegroxy.com/operation/configuration/provider/compositemvt.html[vector tile] layers
+++</li><li>+++
link:https://tilegroxy.com/operation/configuration/provider/cgi.html[Act as an HTTP server] for https://www.mapserver.org[MapServer] and any other CGI application that generates tiles
+++</li><li>+++
Commands for link:https://tilegroxy.com/operation/commands/seed.html[seeding] and link:https://tilegroxy.com/operation/commands/test.html[testing] your layers
+++</li><li>+++
Run as link:https://tilegroxy.com/operation/configuration/encryption.html[HTTPS] including Let's Encrypt (ACME) support
+++</li><li>+++
Configurable via file or etcd with link:https://tilegroxy.com/operation/configuration/index.html[environment variable] override,
link:https://tilegroxy.com/operation/configuration/secret/index.html[externalizable secrets], and link:https://tilegroxy.com/operation/reloading.html[zero-downtime reload]
+++</li><li>+++
link:https://tilegroxy.com/operation/get-it.html#docker[Container deployment]
+++</li><li>+++
Minimal HTTP footprint to decrease security exposure
+++</li><li>+++
Traces, metrics, and logs available via link:https://tilegroxy.com/operation/configuration/telemetry.html[OpenTelemetry]
+++</li><li>+++
Per-layer usage link:https://tilegroxy.com/operation/configuration/analytics/index.html[analytics] recorded to ClickHouse, PostgreSQL, or a custom destination
+++</li><li>+++
Usable as an application or a link:https://tilegroxy.com/operation/extensibility.html[library]
+++</li><li>+++
Supports link:https://tilegroxy.com/operation/tilejson.html[TileJSON]
+++</li></ul>+++

== Documentation

**Prebuilt Documentation for the most recent release is available link:https://tilegroxy.com[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 link:https://antora.org[Antora] with raw AsciiDoc located in link:./docs[docs]

A link:https://tilegroxy.com/operation/configuration/index.html#lazy-button[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.


:leveloffset: 1

= 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 https://github.com/Michad/tilegroxy/releases[Github].

Building tilegroxy yourself requires a bash-like shell with go, node, git, make, and standard POSIX utilities like date.  It uses a conventional link:https://github.com/Michad/tilegroxy/blob/main/Makefile[Makefile] workflow.

.Build and install
[,shell]
----
make
sudo make install
----

Once installed, tilegroxy can be invoked via the available link:https://tilegroxy.com/operation/commands/index.html[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 https://golang.testcontainers.org/[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:

[,shell]
----
make clean build unit
----

See link:https://tilegroxy.com/development/tests.html[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.  https://github.com/Michad/tilegroxy/pkgs/container/tilegroxy[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 xref:compatibility.adoc[Compatibility].

.Pull the latest release
[,shell]
----
docker pull ghcr.io/michad/tilegroxy:latest
----

.Run a command in the container
[,shell]
----
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
[,shell]
----
docker build . -t tilegroxy
----

An example link:https://github.com/Michad/tilegroxy/blob/main/docker-compose.yml[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 link:https://github.com/Michad/tilegroxy/tree/main/charts/tilegroxy[Helm chart] is included in the repository:

[,shell]
----
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 xref:configuration/index.adoc[configuration reference] can be used as-is:

[,yaml]
----
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 xref:configuration/health.adoc[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 link:https://github.com/Michad/tilegroxy/blob/main/charts/tilegroxy/README.md[chart README] for the full list of values.

:leveloffset!:


== 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 link:https://tilegroxy.com/operation/extensibility.html[extensibility documentation] for instructions.

== Contributing

Any contribution via an Issue or Pull Request is very welcome.

A few please and thank yous:

* Follow https://go.dev/doc/effective_go[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 https://gist.github.com/joshbuchea/6f47e86d2510bce28f8e7f42ae84c716[semantic] / https://www.conventionalcommits.org/en/v1.0.0/[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.