Disks

Stores the cache entries as files in a location on the filesystem.

If the filesystem is purely local then you will experience inconsistent performance if using tilegroxy in a high-availability deployment.

Files are stored in a flat structure inside the specified directory. No cleanup process is included inside of tilegroxy itself. It is recommended you use an external cleanup process to avoid running out of disk space.

Name should be "disk"

Configuration options:

Parameter Description Type Required Default

path

The absolute path to the directory to store cache entries within. Directory (and tree) will be created if it does not already exist

string

Yes

None

filemode

A Go filemode as an integer to use for all created files/directories. This might change in the future to support a more conventional unix permission notation

uint32

No

0777

Example:

"cache": {
  "name": "disk",
  "path": "./disk_tile_cache"
}

Cache key sanitization

Cache filenames are derived from the layer name and tile coordinates, e.g. mylayer_1_2_3. Since the layer name comes from the incoming request path for pattern layers, it’s sanitized before being used in a filename: every character other than ASCII letters, digits, -, and . is replaced with , and any run of two or more consecutive dots (or a lone .) is also replaced with . This prevents a crafted layer name (e.g. one containing ../) from writing or reading cache entries outside the configured path. Ordinary layer names like osm or my-layer pass through unchanged.

This is a many-to-one mapping, so two distinct layer names that differ only in unsafe characters will sanitize to the same filename and share a cache entry - for example both a/b and a b sanitize to a_b. This is an accepted tradeoff to keep cache filenames human-readable; if you rely on layer names that differ only by characters outside A-Za-z0-9-., be aware they may collide in the cache.