Build the website¶
git submodule update --init --recursive MAMUT-routing-lib MAMUT-routing-tools benchmarks/Poryos2026 benchmarks/Mamut2026
uv sync
uv run mamut-routing-publish site build --precompress
uv run mamut-routing-publish serve # http://127.0.0.1:8082/
Only initialized families are published. dist/ is fully static.
Phases of site build¶
| Phase | What it does | Knobs |
|---|---|---|
| resolve snapshot | commit, branch, snapshot id (<date>-<short sha> by default) |
--source-commit, --source-branch, --published-at, --snapshot-id, --history-summary |
| ATF cache | materializes arrival-time sidecars of materialized-td-model families (Lera2026, Poryos2026 TD) into dist/atf-cache/, one file per (family, instance), incremental by recorded sha |
--atf-max-n (400), --atf-jobs (memory knob: one full ATF set per worker), --skip-atf-cache |
| route geometry | road-following BKS polylines into dist/route-geometry-cache/, content-addressed by BKS sha256; validates and fetches missing OSM extracts under osmdata/ first |
--route-geometry-jobs (auto = 1: a city graph can exceed 15 GiB), --no-fetch-missing-osm, --skip-route-geometry |
| payloads | dist/site-payloads/**.json, one per route, instances resolved in parallel; writes the history ledger |
--jobs (auto = cores − 2), --schema-version, --payload-root-dir |
| webapp | thin HTML shells per route, assets, workbench page | --payload-mode static|api, --basemap-api-key / MAMUT_BASEMAP_API_KEY |
| docs | this documentation into dist/docs/ (strict MkDocs build) |
--skip-docs |
| precompress | .gz + .br sidecars for text assets ≥ 1 KiB, incremental by mtime |
--precompress |
--progress-format text|json, --quiet and --list-files control reporting; the JSON summary on stdout carries every
phase's counters. Standalone commands exist for each phase (site materialize-atf, site materialize-route-geometry,
site payloads, site webapp, site docs, site precompress).
Staging builds and the three roots¶
publish_roots.py names the roots: the source repo (read-only inputs), the site output (the only tree a build
writes), the state dir (history ledger and inventories, publish-state/ by default). A staging build
(--site-output-dir <fresh dir>) seeds its caches from the active dist by hardlinks and never writes it; on a
deployment dist is a symlink to the live release, swapped atomically after the build succeeded.
uv run mamut-routing-publish site build --site-output-dir /srv/mamut/releases/dist-$(date +%Y%m%d-%H%M%S) \
--state-dir /srv/mamut/releases/publish-state --precompress
Memory and duration¶
Payloads and shells take minutes; the caches take hours the first time and seconds afterwards. Route geometry is the
memory hog (Berlin peaked near 10 GB; Bogota with n=4000 did not finish in 90 minutes on a 6-vCPU host). Prefer
computing geometry once on a workstation and copying dist/route-geometry-cache (keyed by BKS sha, so it is portable)
into the release directory of the host; the next build reports generated=0 reused=N.
The documentation phase¶
Strict: any broken link, missing nav target, broken anchor or unresolved API reference fails the build (and CI);
external URLs are not checked. Iterate with uv run mkdocs serve or uv run mamut-routing-publish site docs
--site-output-dir dist-preview, and preview a staging tree with serve --site-dir dist-preview. A checkout without
mkdocs.yml skips the phase; a checkout without the docs toolchain fails before the cache phases unless --skip-docs.
Previewing a staging build¶
serve serves <repo>/dist unless told otherwise. To look at a staging build without touching the live tree or
the publication history:
uv run mamut-routing-publish site build --site-output-dir dist-preview --state-dir dist-preview-state --skip-atf-cache --skip-route-geometry
uv run mamut-routing-publish serve --site-dir dist-preview
Checking a build¶
dist/index.htmlopens and lists the families you initialized;- an instance page shows road-following routes (or straight lines where geometry was skipped);
/history/shows the new snapshot with the expected counts;/docs/opens with the search working;curl -sI -H 'Accept-Encoding: br' http://127.0.0.1:8082/site-payloads/index.jsonreturnscontent-encoding: brafter--precompress.