Overview

The cache command manually manipulates Shigola's cache

Two flags worth knowing about:

• --tile-matrix-set — one run covers one tiling scheme.
• --cache-tiers — which tiers of a layered cache a run may write.
• --overwrite also purges the tiers it does not write.

Note that --bounds landing exactly on a tile edge does not include the tile on the far side.

Examples

• Simple seed
• Simple purge
• tile_name
• Simple tile list
• Tile name format

Note: The tile-list methods of fetching tiles is inefficient and will regenerate lower zoom tiles repeatedly.

Global Flags

Global Flags are valid for all subcommands

Running ./shigola cache -h will give a lost of flags with descriptions:

Available Commands:
  seed        seed tiles to the cache
  purge       purge tiles from the cache

Flags:
  -h, --help   help for cache
Global Flags:
      --config string   path to config file (default "config.toml")

Seeding/Purging

These subcommands are used to manipulate Shigola's cache.

Flags

Available Commands:
  tile-list   operate on a list of tile names separated by new lines
  tile-name   operate on a single tile formatted according to --format

Flags:
      --bounds string           lng/lat bounds to seed the cache with in the format: minx, miny, maxx, maxy (default "-180,-85.0511,180,85.0511")
      --bounds-srid int         the srid --bounds are given in. only 4326 (lng/lat) is supported (default 4326)
      --cache-tiers string      for a layered cache, the comma-separated tier names this run may write
      --concurrency int         the amount of concurrency to use. defaults to the number of CPUs on the machine (default 8)
  -h, --help                    help for seed
      --layers string           purge only: comma-separated layers of --map to purge, with the map's whole-map tile
      --log-threshold int       during seeding, only log tiles that take this number of milliseconds or longer to render
      --map string              map name as defined in the config
      --max-zoom uint           max zoom to seed cache to (default 22)
      --min-zoom uint           min zoom to seed cache from
      --overwrite               overwrite the cache if a tile already exists (default false)
      --tile-matrix-set string  the tiling scheme to seed or purge, by tileMatrixSetId

• bounds -- The bounds flag is used to specify latitude and longitude bounds for seeding and purging. Using this command should be used along with the max-zoom and min-zoom flags.
• bounds-srid -- the SRID --bounds are given in. Only 4326 (lng/lat) is supported. This does not select the tiling scheme — use --tile-matrix-set for that.
• max-zoom -- max zoom to seed the cache, will default to 22.
• min-zoom -- min zoom to seed the cache, will default to 0.
• log-threshold -- during seeding, only log tiles slower than this many milliseconds. Defaults to logging all tiles.

Bounds landing exactly on a tile edge no longer include the tile on the far side. A run whose bounds were chosen to line up with tile boundaries will cover one fewer tile per edge than it did upstream.

Global Flags

--tile-matrix-set

Names the tiling scheme to seed or purge. One run covers one scheme — it enumerates a single tile pyramid, so a run cannot cover two at once. Seed each scheme you serve.

# defaults to the first scheme the map lists
$ ./shigola cache seed --map=parks --bounds="-117.25,32.5,-117.0,32.75"

# or name one explicitly
$ ./shigola cache seed --map=parks --tile-matrix-set=WorldCRS84Quad --bounds="-117.25,32.5,-117.0,32.75"

What you get if you omit it

Invocation	Scheme used
--map=parks	the first entry of that map's tile_matrix_sets, in the order written
no --map	WebMercatorQuad, whatever any map lists

"First" is literal — nothing sorts the list, so swapping two entries in the config changes what the same command seeds. A map that omits tile_matrix_sets is given every servable scheme with WebMercatorQuad first, so it too defaults to WebMercatorQuad.

A run that names no scheme warns, and says which one it picked. The wrong scheme is not visibly wrong: a seed fills a cache nothing will read, and a purge leaves the tiles you meant to remove in place while removing another scheme's. Both exit 0.

WARN cache seed/purge: no --tile-matrix-set given, using WorldCRS84Quad
     (the first scheme map "parks" lists). one run covers one scheme --
     pass --tile-matrix-set to choose it

Pass --tile-matrix-set and the warning goes away — the run is then saying what it means.

If any targeted map does not support the run's scheme, the run fails and names those maps rather than skipping them: seeding a map on the wrong pyramid writes tiles no request will ever ask for, and would otherwise report success.

--cache-tiers

No effect on a single-backend cache.

For a layered cache, which tiers a run may write.

$ ./shigola cache seed --map=osm                          # writes the LAST tier only (default)
$ ./shigola cache seed --map=osm --cache-tiers=all        # pre-warm: write every tier
$ ./shigola cache seed --map=osm --cache-tiers=hot,s3     # an explicit list
$ ./shigola cache seed --map=osm --overwrite              # write, then purge the rest

seed writes only the last tier by default. Seeding every tier would flood the hot tier with cold tiles in seed order, evicting the live working set — the exact harm a chain exists to avoid. The last tier in read order is the durable one by construction.

Two consequences: adding a tier to an existing chain changes what seed writes, and the default assumes tiers are ordered hot → durable, which nothing enforces — a chain of s3 then redis makes seed write the hot tier and skip the durable one.

Names are validated at startup; an unknown name is an error, not a silent no-op. A tier inside a nested chain is addressed by path (nested/inner). When set, --cache-tiers bounds promotion as well as writes, so --cache-tiers=s3 cannot reach the hot tier by either route.

--overwrite purges the tiers it does not write, after writing them. Without that, a re-seed with the durable-only default would leave the hot tier serving pre-update tiles until TTL expiry — so the command documented as the invalidation mechanism would not invalidate what users are served. Writing first closes the window in which a concurrent read could promote the old tile back.

cache seed

The seed subcommand is used to cache tiles on demand.

Note: the Shigola server does not need to be running for this command to execute. However, your caching backend does.

Example

Example: Simple seed

$ ./shigola cache seed --bounds "-117.25,32.5,-117.0,32.75"

This command will seed the only tile at zoom 0, based on the layers specified in the bonn.toml configuration file. The --overwrite ensures the previously cached tile gets overwritten.

cache purge

The purge command is used to remove tiles from the cache. This can be used to remove outdated data, as Shigola prioritizes the cache.

Example

Example: Simple purge

$ ./shigola cache purge --bounds "-117.25,32.5,-117.0,32.75"

This command will purge the only tile at zoom 0, based on the layers specified in the bonn.toml configuration file.

A map's tiles are cached under one key for the whole map and, when it serves layer collections, one key per layer. A purge clears the whole-map tile and every layer's tile. --layers narrows it to the layers named, and still clears the whole-map tile, because that tile contains those layers too:

$ ./shigola cache purge --map=osm --layers=roads --bounds "-117.25,32.5,-117.0,32.75"

To purge over HTTP instead, from a service rather than a shell, see the Cache Admin API.

--layers needs --map, since layer names belong to one map. Seeding covers whole maps only: a seed fills the whole-map tile, and layer tiles are cached as they are requested.

cache [seed|purge] tile-name

The tile-name command and format flag are used to specify tiles according to the slippy tile scheme. The tile-name command takes in the tile described by the format.

Flags

Flags:
      --format string   4 character string where the first character is a non-numeric delimiter followed by 'z', 'x' and 'y' defining the coordinate order (default "/zxy")
  -h, --help            help for tile-name
      --max-zoom uint   max zoom to seed cache to
      --min-zoom uint   min zoom to seed cache from

• min-zoom -- If specified; Shigola will generate a range of tiles (from min-zoom to max-zoom (defaults to 22)) for each tile listed in the file.
• max-zoom -- If specified; Shigola will generate a range of tiles (from min-zoom (defaults to 0) to max-zoom) for each tile listed in the file.
• format -- 4 characters string defining the tile format. See: tile_format.

Global Flags

Example

Example: Simple seed tile-name

$ ./shigola cache seed tile-name 0/0/0

cache [seed|purge] tile-list

The tile-list command instructs Shigola to read tile names from a file. The file is expected to have one tile per line, where each tile is formatted according to the format flag.

Flags

Flags:
      --format string   4 character string where the first character is a non-numeric delimiter followed by 'z', 'x' and 'y' defining the coordinate order (default "/zxy")
  -h, --help            help for tile-list
      --max-zoom uint   max zoom to seed cache to
      --min-zoom uint   min zoom to seed cache from

• min-zoom -- If specified; Shigola will generate a range of tiles (from min-zoom to max-zoom (defaults to 22)) for each tile listed in the file.
• max-zoom -- If specified; Shigola will generate a range of tiles (from min-zoom (defaults to 0) to max-zoom) for each tile listed in the file.
• format -- 4 characters string defining the tile format. See: tile_format.

Global Flags

Example

Example: Simple file list expired_tiles.txt (with /zxy format):

15/0/0
15/0/1
15/1/1

$ ./shigola cache seed tile-list expired_tiles.txt

This will read the expired_tiles.txt and seed the cache with the exact tiles as listed in the file.

Example: Non-default format tile list expired_tiles.txt (with -xyz format):

0-0-15
0-1-15
1-1-15

$ ./shigola cache seed --tile-name-format="-xyz" --tile-list="expired_tiles.txt" --overwrite

This will do the same as the above example but using a different format.

Example: Simple file list with zooms expired_tiles.txt (with /zxy format):

15/0/0

$ ./shigola cache seed tile-list expired_tiles.txt --min-zoom=14

This will read the expired_tiles.txt and seed the cache with tiles ranging from zoom level from 14-22 that are above and below the 15/0/0 tile.

Tile-Name-Format

The format allows the slippy tile format to be changed. The flag takes a string of length four, where the first character is the delimiter and the following three characters have to be "x", "y", and "z" in the desired order. For example, the definition for z/x/y is /zxy.

Example: Tile name format

$ ./shigola cache seed tile-name "0-0-18" --format="-xyz"

In this example the 0-0-18 will be interpreted as (z:18, x:0, y:0)

Example: Tile name format

$ ./shigola cache seed tile-name "18 0 0" --format=" zxy"

In this example the 18 0 0 will be interpreted as (z:18, x:0, y:0)

Global Flags

Global Flags are valid for all subcommands

• concurrency -- the amount of concurrency to use.
• config -- path to config file (default “config.toml”)
• map -- the name of the map to use from the config file
• layers -- purge only: the layers of --map to purge, together with the map's whole-map tile. Omitted, a purge clears every layer's tile.
• overwrite -- if the tile already exists overwrite it. With a layered cache, also purges the tiers this run did not write.
• cache-tiers -- for a layered cache, the tiers this run may write. See --cache-tiers.
• tile-matrix-set -- the tiling scheme to operate on. See --tile-matrix-set.
• log-threshold -- during seeding, only log tiles slower than this many milliseconds.