diff --git a/docs/impl/reports/VALHALLA-ARM64.md b/docs/impl/reports/VALHALLA-ARM64.md new file mode 100644 index 0000000..dd1fe30 --- /dev/null +++ b/docs/impl/reports/VALHALLA-ARM64.md @@ -0,0 +1,108 @@ +--- +type: default +--- +# Valhalla on the Jetson: arm64 viability and the driving-side trap + +**Date:** 2026-09-04 +**Host:** `mikkeli-orin-nano-2` (192.168.2.209), aarch64, Ubuntu 22.04.5, L4T R36.4.7 / JetPack 6 +**Outcome:** arm64 works. A separate, silent correctness bug was found and fixed. + +## Why this was investigated + +Valhalla's arm64 container support was recorded as the one real integration risk +in the navigation workstream, on the strength of a long-running upstream issue +(valhalla/valhalla#3424) about building arm64 images. Everything else in the +workstream was blocked behind the answer. + +## arm64: not a risk + +The issue is stale. Checked before pulling anything: + +``` +docker manifest inspect ghcr.io/valhalla/valhalla:latest + → linux/amd64, linux/arm64 +``` + +Both `ghcr.io/gis-ops/docker-valhalla` and `ghcr.io/nilsnolde/docker-valhalla` +also publish arm64. The official image runs natively; `valhalla_build_config`, +`valhalla_build_admins` and `valhalla_build_tiles` all execute. Version 3.8.3. + +Full pipeline verified: config → timezones → admins → tiles → served route. + +| Measurement | Value | +|---|---| +| Shikoku PBF | 49 MB | +| Routing tiles from it | 149 MB | +| Whole-Japan PBF | 2.4 GB | +| Admin DB from whole Japan | 17 MB | +| Timezone DB | 116 MB | +| Route Takamatsu → Matsuyama | 157 km, 112 min | + +Japanese street names survive intact in the route narrative +(`高松南バイパス`, `高松停車場栗林公園線/173`), so CJK is fine on the routing +path as well as the rendering path. + +A benign warning appears at startup: + +``` +[ERROR] (stat): /data/valhalla/tiles.tar No such file or directory +[WARN] Tile extract could not be loaded +``` + +The server falls back to the tile *directory*, which is the form we want anyway. +Not an error condition. Do not "fix" it by switching to the tar. + +## The actual finding: a sub-region extract silently mirrors the map + +The plan said to start from a regional extract to keep artifacts small. That is +correct for routing tiles and **wrong for the admin database.** + +Built from `shikoku-latest.osm.pbf`: + +``` +by admin_level: [(4, 4)] + (4, '36', '徳島県', drive_on_right=1) + (4, '39', '高知県', drive_on_right=1) + (4, '38', '愛媛県', drive_on_right=1) + (4, '37', '香川県', drive_on_right=1) +``` + +No `admin_level=2` row at all, and right-hand traffic on every prefecture. + +Built from `japan-latest.osm.pbf`: + +``` +by admin_level: [(2, 1), (4, 47)] + (2, 'JP', '日本', 'Japan', drive_on_right=0) +``` + +Driving side is a **country-level** property. A Shikoku-clipped extract does not +contain Japan's country boundary, so no country record exists and the value +defaults to 1. + +### Why this is dangerous + +`valhalla_build_admins` **exits successfully.** Nothing warns. Nothing fails. The +tiles build fine and the server serves routes. The first symptom is a turn +instruction that is subtly wrong, on a road the driver may not know well. + +### The fix + +The admin build and the tile build are separate invocations reading the same +config, so they can take different inputs: + +- admins ← `japan-latest.osm.pbf` (always the full country) +- tiles ← whatever regional extract is wanted + +Cost is one 2.4 GB download, which is not repeated per region. + +### The rule that follows + +Never assume this worked. Every build asserts that a country-level row exists and +reports `drive_on_right=0` before its tiles are treated as usable. A check is +cheap; the failure is silent and the consequence is on a road. + +## Left on the host + +`~/valhalla-test/` — 2.8 GB, kept deliberately. It is a working Valhalla install +with the Japan PBF already fetched, which is the expensive part to reproduce.