netbox-discovery-quickstart: add macOS support via Lima VM, fix NetBox/Diode plugin version mismatch

[domfee]

Summary

Adds macOS support to the NetBox Discovery quickstart, and fixes a real (platform-independent) version-compatibility bug hit along the way.

Changes

0_macos_create_vm.sh (new)
ContainerLab has no native macOS support, and the Nokia SR Linux lab images are x86_64-only. A native arm64 Lima VM was tried first, but SR Linux's system daemons boot-loop under QEMU's per-process binfmt emulation — they need kernel/ioctl behavior that only a genuine x86_64 kernel provides. This script bootstraps a Lima-managed x86_64 Ubuntu 25.04 VM sized for the workload (11 CPUs / 16GiB RAM by default — fewer CPUs caused Device Discovery's bulk NetBox writes to time out under emulation) and prints the next commands to run inside it.

3_start_netbox.sh
Bumped netbox-docker from 3.3.0 (paired with NetBox v4.3.7) to 5.0.2 (paired with NetBox v4.6.7), and pinned the Diode plugin to 1.14.1. The script previously installed the plugin unpinned, which now resolves to a release requiring NetBox >=4.4.10 — so on the pinned v4.3.7 base, the plugin silently failed to load (Unable to load plugin netbox_diode_plugin: ... requires NetBox minimum version 4.4.10 (current: 4.3.7)), and neither Network Discovery nor Device Discovery could actually reach NetBox. This isn't macOS-specific — anyone running the quickstart fresh right now would hit it. Also raised the NetBox healthcheck start_period from 600s to 1800s to match realistic first-migration timing on a freshly-provisioned host.

README.md

• New "Running on macOS" section explaining the above and pointing to 0_macos_create_vm.sh.
• Notes on Lima's automatic port-forwarding, the non-interactive su - quickstart step, and realistic migration timing.
• New Troubleshooting section covering issues hit getting this working end-to-end:
  • netbox-docker-netbox-housekeeping-1 exiting once on a benign first-boot race
  • Diode's nginx caching a stale upstream IP after container restarts (502s)
  • Device Discovery's bulk NetBox writes timing out under CPU-constrained emulation
  • Diode's ingestion-log dedup permanently blocking retries of previously-failed content (a footgun if you retry after fixing an earlier failure)
  • NetBox 4.6's new v2 API token format, for anyone scripting against the API directly

Verification

Ran the full quickstart end-to-end on macOS (Apple Silicon) via the new Lima VM path: NetBox + Diode plugin load correctly, Network Discovery lands all expected IPs in IPAM, and Device Discovery lands both SR Linux devices in DCIM with correct Device Type/Platform/Status and full interface data (MAC address, MTU, speed) including the inter-device link ethernet-1/1.

🤖 Generated with Claude Code

[mrmrcoleman]

Hey @domfee I'm not in front of laptop but this seems reasonable. I would just ask to bots to make sure that this enables MacOS but doesn't disable Linux in doing so.