# Installing Homebridge with Docker (https://docs.homemanager-app.de/guide/install-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.

<Cards>
  <Card icon="<HelpCircle />" title="Still deciding on your hardware?" description="Compare Raspberry Pi, Docker on a NAS, and a Mac in our hardware guide." href="/guide/choose-your-system" />
</Cards>

***

## Why run Homebridge in Docker? [#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 [#limitation-docker-desktop-on-macos-and-windows]

<Callout type="warn">
  **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&#x60;) from passing multicast mDNS traffic (Bonjour over UDP port 5353) to your physical network. Apple Home will not find the bridge and will display &#x2A;“No Response”* (documented in [Docker Desktop issue #570](https://github.com/homebridge/docker-homebridge/issues/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](/guide/install-macos). For Windows, use the [Windows background service guide](/guide/install-windows).
</Callout>

***

## Requirements for container setups [#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`) [#1-host-network-mode-network_mode-host]

Docker normally isolates containers in an internal bridge network. Apple HomeKit relies on &#x2A;*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`) [#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 [#installation--deployment]

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

<Callout type="info">
  **Note on image naming:** The official image migrated from `oznu/homebridge&#x60; to &#x2A;*`homebridge/homebridge`** on [Docker Hub](https://hub.docker.com/r/homebridge/homebridge). Use `homebridge/homebridge` for all new setups and updates.
</Callout>

<Tabs items="[&#x22;Docker Compose (Recommended)&#x22;, &#x22;Docker Run (CLI)&#x22;, &#x22;Portainer Stack&#x22;]">
  <Tab>
    ### Method 1: Docker Compose [#method-1-docker-compose]

    [Docker Compose](https://docs.docker.com/compose/) is the easiest way to manage container configurations long term.

    <Steps>
      <Step>
        #### Create a project folder [#create-a-project-folder]

        Create a folder for Homebridge on your server:

        ```bash
        mkdir -p ~/homebridge
        cd ~/homebridge
        ```
      </Step>

      <Step>
        #### Create `docker-compose.yml` [#create-docker-composeyml]

        Save the following configuration as `docker-compose.yml`:

        ```yaml
        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).
      </Step>

      <Step>
        #### Start the container [#start-the-container]

        Launch the container in the background:

        ```bash
        docker compose up -d
        ```

        Docker downloads the image and starts Homebridge. The server becomes accessible within a few seconds.
      </Step>
    </Steps>
  </Tab>

  <Tab>
    ### Method 2: Quick start with `docker run` [#method-2-quick-start-with-docker-run]

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

    ```bash
    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
    ```
  </Tab>

  <Tab>
    ### Method 3: Portainer Stack [#method-3-portainer-stack]

    If you manage your containers through [Portainer](https://www.portainer.io/):

    1. Open Portainer in your browser and choose your environment.
    2. Go to **Stacks** in the sidebar and click **Add stack**.
    3. Name the stack `homebridge`.
    4. Select the **Web editor** and paste:
       ```yaml
       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).*
    5. Click **Deploy the stack**.
  </Tab>
</Tabs>

***

## Configuration on NAS and server platforms [#configuration-on-nas-and-server-platforms]

<Accordions>
  <Accordion title="Synology DiskStation (DSM 7.2 Container Manager)">
    Synology Plus series models with Intel or AMD processors (like DS224+, DS720+, DS920+, DS1522+) support Compose stacks inside DSM 7.2 **Container Manager**.

    <Callout type="info">
      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](/guide/install-synology).
    </Callout>

    1. Open **File Station** and create a folder named `homebridge` inside your shared `docker` folder.
    2. Open **Container Manager** and select **Project** on the left.
    3. Click **Create**:
       * **Project Name:** `homebridge`
       * **Path:** Select `/docker/homebridge`.
       * **Source:** Choose *Create docker-compose.yaml* and paste:
         ```yaml
         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
         ```
    4. Click **Next** to finish. DSM downloads the image and boots the container.
  </Accordion>

  <Accordion title="Unraid">
    On Unraid, install Homebridge via [Community Applications](https://unraid.net/community/apps) (see also the [official Homebridge Unraid wiki guide](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-Unraid)):

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

  <Accordion title="QNAP NAS (Container Station)">
    On QTS or QuTS hero, use [QNAP Container Station](https://www.qnap.com/en/software/container-station) (see the [official QNAP wiki guide](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-QNAP)):

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

  <Accordion title="Proxmox VE or TrueNAS SCALE">
    * **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](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-TrueNAS-Scale)).
  </Accordion>
</Accordions>

***

## Connecting and Initial Setup [#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:

<Tabs items="[&#x22;Homemanager (iOS & iPadOS)&#x22;, &#x22;Homebridge Web Interface&#x22;]">
  <Tab>
    ### Setup with Homemanager [#setup-with-homemanager]

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

    <Steps>
      <Step>
        #### Discover the server [#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.
      </Step>

      <Step>
        #### Select the instance [#select-the-instance]

        Choose the detected server from the list. It shows the Homebridge icon and port `8581`.
      </Step>

      <Step>
        #### Create an administrator account [#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**.
      </Step>
    </Steps>

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

    <Callout type="info">
      Discovery issues or running Docker on a remote server? Refer to [Connecting Servers to Homemanager](/guide/connecting-servers) for manual IP and port configuration and network troubleshooting.
    </Callout>
  </Tab>

  <Tab>
    ### Setup in the Web Browser [#setup-in-the-web-browser]

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

    <Steps>
      <Step>
        #### Open the URL [#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`).*
      </Step>

      <Step>
        #### Create an account or restore a backup [#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.
      </Step>
    </Steps>

    After signing in, the dashboard displays the HomeKit pairing code.
  </Tab>
</Tabs>

***

## Maintenance & commands [#maintenance--commands]

Updates in Docker happen at two different levels:

### 1. Updating plugins and Homebridge Core [#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) [#2-updating-the-docker-base-image-nodejs--os]

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

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

### 3. Useful commands in the terminal, app & web UI [#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`.

```bash
# 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
```

<Callout type="tip">
  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.
</Callout>

### 4. Installing extra system packages (`PACKAGES`) [#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`:

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

***

## Troubleshooting common issues [#troubleshooting-common-issues]

<Accordions>
  <Accordion title="Apple Home cannot find the bridge or shows “No Response”">
    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:
      ```yaml
      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.
  </Accordion>

  <Accordion title="Port conflict: Port 8581 is already in use">
    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`:

    ```yaml
    environment:
      - HOMEBRIDGE_CONFIG_UI_PORT=8585
    ```

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

  <Accordion title="Permission denied in data folder (EACCES)">
    If the log shows `EACCES: permission denied`, the container process lacks write permissions for the mapped folder.

    1. Check your user and group IDs on the host:
       ```bash
       id
       ```
    2. Enter those numbers as `PUID` and `PGID` in your Compose file.
    3. Update ownership of the data folder:
       ```bash
       sudo chown -R 1000:1000 ~/homebridge/data
       ```
  </Accordion>

  <Accordion title="Forgotten password for Web UI or Homemanager">
    Reset the credentials from the host terminal:

    ```bash
    docker exec -it homebridge hb-service reset-admin
    ```

    This resets the login to `admin` / `admin`. Log in immediately to set a new password.
  </Accordion>
</Accordions>

***

## Next steps [#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](/guide/pairing-apple-home)

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](/guide/finding-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](/guide/child-bridges)

***

## Reference links [#reference-links]

* [How to Install Homebridge: All Methods](/guide/install-homebridge)
* [Official Homebridge Wiki: Install Homebridge on Docker](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker)
* [Official Docker Image Repository (homebridge/homebridge)](https://github.com/homebridge/docker-homebridge)
* [Homebridge Docker Image on Docker Hub](https://hub.docker.com/r/homebridge/homebridge)
* [Homebridge on Unraid (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-Unraid)
* [Homebridge on QNAP Container Station (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-QNAP)
* [Homebridge on TrueNAS SCALE (Wiki)](https://github.com/homebridge/docker-homebridge/wiki/Homebridge-on-TrueNAS-Scale)
* [Official Homebridge Discord Server (#docker channel)](https://discord.gg/Cmq8a44)
* [Docker Documentation: Host networking driver](https://docs.docker.com/engine/network/drivers/host/)