maptool/docs/development.adoc

Development guide

Table of Contents

• Web app only
• Offline map data

Web app only

bundle install
bundle exec puma -C config/puma.rb

Open http://127.0.0.1:4567. For auto-reload during development, run via the rerun gem instead:

bundle exec rerun -- bundle exec puma -C config/puma.rb

Tip	Browsers apply heuristic caching to static files even without explicit cache headers, so an edit to public/ (or views/) can appear not to have taken effect on the next reload. Force a real reload (e.g. Ctrl/Cmd+Shift+R) if that happens.

Offline map data

To enable the offline style, place a PMTiles file at data/offline.pmtiles (see docs/architecture.adoc for how it is served and styled). It is not part of the repository — obtain or build one locally:

• The simplest source is a pre-built extract from protomaps.com’s extract builder — pick a region and download it as .pmtiles. Its schema is what protomaps-themes-base (the styling library used for the offline style) expects.

• To convert some other vector tile source (e.g. an .mbtiles file) into PMTiles, use the go-pmtiles CLI: pmtiles convert in.mbtiles data/offline.pmtiles.

Once the file is in place, GET /api/offline-tiles reports available: true and the map defaults to the offline style.