Homebridge on Raspberry Pi

How to setup Homebridge & Docker on a Raspberry Pi

This guide will show you how to run the homebridge/homebridge docker image on a Raspberry Pi.

• Requirements
• Initial Raspberry Pi Setup
• Quick Install
• Manual Install
  • Step 1: Install Docker
  • Step 2: Install Docker Compose
  • Step 3: Create Docker Compose Manifest
  • Step 4: Start Homebridge
• Managing Homebridge
• Connect iOS / HomeKit
• Updating Homebridge / Node.js
• Shell Access

Requirements

💡 Homebridge also provides a Raspberry Pi Image built on Raspbian Lite. If you're just starting out, this is the best option.

If you are going to use plugins that require access to the Raspberry Pi's GPIO or Bluetooth radio, or require hardware video decoding, you should be aware using Docker to run Homebridge may add an additional layer of complexity to your setup. If this is the case may wish to consider Setting up Homebridge natively instead instead.

• Raspberry Pi Zero 2 W
• Raspberry Pi 2
• Raspberry Pi 3
• Raspberry Pi 4

Quick Install

The quick install script will install Docker, Docker Compose, setup the docker-compose.yml file and start the docker container for you.

Script Source

To run the quick install script:

curl https://raw.githubusercontent.com/homebridge/docker-homebridge/master/raspbian-installer.sh?v=2022-06-15 -o get-homebridge.sh
chmod u+x get-homebridge.sh
./get-homebridge.sh

Once installed see Managing Homebridge.

If you don't want to use the quick install script, you can manually run the steps below.

Manual Install

1. Install Docker

sudo apt-get update
sudo apt-get -y install docker.io docker-compose

3. Create Docker Compose Manifest

Create a new directory to store your homebridge docker-compose manifest and config data in. In this example we will install Homebridge in the pi user's home directory.

Create a new directory and change into it:

mkdir /home/pi/homebridge
cd /home/pi/homebridge

Create a new file called docker-compose.yml using nano:

nano docker-compose.yml

The contents of this file should be:

version: '2'
services:
  homebridge:
    image: homebridge/homebridge:latest
    restart: always
    network_mode: host
    volumes:
      - ./volumes/homebridge:/homebridge
    logging:
      driver: json-file
      options:
        max-size: "10mb"
        max-file: "1"

• The restart: always line instructs docker to setup the container so that it that will automatically start again if the Raspberry Pi is rebooted, or if the container unexpectedly quits or crashes.
• The network_mode: host line instructs docker to share the Raspberry Pi's network with the container, allowing your iOS device to find the Homebridge accessory.
• The ./config:/homebridge instructs docker to share the local folder config with the container. This will allow you to recreate or update the docker container without losing any Homekit settings or Homebridge plugins.

Save and close the file by pressing CTRL+X.

4. Start Homebridge

Start the Homebridge Docker container by running:

docker-compose up -d

• It might take some time to download and start the initial image.
• Docker will now download the latest homebridge/homebridge docker image.
• The -d flag tells docker-compose to run the container as a background process.

You'll probably want to view the Homebridge logs to check everything is working

docker-compose logs -f

Your Homebridge config.json, plugins and all HomeKit data will be stored in the newly created config directory.

Managing Homebridge

To manage Homebridge go to http://<ip of raspberry pi>:8581 in your browser. For example, http://192.168.1.20:8581. From here you can install, remove and update plugins, modify the Homebridge config.json and restart Homebridge.

You can restart the container by running:

docker-compose restart homebridge

Connect iOS / HomeKit

You should now be able to see the Homebridge as a new HomeKit accessory in the Apple iOS Home App. You can pair the device using the QR code displayed in the logs (see above) or in browser using the Homebridge UI.

1. Open the Home app on your device.
2. Tap the Home tab, then tap .
3. Tap Add Accessory, then scan the QR code shown in the Homebridge UI or your Homebridge logs.

If the QR code is not displaying correctly and you're using using iOS 11 you will need to follow these steps:

1. Open the Home app on your device.
2. Tap the Home tab, then tap .
3. Tap Add Accessory, and select I Don't Have a Code or Cannot Scan.
4. Enter the Homebridge PIN, this can be found under the QR code in Homebridge UI or your Homebridge logs.

Updating Homebridge / Node.js

To update Homebridge or Node.js to the latest version you just need to pull the latest version of homebridge/homebridge.

Go to the directory containing your docker-compose.yml file:

cd /home/pi/homebridge

Download the latest homebridge/homebridge image:

docker-compose pull homebridge

If a newer version of the image was downloaded, upgrade the container using the new image by running the up command again:

docker-compose up -d

Shell Access

If you require shell access to the container you can run:

docker-compose exec homebridge sh