How to get it :: tilegroxy Docs

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.

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.