Add report: Valhalla arm64 verification and the driving-side trap

Records the investigation including the dead end — a sub-region admin build succeeds silently while producing right-hand-traffic routing — since that is the part worth keeping. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013kj58Jugkic783b8ZrtTVZ
2026-09-04 10:57:36 +09:00
parent 8ee3d4cde5
commit 0e0ff7c4b4
1 changed files with 108 additions and 0 deletions
@@ -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.