Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
docs: explain why Docker bridge networking yields no MAC addresses
Pouzore988427bb2d2
diff --git a/INSTALLATION.md b/INSTALLATION.mdindex 2fdcfd6..573c757 100644--- a/INSTALLATION.md+++ b/INSTALLATION.md@@ -63,6 +63,48 @@ docker compose -f docker-compose.prebuilt.yml up -dUpdate the same way: `docker compose -f docker-compose.prebuilt.yml pull && … up -d`.+## Scanning from Docker — MAC addresses++Out of the box the backend runs on a Docker bridge network, and **the scan will+never report a MAC address** from it. MACs come from ARP, which is layer 2: the+container's ARP cache holds only the Docker gateway, and nmap can read a target's+hardware address only when that target sits in the same broadcast domain. From a+bridge every LAN host is one hop away behind the gateway, so the field stays+empty. `cap_add: NET_RAW` does not change this — the capability grants raw+sockets, not a place on the LAN.++This also affects device identity. When a device is rescanned it is matched on+MAC first and IP second, so without MACs a DHCP lease change makes the device+come back as a new entry in the inventory instead of updating the old one.++To collect MACs, put the backend on the LAN itself. In `docker-compose.yml` (or+`docker-compose.prebuilt.yml`), comment out the backend's `networks:` key and+uncomment:++```yaml+ network_mode: host+```++then `docker compose up -d`. Caveats:++- **Linux only.** On Docker Desktop for macOS and Windows the containers run+ inside a VM, so host networking still does not reach your physical LAN. There+ is no MAC-capable Docker setup on those platforms — run the+ [bare-metal install](#bare-metal--no-docker) instead.+- The backend binds `8000` directly on the host, with no port mapping and no+ network isolation from other host services.+- `frontend` and `mcp` reach the backend at `http://backend:8000` over the+ `homelable` bridge; once the backend leaves that network they need+ `http://127.0.0.1:8000` instead. Set `BACKEND_URL` on `mcp`, and for the front+ end either give it `network_mode: host` too or point its nginx proxy at the+ host address.++The alternative, if you would rather keep the backend isolated, is a **macvlan**+network, which gives the container its own MAC and IP on your physical LAN.+It needs a parent interface and a spare address range from your subnet, and on+most setups the Docker host itself cannot talk to a macvlan container without an+extra shim interface.+## Build from source`docker-compose.yml` at the repo root builds the images locally instead of pulling them — use it for development, or to run a patched tree.diff --git a/README.md b/README.mdindex 44c9884..f93d243 100644--- a/README.md+++ b/README.md@@ -110,6 +110,14 @@ SCANNER_HTTP_VERIFY_TLS=false # verify TLS certs on the HTTP probeThe listed ports are appended to nmap's `-p` spec. Invalid entries (out-of-range, malformed, or reversed ranges) are silently skipped.+### MAC addresses (Docker)++The scan reports no MAC address when the backend runs on a Docker bridge+network — ARP is layer 2, and from a bridge every LAN host sits behind the+Docker gateway. It also means a DHCP device that changes IP comes back as a new+inventory entry, since matching prefers the MAC. Fix and caveats:+[INSTALLATION.md](./INSTALLATION.md#scanning-from-docker--mac-addresses).+### macOS / root privilegesSome nmap scan types (SYN scan, OS detection) require root. If the scan fails with a permissions error, run it manually with sudo using the included script:diff --git a/docker-compose.prebuilt.yml b/docker-compose.prebuilt.ymlindex c62ae23..25c6927 100644--- a/docker-compose.prebuilt.yml+++ b/docker-compose.prebuilt.yml@@ -13,6 +13,12 @@ services:- homelablecap_add:- NET_RAW+ # MAC addresses: on this bridge network the scanner can never see them —+ # ARP is layer 2 and every LAN host is one hop away behind the Docker+ # gateway. To collect MACs (and so keep DHCP devices matched across an IP+ # change), put the backend on the LAN: comment out the `networks:` key+ # above and uncomment the line below (Linux hosts only).+ # network_mode: hostfrontend:image: ghcr.io/pouzor/homelable-frontend:latestdiff --git a/docker-compose.yml b/docker-compose.ymlindex 16c9b2a..ffa434a 100644--- a/docker-compose.yml+++ b/docker-compose.yml@@ -16,6 +16,12 @@ services:# Required for ping-based status checkscap_add:- NET_RAW+ # MAC addresses: on this bridge network the scanner can never see them —+ # ARP is layer 2 and every LAN host is one hop away behind the Docker+ # gateway. To collect MACs (and so keep DHCP devices matched across an IP+ # change), put the backend on the LAN: comment out the `networks:` key+ # above and uncomment the line below (Linux hosts only).+ # network_mode: hosthealthcheck:test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]interval: 10s