Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

docs: explain why Docker bridge networking yields no MAC addresses

Pouzore988427bb2d2
diff --git a/INSTALLATION.md b/INSTALLATION.md
index 2fdcfd6..573c757 100644
--- a/INSTALLATION.md
+++ b/INSTALLATION.md
@@ -63,6 +63,48 @@ docker compose -f docker-compose.prebuilt.yml up -d
Update 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.md
index 44c9884..f93d243 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,14 @@ SCANNER_HTTP_VERIFY_TLS=false # verify TLS certs on the HTTP probe
The 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 privileges
Some 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.yml
index c62ae23..25c6927 100644
--- a/docker-compose.prebuilt.yml
+++ b/docker-compose.prebuilt.yml
@@ -13,6 +13,12 @@ services:
- homelable
cap_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: host
frontend:
image: ghcr.io/pouzor/homelable-frontend:latest
diff --git a/docker-compose.yml b/docker-compose.yml
index 16c9b2a..ffa434a 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -16,6 +16,12 @@ services:
# Required for ping-based status checks
cap_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: host
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:8000/api/v1/health"]
interval: 10s