Run-it-in-Docker section in beyond-the-lan: image location, volume layout, exec-based CLI verbs, host-vs-bridge networking trade-off, health check port, and bind-mount ownership. Platform claims corrected across beyond-the-lan, self-host tutorial, and troubleshooting: full support is macOS arm64 and Linux x86_64; arm64 Linux cannot boot the node because jazz-napi ships no linux-arm64-gnu build (documented next to the existing Windows gap).
- commit
- 079104107dc7b8864d48861bc4b9e14216ebe001
- parent
- 81309c692b5fd6c90af45db33a7882c83750e75a
- author
- Dami <dami.etoile@gmail.com>
| M | docs/ | 47 | ++++++++++++++++++++++++++++-- |
| M | docs/ | 5 | ++- |
| M | docs/ | 8 | ++++- |
@@ -60,15 +60,56 @@ forgoes relay-assisted address discovery, so expect hole-punching to suffer acro
6060 deno task compile # → dist/lofi-node6161 ```6262 63-The compiled binary embeds the prebuilt native transport matrix — macOS arm64 and x86_64, Linux64-x86_64 and aarch64 — and extracts the right library to a version-keyed OS cache on first run.65-Artifact digests are pinned in the source, so an extraction that doesn't match its pin fails loudly.63+The compiled binary embeds the prebuilt native transport layer and extracts it to a version-keyed OS64+cache on first run. Artifact digests are pinned in the source, so an extraction that doesn't match65+its pin fails loudly. Release binaries cover macOS arm64 and Linux x86_64.6666 6767 **Windows** is a documented gap: the native layer's build path needs a `libnode.dll` import library6868 the upstream toolchain doesn't ship for this configuration. On Windows the node runs LAN-only — the6969 Jazz server works, `status().mesh` reports `{ state: "unavailable", reason: … }`, and7070 `ticket()`/`pair()` throw typed errors rather than degrade silently.7171 72+**Linux aarch64** is a second documented gap: the Jazz engine (jazz-napi) publishes no73+linux-arm64-gnu build, so neither a compiled binary nor a native container image can boot on arm6474+Linux. The iroh transport layer is built for the platform already; the target returns when the75+upstream package appears.76+77+## Run it in Docker78+79+The container image wraps the same compiled binary in a minimal glibc base:80+`ghcr.io/felinestatemachine/lofi-node`, published per release, linux/amd64 (per the platform note81+above; Docker Desktop and qemu run it on arm64 hosts under emulation).82+83+```sh84+docker run --rm -v lofi-node-data:/data ghcr.io/felinestatemachine/lofi-node \85+ init --dir /data --port 4802 --public-url https://sync.example.net86+docker run -d --name lofi-node --network host \87+ -v lofi-node-data:/data ghcr.io/felinestatemachine/lofi-node88+```89+90+Everything durable lives in the `/data` volume: `config.json`, the node identity key,91+`tickets.json`, and the SQLite store. CLI verbs run through `docker exec` against the same directory92+and take effect without a restart, exactly as outside a container:93+94+```sh95+docker exec lofi-node lofi-node ticket issue --dir /data --label phone96+```97+98+Two container-specific choices matter:99+100+- **Networking.** Host networking keeps Docker's bridge NAT out of iroh's hole-punching path. A101+ bridge network with a published port (`-p 4802:4802`) serves apps through the gate without issue,102+ but paired nodes behind it are more likely to fall back to relayed traffic103+ ([the relay's role](pair-two-homes.md)). Host networking is a Linux feature; Docker Desktop104+ supports it from version 4.34.105+- **The health check** probes `http://127.0.0.1:4802/health`. A node initialized with a different106+ `--port` needs the check overridden in compose.107+108+The image runs as uid 1000. Named volumes inherit that ownership; a bind mount must be writable by109+uid 1000 (`chown 1000:1000 <dir>`) or the storage probe fails at boot, naming the path. The110+repository's [compose.yaml](https://github.com/FelineStateMachine/lofi-node/blob/main/compose.yaml)111+is the reference deployment.112+72113 ## The version invariant73114 74115 A node pins the **exact** Jazz alpha of the apps it serves; version bumps are coordinated changes,@@ -23,8 +23,9 @@ For a single self-contained binary instead, compile from a checkout of
2323 deno task compile # → dist/lofi-node2424 ```2525 26-Either way, the native transport layer covers macOS arm64/x86_64 and Linux x86_64/aarch64; on27-Windows the node runs LAN-only ([why](troubleshooting.md)).26+Either way, full support covers macOS arm64 and Linux x86_64 (including the27+[container image](beyond-the-lan.md)); on Windows and arm64 Linux the node is limited28+([why](troubleshooting.md)).2829 2930 ## 2. Initialize and start3031 @@ -18,8 +18,12 @@ rather than degrade silently. Causes, in resolution order:
1818 needs a `libnode.dll` import library the upstream toolchain ships only for msvc). Windows nodes1919 run LAN-only until that resolves.2020 21-The compiled binary embeds digest-pinned prebuilts for macOS arm64/x86_64 and Linux x86_64/aarch64;22-a cache extraction that doesn't match its pin fails loudly rather than loading.21+On **arm64 Linux** the limitation sits one layer deeper: the Jazz engine (jazz-napi) publishes no22+linux-arm64-gnu build, so the node cannot start at all there. Release binaries and the container23+image cover macOS arm64 and Linux x86_64 ([platform notes](beyond-the-lan.md)).24+25+The compiled binary embeds digest-pinned prebuilts; a cache extraction that doesn't match its pin26+fails loudly rather than loading.2327 2428 ## 401 `invalid_ticket`2529