Upgrading

TileJSON only uses the X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Prefix headers when the request comes from a proxy listed in server.forwarded.trusted. Private, loopback, and link-local addresses are trusted by default. If your proxy has a public address, add it to trusted or set baseurls in the TileJSON configuration, otherwise the tiles URLs are built from the request tilegroxy received

The client IP in logs and analytics now comes from the X-Forwarded-For header when the request is from a trusted proxy. It used to always be the address of the connection, so a proxy on a private network would be recorded instead of the client

Forwarded configures which proxies are trusted and which headers they report the original request in, for example CF-Connecting-IP

Rate limiting available. Off by default

The TileJSON document endpoint works for any name a pattern layer matches, not only the names listed in its examples

SIGHUP now reloads the configuration instead of shutting down. Anything that relied on SIGHUP to stop the process should send SIGTERM or SIGINT instead. See Reloading

Library use only: pkg/ has been minimized to entity interfaces, Deps structs, registrations, and the types they reference. See Using tilegroxy as a library for the supported approach

The pmtiles provider serves tiles directly from a PMTiles archive

MapLibre Tiles (MLT) are supported alongside MVT, with new compositemlt and cropmlt providers

Bearer authentication validates API tokens stored in a PostgreSQL or Redis datastore

Passthrough authentication forwards incoming credentials to an existing HTTP endpoint

Layers can pull TileJSON metadata from their provider, for example from a PMTiles archive

The disk cache filemode accepts chmod-style values such as "0644"

Deprecated configuration now logs a warning. The currently deprecated options are listed in Compatibility

Health moved from server.health to a top-level health section. The SERVER_HEALTH_* environment variables are now HEALTH_* and the Helm chart values moved to match

Custom authentication scripts now implement func validate(string) tilegroxy.ValidationResult, a struct carrying Pass, Expiration, UserID, TenantID and AllowedLayers, instead of returning four values. See Custom Authentication

The error section is no longer partially reloadable. Changes to it now require a restart

The ttl of the AWS Secrets Manager secret source changed meaning. It used to control a cache that had little effect. It now triggers a reload of all secrets when it expires

Library use only: the Cache interface gained a Remove method and ClientConfig.UnknownLength is now a *bool

Authentication can attribute a request to a tenant as well as a user. The new tenant cache namespaces entries so one tenant is never served another’s tile. See Multi-tenant

The top-level cache can be a list of configurations identified by id, and each layer can pick one. See Overridable caches

Cache-Control and CORS have dedicated sections. If you set these through server.headers, consider moving to the new sections. Both are off by default

An audit log records authentication failures and configuration reloads. Off by default

Secrets gained watch and ttl options so rotated credentials take effect without a restart

The disk cache supports a layout so entries aren’t all written to one directory

New CLI options: config diff, seed --purge, seed --max-failures, and --user and --tenant on seed and test

server production now defaults to true. If your configuration doesn’t set it, the splash page, documentation, and layer preview are no longer served. Set production: false explicitly to keep the old behavior

Library use only: Initialize on provider, authentication, and analytics registrations now takes a single dependency struct. Custom scripts are unaffected

Layers can serve TileJSON documents describing their tiles

Layers can declare a data type, zoom limits, and bounds, enforced before the request reaches a provider. They also gained a cache invalidation version

The cropmvt provider crops vector tiles to bounds

JWT authentication can fetch signing keys from a JWKS endpoint

A layer preview page is available when production is false

Duplicate concurrent requests for the same tile are coalesced into a single upstream fetch

The ttl cache bounds how long entries live in caches without native expiration

Timeout responses can be customized and most errors have a vector tile variant. See Error

seed can resume an interrupted run and target a specific cache. test gained JSON and file output

A Helm chart is available

Shutdown and reload now drain in-flight requests instead of dropping them

memcache was renamed memcached and the postgres analytics was renamed postgresql. The old names still work but are deprecated

Configuration validation is stricter. Unknown keys, an invalid error.mode, invalid logging levels and formats, duplicate layer IDs, and datastore ID collisions are now errors. Run config check before upgrading

Special characters in layer names are replaced with an underscore when used in disk and S3 cache keys and telemetry metric names. Layer names that differ only by special characters may now collide. Existing cache entries for such layers will no longer be found. See Layer names

Analytics records an event for each tile served, to PostgreSQL, ClickHouse, or a custom destination. Off by default

ETag and If-None-Match support, so repeat requests for unchanged tiles return 304. No configuration needed

Vector tile content types are allowed by default, so proxied MVT works without changing the client contenttypes

Releases are signed with a new key. If you verify release signatures, import the new public key from the release notes

The crop provider limits a layer to a geographic area

Hot reloading of configuration supplied by file, enabled with --hot-reload

The compositemvt provider combines multiple MVT layers into a single tile

The postgismvt provider generates MVT tiles from a PostGIS table

A health endpoint on a secondary port for load balancer and orchestrator probes

Custom provider scripts now return an image struct instead of a byte array, so they can specify a content type. See Custom Providers

Documentation is published as a website and served by tilegroxy itself

Improved content type handling

OpenTelemetry support for traces, metrics, and logs

Cache writes are asynchronous

The proxy provider supports {ctx.query-string} and EPSG:3857

Secrets can be read from an external store, starting with AWS Secrets Manager

The cgi provider serves tiles from CGI applications such as MapServer

tilegroxy can be used as a library

The per-layer overrideclient parameter is renamed client. It now only overrides the values you set and inherits everything else from the top-level client, where it previously replaced the whole client configuration

HTTPS, including Let’s Encrypt. See Encryption

JWT authentication can restrict access to an area using a geohash claim

Layers can match a pattern instead of a fixed ID, and the ref provider points one layer at another

Configuration can come from etcd or Consul and be overridden with environment variables. See Configuration

Prebuilt binaries for several operating systems and architectures, with checksums and signatures