Skip to content

Deploying a new tileset

Tilesets are versioned by filename and rolled out through the catalog. See Serving tiles for how the catalog maps names to MBTiles.

tile_job

tile_job is a swarm global-job (manifest workers.tile_job) that runs tile.sh on every worker. It reads MBTILES_CATALOG, downloads each listed file it doesn't already have from s3://<MBTILES_BUCKET>/mbtiles/ (MBTILES_BUCKET defaults to develop-swarm-woosmap-eu-west-2), validates it, and removes any *.mbtiles not in the catalog (skipping files still locked by a running container). Run it before re-deploying the service so the new files are on disk first.

Rolling out a new version

MBTILES_CATALOG must list a file before tile_job can pull it, and the maps service must be re-deployed to pick up the updated catalog and defaults. So each phase is: change config, run tile_job, deploy maps.

Phase 1: make the new tiles available (default unchanged).

  1. Upload the new MBTiles to s3://<MBTILES_BUCKET>/mbtiles/.
  2. Add the new filename to MBTILES_CATALOG, leaving MBTILES_FILENAME / STREETS_MBTILES_FILENAME pointing at the old file.
  3. Run tile_job: every worker pulls the new file to /var/lib/db/.
  4. Deploy the maps service: containers load the new catalog. They can now serve the new name on request, but styles still emit the old default.

Phase 2: flip the default.

  1. Set the default (STREETS_MBTILES_FILENAME or MBTILES_FILENAME) to the new filename.
  2. Deploy the maps service. Styles now emit the new name. Phase-1 containers still carry it in their catalog and new containers still carry the old name, so the roll overlaps with no window where a request resolves to the wrong file.

Phase 3: drop the old version.

  1. Remove the old filename from MBTILES_CATALOG.
  2. Run tile_job (reaps the old file, skipping any still locked) and deploy the maps service. A late request for the dropped name returns 404; the client refetches the (never-cached) style and gets the current name.
flowchart LR
    A[Upload to S3] --> B[Add name to catalog]
    B --> C[Run tile_job]
    C --> D[Deploy maps]
    D --> E[Flip default]
    E --> F[Deploy maps]
    F --> G[Drop old name]
    G --> H[tile_job + deploy]

Updating the sprite

Sprites are style assets (served from styles/streets-v{N}/sprites/, selected by DEFAULT_STYLE_VERSION), not the MBTILES_CATALOG. When updating the sprite, bump the streets asset version (streets-v{current + 1}) and keep the previous version's assets around until the deploy has fully rolled, so in-flight clients referencing the old version don't 404.