docker-homebridge: Open Source Internet of Things (IoT)

What is docker-homebridge?

docker-homebridge is the official Docker image for Homebridge, packaging the HomeKit bridge that emulates the iOS HomeKit API on a local network as a multi-architecture container for x86_64, ARM32v7 and ARM64v8 hosts.

What it is

docker-homebridge is the official container distribution of Homebridge, maintained in the Homebridge GitHub organisation and written primarily in Shell. It is licensed under GPL-3.0 and ships the Homebridge runtime together with ffmpeg and libfdk-aac, so media-related plugins that depend on those libraries work without extra host packages. The published images are multi-architecture, covering amd64, arm32v7 and arm64v8, and they are built on Ubuntu 24.04 by default, with an Ubuntu 22.04 variant provided for Synology compatibility. The tag family covers stable releases through latest and ubuntu, Homebridge 1.x through legacy, the older base image through synology, and pre-release builds through beta and alpha.

The project addresses the installation and maintenance problem that surrounds Homebridge itself. Homebridge is a Node.js application that presents non-HomeKit accessories to Apple's Home app, and running it reliably means matching Node versions, native dependencies and mDNS behaviour to whatever hardware is available. This image replaces hand-built Homebridge installations and the community oznu/homebridge image that it migrated from, standardising the runtime, the bundled multimedia libraries and the container configuration. It belongs to the smart-home and IoT ecosystem, and it exists so that a self-hoster can bring up the same known-good runtime on a Raspberry Pi, an ARM64 board or an x86_64 server.

Key capabilities

Multi-architecture images for amd64, arm32v7 (Raspberry Pi) and arm64v8 hosts.
Release tags covering latest and ubuntu, legacy (Homebridge 1.x), synology (Ubuntu 22.04 base), beta and alpha.
ffmpeg and libfdk-aac bundled in the image for media-related plugins.
Host networking through network_mode: host or --net=host, which is required for HomeKit discovery.
Persistent configuration and plugins through a volume mount such as ./volumes/homebridge:/homebridge.
Environment controls for TZ and for Avahi mDNS, with ENABLE_AVAHI=1 by default and 0 to disable it.
A healthcheck polling http://localhost:8581, shown in the Compose example alongside restart: always and capped json-file logging.

Who uses it and how

Raspberry Pi owners run it on ARM32v7 or ARM64v8 boards as a small, always-on home hub appliance.
Synology NAS users select the synology tag to stay on the Ubuntu 22.04 base image their platform tolerates.
Home servers on x86_64 hosts run it with host networking so HomeKit can discover the bridge on the local network.
Users with existing Homebridge 1.x configurations pin the legacy tag to remain on 1.x stable releases.
Plugin authors and early testers follow the beta and alpha tags to exercise pre-release Homebridge versions.

Getting started

The recommended route is Docker Compose: create a docker-compose.yml using the image homebridge/homebridge:latest with network_mode: host, a ./volumes/homebridge:/homebridge volume and a restart policy, then run docker compose up -d. The same container can be started with a single docker run command using --net=host and a volume mount, and the images are published on Docker Hub at hub.docker.com/r/homebridge/homebridge.

How it compares

No paid products are listed for this entry, so the meaningful comparison is with the software it packages. The upstream Homebridge project is the application this image distributes rather than replaces, and the community oznu/homebridge image it superseded is the distribution point it moved on from, which means existing configurations must update their image reference to homebridge/homebridge to keep receiving current releases.

When to use it — and when not to

A self-hoster must be able to run a container with host networking and a persistent volume, and must be willing to keep the plugins inside that volume updated; beyond the mounted Homebridge directory there is no database, SMTP service or external storage to operate. It should not be chosen by anyone running Docker Desktop for Mac or Windows, because the image does not work there due to networking limitations, and the beta and alpha tags are a poor fit for a household that expects an unattended bridge. Synology users and Homebridge 1.x holdouts also need specific tags rather than latest, which adds a small amount of maintenance discipline.

project readme (upstream, from github) — read inline

Homebridge Docker

Official Docker image for Homebridge - Emulate the iOS HomeKit API on your network

📢 Important Update

We have migrated the official Homebridge Docker image from oznu/homebridge to homebridge/homebridge.
Please update your configurations to use the new image location for the latest updates and features.

🚀 Quick Start

Prerequisites

Docker Engine with networking access
Host network mode support (required for HomeKit)

⚠️ Compatibility Note: This image does not work with Docker Desktop for Mac or Windows due to networking limitations (details).

📦 Available Images

This is a multi-architecture image supporting x86_64, ARM32v7 (Raspberry Pi), and ARM64v8 platforms. Images are available with Ubuntu 24.04 (default) and Ubuntu 22.04 (for Synology compatibility) base images.

Image Tag	Architectures	Base Image	Release Type	Description
`latest`, `ubuntu`	amd64, arm32v7, arm64v8	Ubuntu 24.04	Stable	Production-ready with latest stable releases
`legacy`	amd64, arm32v7, arm64v8	Ubuntu 24.04	Legacy	Production-ready with Homebridge 1.x stable releases
`synology`	amd64, arm32v7, arm64v8	Ubuntu 22.04	Stable	Production-ready with latest stable releases
`beta`	amd64, arm32v7, arm64v8	Ubuntu 24.04	Beta	Pre-release with beta versions for testing
`alpha`	amd64, arm32v7, arm64v8	Ubuntu 24.04	Alpha	Early access with alpha versions for development

🛠️ Installation

Using Docker Compose (Recommended)

Create a docker-compose.yml file:

services:
  homebridge:
    image: homebridge/homebridge:latest
    restart: always
    network_mode: host
    hostname: docker-desktop  # Optional: Set container hostname
    volumes:
      - ./volumes/homebridge:/homebridge
    environment:
      - TZ=America/Toronto  # Optional: Set your timezone
      - ENABLE_AVAHI=1      # Optional: Enable/disable Avahi (1=enabled, 0=disabled)
    logging:
      driver: json-file
      options:
        max-size: '10m'
        max-file: '1'
    healthcheck:
      test: ["CMD-SHELL", "curl --fail http://localhost:8581 || exit 1"]
      interval: 60s
      retries: 5
      start_period: 300s
      timeout: 2s

Start the container:

docker compose up -d

Using Docker CLI

docker run \
  --net=host \
  --name=homebridge \
  -e TZ=America/Toronto \
  -v $(pwd)/homebridge:/homebridge \
  homebridge/homebridge:latest

⚙️ Configuration

Required Parameters

Parameter	Docker Compose	Docker CLI	Description
Network Mode	`network_mode: host`	`--net=host`	Required - Enables host networking for HomeKit discovery
Volume Mount	`volumes:`	`-v /path:/homebridge`	Required - Persistent storage for config and plugins

Optional Parameters

Parameter	Docker Compose	Docker CLI	Default	Description
Hostname	`hostname: homebridge`	`--hostname=homebridge`	Container ID	Set custom hostname for the container
Timezone	`environment:` `- TZ=America/Toronto`	`-e TZ=America/Toronto`	`UTC`	Set timezone (list)
Avahi mDNS	`environment:` `- ENABLE_AVAHI=1`	`-e ENABLE_AVAHI=1`	`1`	Set to `0` to disable Avahi mDNS service

Note: When running with ENABLE_AVAHI=0, you can mount the host's mDNS service to enable mDNS usage in the container:
volumes:
  - ./volumes/homebridge:/homebridge
  - /var/run/dbus:/var/run/dbus  # Mount host D-Bus socket
  - /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket  # Mount host Avahi socket

🖥️ Homebridge UI

Access the Homebridge UI at http://:8581

The UI allows you to:

✅ Install, update, and remove plugins
✅ Edit Homebridge configuration
✅ View logs and restart Homebridge
✅ Manage accessories and bridges

Homebridge UI Screenshot

🔧 Custom Startup Script

For advanced customization, use the Startup Script feature in the UI (Settings → Startup & Environment).

Startup Script Settings

The startup.sh script:

Runs on every container start
Persists across container recreations
Can install packages, copy files, or execute custom commands

Example:

#!/bin/sh

# Install custom Node.js packages
npm install -g some-custom-package

# Install Python dependencies
pip3 install some-python-library

# Copy configuration from host
cp /homebridge/custom-config.json /etc/custom-config.json

Sample Startup Script

📚 Step-by-Step Guides

🔄 Updates

Manual Updates

Pull the latest image and recreate your container:

docker compose pull
docker compose up -d

Automated Updates

⚠️ Not Recommended: Automated updates using tools like Watchtower are strongly discouraged and done at your own risk

In-Container Updates

Since the 2025-06-25 release, updates to

Homebridge core
Homebridge UI
Node.js runtime

will be overwritten if the container is updated.

🎥 FFmpeg Support

This image includes FFmpeg with libfdk-aac audio support for camera streaming and video processing.

✅ Container Validation

This repository includes automated validation to ensure container builds work correctly.

Manual Validation

To validate a specific release:

Go to Actions
Select "Validate Docker Container"
Click "Run workflow"
Choose the release tag:
- latest - Stable release
- beta - Beta pre-release
- alpha - Alpha early release

The validation workflow will:

✅ Start the container and verify it runs
✅ Check Homebridge UI accessibility on port 8581
✅ Verify Homebridge service starts with version detection
✅ Validate container health checks
✅ Extract and validate the Docker manifest

🐛 Troubleshooting

1. FFmpeg Issues

FFmpeg with libfdk-aac audio support is included in this image. No additional installation required.

2. Container Won't Start on Older Raspbian

If you see errors like:

Node.js[445]: ../src/util.cc:188:double node::GetCurrentTimeInMicroseconds(): Assertion `(0) == (uv_gettimeofday(&tv))' failed.

s6-svscan: warning: unable to iopause: Operation not permitted

Your host OS needs to be updated. See #434 and #441 for solutions.

3. Get Help on Discord

Join the Official Homebridge Discord and ask in the #docker channel.

📄 License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Made with ❤️ by the Homebridge community

Frequently asked questions

Is docker-homebridge free to use?

docker-homebridge is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does docker-homebridge do?

Homebridge Docker. HomeKit support for the impatient using Docker on x86_64, Raspberry Pi (ARM64). Includes ffmpeg + libfdk-aac.

What is docker-homebridge written in?

docker-homebridge is primarily written in Shell. Its source is publicly available at https://github.com/homebridge/docker-homebridge, and it has 2,692 GitHub stars.