Installing Homebridge with Docker

If you already run a Linux home server, a Synology or QNAP NAS, or an Unraid machine, running Homebridge in a Docker container saves you from buying extra hardware. Homebridge runs isolated from your host operating system and starts back up automatically after a reboot.

This guide walks through the required network settings, shows how to launch the container with Docker Compose or Portainer, and explains how to manage it from the Homemanager app or a web browser.

Why run Homebridge in Docker?

• Use existing hardware: Run Homebridge on a machine you already own, saving purchase costs and an extra power plug.
• Clean isolation: Node.js, libraries, and Homebridge stay inside the container without altering your host system.
• Simple backups: Settings, plugins, and HomeKit pairing data live in a single mapped folder on your host, making server moves straightforward.
• Automatic restarts: Using restart: unless-stopped, Docker brings Homebridge back up after crashes or host reboots.
• Built-in FFmpeg: The official image includes ffmpeg with audio transcoding out of the box, so camera plugins work immediately without manual compilation.

Limitation: Docker Desktop on macOS and Windows

Requirements for container setups

Apple Home requires two specific settings to detect accessories and store configuration data permanently. The templates in this guide include both:

1. Host network mode (network_mode: host)

Docker normally isolates containers in an internal bridge network. Apple HomeKit relies on mDNS (Bonjour over UDP port 5353) for local device discovery. These multicast packets cannot cross Docker bridge boundaries.

Homebridge must use host network mode (network_mode: host or --net=host), allowing the container to bind directly to the host's IP address and network interface.

2. Persistent storage (/homebridge)

Container filesystems reset whenever an image updates or a container is recreated.

The internal path /homebridge must map to a persistent directory on your host. This preserves config.json, installed plugins, cache files, and Apple Home pairing keys.

Installation & deployment

The official multi-architecture image is maintained at homebridge/homebridge:latest and supports amd64, arm64, and armv7 processors.

mkdir -p ~/homebridge
cd ~/homebridge

services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./data:/homebridge
    environment:
      - TZ=Europe/Berlin
      - PUID=1000
      - PGID=1000
      - HOMEBRIDGE_CONFIG_UI_PORT=8581

docker compose up -d

mkdir -p ~/homebridge/data

docker run -d \
  --name=homebridge \
  --restart=unless-stopped \
  --net=host \
  -v ~/homebridge/data:/homebridge \
  -e TZ=Europe/Berlin \
  -e PUID=1000 \
  -e PGID=1000 \
  -e HOMEBRIDGE_CONFIG_UI_PORT=8581 \
  homebridge/homebridge:latest

Configuration on NAS and server platforms

Connecting and Initial Setup

Once the container is running, Homebridge is available on your local network. The web interface (homebridge-config-ui-x) acts as the browser dashboard and provides the API that Homemanager connects to.

The instance runs unencrypted over port 8581 by default.

Because this is a fresh setup without existing accounts, you create an administrator account during the first connection. You can do this in the app or in a browser:

http://<your-server-ip>:8581

Maintenance & commands

Updates in Docker happen at two different levels:

1. Updating plugins and Homebridge Core

Update plugins and Homebridge releases directly in Homemanager or through the web interface. All configuration files and dependencies stay in your mapped /homebridge folder, so changes persist across container restarts. You do not need to rebuild the container for plugin updates.

2. Updating the Docker base image (Node.js & OS)

To update the underlying Node.js runtime and base system libraries, pull the latest image:

cd ~/homebridge
docker compose pull
docker compose up -d

3. Useful commands in the terminal, app & web UI

You can run maintenance commands without logging into the host over SSH:

• Homemanager app & web UI: Both include a built-in terminal to run commands directly inside the container environment.
• Host terminal (docker exec): If you are connected to the host via SSH, run commands with docker exec.

# Reset the administrator password to admin/admin
docker exec -it homebridge hb-service reset-admin

# Follow live container logs
docker logs -f homebridge

# Open an interactive shell inside the container
docker exec -it homebridge sh

# Restart the container
docker restart homebridge

4. Installing extra system packages (PACKAGES)

Some plugins need additional system binaries (like Bluetooth utilities or specialized tools).

The official image installs these packages automatically on startup when declared under environment in docker-compose.yml:

environment:
  - TZ=Europe/Berlin
  - PACKAGES=libcap2-bin,iputils-ping

Troubleshooting common issues

Next steps

Once Homebridge is running in Docker:

1. Pair with Apple Home:
   Scan the setup QR code in Homemanager or on the web dashboard with the Apple Home app on your iPhone.
   Apple Home pairing guide

2. Install plugins:
   Search for device integrations in Homemanager or the web interface (such as Tuya, Shelly, FritzBox, Ring, or cameras).
   Tips on finding and evaluating plugins

3. Set up child bridges:
   Isolate larger plugins into separate processes so an issue with one accessory does not affect the rest of your home.
   Learn more about child bridges

Reference links

• Official Homebridge Wiki: Install Homebridge on Docker
• Official Docker Image Repository (homebridge/homebridge)
• Homebridge Docker Image on Docker Hub
• Homebridge on Unraid (Wiki)
• Homebridge on QNAP Container Station (Wiki)
• Homebridge on TrueNAS SCALE (Wiki)
• Official Homebridge Discord Server (#docker channel)
• Docker Documentation: Host networking driver