Skip to Content

Map tiles service

Keeps the world map in your map bucket up to date, and lets you check on it or roll it back.

The map tiles service downloads the Protomaps world map into your map bucket and keeps it current. It checks for a new map when it starts, and again when the map in use is MAP_TILES_UPDATE_INTERVAL_DAYS (30) days old, counted from the date Protomaps built it. A new map is only downloaded when:

  • the bucket has no map yet, or the one in use is at least 30 days old,
  • Protomaps has published a newer map in the format the app expects, and
  • the spare copy isn't still being used by anyone.

So the map changes about once a month. If the map is due but Protomaps has nothing newer, the service checks again 30 days later. If an update fails, it tries again after an hour, doubling the wait after each failure up to a day.

Two copies, used in turn

The bucket holds two copies of the map, A and B. One is always in use. The other is either empty, downloading a newer map, or kept as the fallback. An update never touches the copy in use, so the map keeps working the whole time.

What happensCopy ACopy B
1. First start
The service downloads the first map into copy A. The app says the server is still preparing the map.
DownloadingOctober map
Empty
2. A few hours later
The download is checked and switched on. Everyone's map now works.
In useOctober map
Empty
3. About a month later
Protomaps has a newer map. It downloads into the spare copy while copy A stays in use.
In useOctober map
DownloadingNovember map
4. Download checked
The app switches to copy B. Copy A is kept as the fallback.
FallbackOctober map
In useNovember map
5. About a month later
The next map replaces the fallback, which nobody has used for weeks.
DownloadingDecember map
In useNovember map
6. Download checked
The app switches back to copy A, and copy B becomes the fallback. And so on.
In useDecember map
FallbackNovember map
How the two copies take turns. Each update goes into the copy that isn't in use.

What an update does

  1. Checks the spare copy is free to replace (see below).
  2. Downloads the new map from Protomaps, about 130 GiB, and uploads it into the spare copy, in parts. The service keeps nothing on disk itself, only in the bucket. With the quick start, the bucket is on the same disk.
  3. Checks the upload against the original.
  4. Switches the app to the new copy. The old one becomes the fallback.

The fallback

After a switch, the old copy is kept:

  • Apps that already had the map open keep using it for up to 7 days, so they never mix parts of two maps. Newly opened maps use the new copy within about a minute.
  • You can roll back to it if the new map is broken.
  • It can't be replaced until 8 days after the switch. Updates come about every 30 days, so in practice it stays until the next update. This is why MAP_TILES_UPDATE_INTERVAL_DAYS must be more than 8.

The app's Account › About screen shows which copy is in use and the date of its map.

Check on it

The commands on this page are for the quick start. Run them in the folder with docker-compose.yml. If you run the containers another way, use docker exec with your map tiles container's name instead, such as docker exec openbeacon-map-tiles map-tiles status.

docker compose exec map-tiles map-tiles status

This shows which copy is in use, the map build in each copy, when the spare copy can be replaced, when the map is due for an update, when the service next checks, any speed limit, whether an update is running and how the last one ended. For example:

Bucket: openbeacon-map
Map in use: slot B
Slot A: Protomaps build 2026-11-01 (schema 4.15.2, 120.3 GiB, published 2026-11-02T03:12:44.000Z), still served to open maps until 2026-12-09T03:00:00.000Z
Slot B: Protomaps build 2026-12-01 (schema 4.15.2, 121.0 GiB, published 2026-12-02T03:00:00.000Z), in use
The standby slot can be replaced from 2026-12-10T03:00:00.000Z
Map due for update: from 2026-12-31T00:00:00.000Z, if Protomaps has a newer build
Next check: 2026-12-31T00:00:00.000Z
Speed limit: 100 Mbps each way (MAP_TILES_MAX_MBPS)
Update: not running
Last update: published at 2026-12-02T03:00:00.000Z: Published build 20261201 to slot b. Newly opened maps use it within about a minute.

It can show three more lines. Rolled-back build names a map you rolled back from. Resumable upload is an unfinished upload saved for the next update. Untracked archive is a map file in the bucket that the service isn't using, such as the spare copy while it's being replaced.

For more detail, follow the log with docker compose logs -f map-tiles. It logs progress and the reason for every skip or failure.

Update now

docker compose exec map-tiles map-tiles update

This ignores the 30-day interval, but still does nothing if Protomaps has nothing newer or the spare copy may still be in use. It returns straight away; a full update takes several hours.

Roll back a bad map

docker compose exec -it map-tiles map-tiles rollback

It asks you to confirm. Add --yes if you're running it without a terminal. Apps move off the bad map within about 10 minutes. You can roll back until the spare copy is replaced, at least 8 days after the switch. The next update then replaces the bad map.

The service remembers the map you rolled back from. Scheduled updates skip it until Protomaps publishes a newer one. map-tiles update installs it anyway.

You can't roll back while an update is running.

If it's interrupted

If the service stops during an upload, it carries on from the parts already uploaded when it starts again. This only works while that map is still the newest one Protomaps offers. If Protomaps has published a newer map by then, the next update removes the unfinished upload and starts the newer map from the beginning.

Whenever it starts an upload from the beginning, the service first removes any unfinished upload left in that copy. If your provider removes an unfinished upload before the service resumes it, as Cloudflare R2 does after 7 days by default, the next attempt also starts from the beginning.

The service also repairs its own bookkeeping. If the copy in use has gone missing from the bucket, it switches to the other one. If the spare copy has gone missing, it stops offering it as the fallback. If both are missing, it downloads the map again.

Starting problems

At startup the service checks its settings, that it can list the bucket and write and delete a small test object, and that it can write to /state. If a check fails, it exits and names the problem, with a line above it saying which setting to look at:

  Map storage: check MAP_S3_REGION
  Map storage: failed (AuthorizationHeaderMalformed)

AccessDenied usually means the access key can't write to the bucket. ENOTFOUND usually means the endpoint is wrong, or your provider needs MAP_S3_FORCE_PATH_STYLE=true.

On this page