Set up Homebridge with Docker or Docker Compose on Linux, Synology NAS, or Unraid. Covers host networking, permissions, and troubleshooting.

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.

Still deciding on your hardware?

Compare Raspberry Pi, Docker on a NAS, and a Mac in our hardware guide.

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

mDNS limitation with Docker Desktop (macOS & Windows):
Docker Desktop on macOS and Windows runs containers inside a virtual Linux machine. This virtualization layer prevents host network mode (network_mode: host) from passing multicast mDNS traffic (Bonjour over UDP port 5353) to your physical network. Apple Home will not find the bridge and will display “No Response” (documented in Docker Desktop issue #570).

Run Docker on bare-metal Linux (Debian, Ubuntu, Raspberry Pi OS), a NAS (Synology, QNAP), or Unraid / Proxmox. For macOS, follow our native macOS installation guide. For Windows, use the Windows background service guide.

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.

Note on image naming: The official image migrated from oznu/homebridge to homebridge/homebridge on Docker Hub. Use homebridge/homebridge for all new setups and updates.

Method 1: Docker Compose

Docker Compose is the easiest way to manage container configurations long term.

Create a project folder

Create a folder for Homebridge on your server:

mkdir -p ~/homebridge
cd ~/homebridge

Create `docker-compose.yml`

Save the following configuration as docker-compose.yml:

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

Configuration details:

network_mode: host: Connects the container directly to the host network (required for HomeKit).
volumes: Maps the host folder ./data to /homebridge inside the container.
TZ: Sets the time zone for automations and log output.
PUID & PGID: Matches your Linux user account IDs (find yours with id). This prevents file permission issues in the mounted folder.
HOMEBRIDGE_CONFIG_UI_PORT: Web port for the dashboard and the Homemanager API (default: 8581).

Start the container

Launch the container in the background:

docker compose up -d

Docker downloads the image and starts Homebridge. The server becomes accessible within a few seconds.

Method 2: Quick start with `docker run`

To start Homebridge directly from the terminal without a Compose file, run:

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

Method 3: Portainer Stack

If you manage your containers through Portainer:

Open Portainer in your browser and choose your environment.
Go to Stacks in the sidebar and click Add stack.
Name the stack homebridge.

Select the Web editor and paste:

version: '3.8'
services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    volumes:
      - /var/lib/homebridge:/homebridge
    environment:
      - TZ=Europe/Berlin
      - PUID=1000
      - PGID=1000
      - HOMEBRIDGE_CONFIG_UI_PORT=8581

(Adjust /var/lib/homebridge to match your host storage path).

Click Deploy the stack.

Configuration on NAS and server platforms

Synology Plus series models with Intel or AMD processors (like DS224+, DS720+, DS920+, DS1522+) support Compose stacks inside DSM 7.2 Container Manager.

If you own a j-series or Play-series DiskStation without Docker support, or prefer running without containers, use the native SPK package instead. Follow our Synology NAS guide.

Open File Station and create a folder named homebridge inside your shared docker folder.
Open Container Manager and select Project on the left.

Click Create:

Project Name: homebridge
Path: Select /docker/homebridge.

Source: Choose Create docker-compose.yaml and paste:

services:
  homebridge:
    image: homebridge/homebridge:latest
    container_name: homebridge
    restart: unless-stopped
    network_mode: host
    volumes:
      - /volume1/docker/homebridge:/homebridge
    environment:
      - TZ=Europe/Berlin
      - HOMEBRIDGE_CONFIG_UI_PORT=8581

Click Next to finish. DSM downloads the image and boots the container.

On Unraid, install Homebridge via Community Applications (see also the official Homebridge Unraid wiki guide):

Open the Apps tab in the Unraid web interface.
Search for Homebridge and select the official template.
Confirm two key settings:
- Network Type: Must be set to Host (for mDNS).
- AppData Storage: Point /mnt/user/appdata/homebridge to /homebridge.
Click Apply.

On QTS or QuTS hero, use QNAP Container Station (see the official QNAP wiki guide):

Open Container Station and navigate to Applications (or Create).
Create an application called homebridge.
Paste the Compose YAML and verify that network_mode: host is set.
Map a volume from your storage pool (such as /share/Container/homebridge:/homebridge).
Click Create to launch the container.

Proxmox VE: Run Docker inside an unprivileged LXC container (Debian or Alpine) with nesting enabled, or use a minimal VM.
TrueNAS SCALE: Use the app catalog or launch a custom Compose app with host networking and a persistent dataset for /homebridge (read the TrueNAS SCALE wiki guide).

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:

Setup with Homemanager

Homemanager lets you manage instances on iPhone and iPad, monitor live logs, and configure plugins.

Discover the server

Open Homemanager while connected to the same Wi-Fi network as the host server. Tap Connect to Server during initial launch (or Add Platform in the platform list). With host networking enabled, the app finds the instance automatically using mDNS and Bonjour.

Select the instance

Choose the detected server from the list. It shows the Homebridge icon and port 8581.

Create an administrator account

Homemanager detects the new server and opens the Create new User screen. Enter a display name, username (such as admin), and password, then tap Create and Log In.

The account is created directly on the server, credentials are saved securely in your iOS Keychain, and Homemanager connects immediately.

Discovery issues or running Docker on a remote server? Refer to Connecting Servers to Homemanager for manual IP and port configuration and network troubleshooting.

Setup in the Web Browser

To configure the server from a computer, open the interface in a desktop browser.

Open the URL

Navigate to the web interface in your browser:

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

(Example: http://192.168.178.50:8581 or http://homebridge.local:8581).

Create an account or restore a backup

Enter a username and password for the admin account. If migrating from an earlier setup, you can restore a backup archive here instead.

After signing in, the dashboard displays the HomeKit pairing code.

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

If you have the web interface or Homemanager open, you can run hb-service commands directly in the built-in terminal without the docker exec -it homebridge prefix.

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

In container setups, discovery problems usually trace back to mDNS:

Check network mode: Make sure the container runs with network_mode: host. Standard Docker bridge networks block mDNS discovery packets.
Avahi daemon conflict: If your Linux host already runs avahi-daemon, it can collide on port 5353. In Homebridge under Advanced Settings, change the mDNS advertiser from Bonjour HAP to Ciao. Alternatively, pass ENABLE_AVAHI=0 to the container and mount your host's D-Bus and Avahi sockets:
```
volumes:
  - ./data:/homebridge
  - /var/run/dbus:/var/run/dbus
  - /var/run/avahi-daemon/socket:/var/run/avahi-daemon/socket
environment:
  - ENABLE_AVAHI=0
```
Guest Wi-Fi isolation: Your iPhone or iPad and your server must be on the same local subnet. Guest networks isolate clients, preventing discovery.

In host network mode, Homebridge shares ports with the host. If another service already listens on 8581, the web UI fails to start.

Change the UI port in docker-compose.yml:

environment:
  - HOMEBRIDGE_CONFIG_UI_PORT=8585

Access the dashboard at http://<your-server-ip>:8585.

If the log shows EACCES: permission denied, the container process lacks write permissions for the mapped folder.

Check your user and group IDs on the host:
```
id
```
Enter those numbers as PUID and PGID in your Compose file.

Update ownership of the data folder:

sudo chown -R 1000:1000 ~/homebridge/data

Reset the credentials from the host terminal:

docker exec -it homebridge hb-service reset-admin

This resets the login to admin / admin. Log in immediately to set a new password.

Next steps

Once Homebridge is running in Docker:

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
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
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

Last updated on

Installing Homebridge with Docker

Still deciding on your hardware?

Why run Homebridge in Docker?

Limitation: Docker Desktop on macOS and Windows

Requirements for container setups

1. Host network mode (`network_mode: host`)

2. Persistent storage (`/homebridge`)

Installation & deployment

Method 1: Docker Compose

Create a project folder

Create `docker-compose.yml`

Start the container

Method 2: Quick start with `docker run`

Method 3: Portainer Stack

Configuration on NAS and server platforms

Connecting and Initial Setup

Setup with Homemanager

Discover the server

Select the instance

Create an administrator account

Setup in the Web Browser

Open the URL

Create an account or restore a backup

Maintenance & commands

1. Updating plugins and Homebridge Core

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

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

4. Installing extra system packages (`PACKAGES`)

Troubleshooting common issues

Next steps

Reference links

On this page

Installing Homebridge with Docker

Still deciding on your hardware?

Synology DiskStation (DSM 7.2 Container Manager)

Unraid

QNAP NAS (Container Station)

Proxmox VE or TrueNAS SCALE

Apple Home cannot find the bridge or shows “No Response”

Port conflict: Port 8581 is already in use

Permission denied in data folder (EACCES)

Forgotten password for Web UI or Homemanager

On this page