It started with a Raspberry Pi.

Prologue · where it began

the beginning home lab series · prologue

None of this started as a plan to build a lab. It started with the Home app. I wanted the smart-home devices in the house, the ones that do not speak Apple's HomeKit, to show up in the Home app next to everything else, and the usual answer to that is Homebridge on a Raspberry Pi.

WHAT HOMEBRIDGE DOES

Homebridge is a small Node.js server that pretends to be a HomeKit bridge. Plugins translate each non-HomeKit device into something the Home app understands, and the Home app finds the bridge the way it finds any accessory: by listening for it on the local network over mDNS (Bonjour). That last detail matters later.

ON A MAC: IS ANY HOMEKIT BRIDGE ADVERTISING ITSELF?

# HomeKit accessories and bridges announce _hap._tcp on the local network
dns-sd -B _hap._tcp

THE PI

The Pi was the obvious first home for it: small, silent, cheap to leave on. It was a regular Raspberry Pi with the bare minimum of memory, 1 or 2 GB, and that was the problem. Homebridge, its plugins and the operating system did not fit comfortably, so it kept falling over. Getting everything reliably into the Apple ecosystem was not happening, and a Pi that could not hold one service was never going to hold what I kept wanting to add next.

ONE THING, THEN THE NEXT

So Homebridge moved to a bigger machine, a Dell Precision tower running Ubuntu and Docker. And once there was a real machine on the network, it did not stay one service for long:

Homebridge, the reason for the machine, in a container.
A reverse proxy, so each service had a name instead of a port.
Monitoring, because once several things run you need to know which one stopped.
A Jupyter notebook on the GPU, for coursework and experiments.
Then local language models, a documentation site, a remote browser, and more.

Nobody designed that list. Each item was the obvious next step from the one before, which is how most home labs, and most production systems, actually get built.

WHY THE CONTAINERS NEEDED REAL ADDRESSES

The mDNS detail is the thread into part 1. Multicast discovery does not cross Docker's default bridge network, so a Homebridge container behind it is invisible to the Home app. The standard fix is host networking; the lab went further and gave every container its own address on the LAN with macvlan. To this day Homebridge runs in its own guest with a real network presence, because HomeKit will not have it any other way.

HOMEBRIDGE IN DOCKER, VISIBLE TO THE HOME APP

# simplest: share the host's network, so mDNS just works
docker run -d --name homebridge --restart unless-stopped \
  --network host \
  -v ~/Docker/homebridge:/homebridge \
  homebridge/homebridge:latest

# the web UI is then on port 8581 of the host

ASK AN AGENT

PROMPT: WHY WON'T MY HOMEBRIDGE SHOW UP IN APPLE HOME?

My Homebridge bridge does not appear in, or keeps dropping out of, the Apple Home app. Diagnose it without changing anything yet.

- Where Homebridge runs (Pi, Docker, VM, LXC) and its network mode. If it is in Docker, is it on the default bridge network?
- Whether it is advertising _hap._tcp: check from a Mac with dns-sd -B _hap._tcp, and from the host with avahi-browse -rt _hap._tcp.
- Whether multicast can cross between the bridge and my Apple devices: separate Wi-Fi networks or VLANs, client isolation, or mDNS settings on the router.
- The Homebridge log around the last pairing attempt.
Tell me the single most likely cause first, with the evidence for it.

THE SERIES

← writing One Ubuntu box and a macvlan network → press / for a prompt