= Development guide
:toc:
:toclevels: 2

== Web app only

[source,shell]
----
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:

[source,shell]
----
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
  https://app.protomaps.com[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
  https://github.com/protomaps/go-pmtiles[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.