Portainer Templates logo

Portainer Templates

Homebridge - Debian Homebridge - Debian

Container

Homeautomation

Debian Homebridge allows you to integrate with smart home devices that do not natively support HomeKit. There are over 2,000 Homebridge plugins supporting thousands of different smart accessories.

Image details

Pulls: 13.0M
Architecture: amd64, arm64, arm/v7
Image size: 418 MB
User: homebridge
Created: Jun 05, 2023
Updated: 1 day ago
Status: active

Source details

Repo: homebridge/homebridge
Stars: 25.5k
Forks: 2k
Language: TypeScript
License: Apache-2.0
Latest: v2.3.1 · 5 days ago
Updated: 5 hours ago
Website: homebridge.io/

Configuration

Type
Container
Platform
linux
Image
homebridge/homebridge:ubuntu-arm32v7
Privileged
Yes
Volumes
/homebridge : /portainer/Files/AppData/Config/debian-homebridge
Env vars
PGID=1000PUID=1000HOMEBRIDGE_CONFIG_UI=1HOMEBRIDGE_CONFIG_UI_PORT=8581TZ=America/New_York
Restart
unless-stopped

Template by novaspirit

Notes

Template created by Pi-Hosted Series
Check our Github page: https://github.com/pi-hosted/pi-hosted

Official Webpage: https://homebridge.io/
Official Docker Documentation: https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker


Bringing HomeKit support where there is none

Standalone Install

Select an install method, to see config/commands for deploying Homebridge - Debian

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select Homebridge - Debian, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo

More install options in our documentation, or see homebridge/homebridge for app-specific guidance.

Donate Build and Push Docker Images Docker Pulls Discord

Homebridge Docker Image

This Ubuntu Linux based Docker image allows you to run Nfarina's Homebridge on your home network which emulates the iOS HomeKit API.
This is a multi-arch image and will run on x8664, Raspberry Pi 2, 3, 4, Zero 2 W, or other Docker-enabled ARMv7/8 devices. Docker will automatically pull the correct image for your system.
Image TagArchitecturesBase Image
latest, ubuntuamd64, arm32v7, arm64v8Ubuntu 24.04

Step-By-Step Guides

Compatibility

Homebridge requires full access to your local network to function correctly which can be achieved using the ``--net=host`` flag.
This image will not work when using Docker for Mac or Docker for Windows due to this and this.

Usage

Command Line:
docker run --net=host --name=homebridge -v $(pwd)/homebridge:/homebridge homebridge/homebridge:latest

Using Docker Compose (recommended):
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"

Parameters

The parameters are split into two halves, separated by a colon, the left hand side representing the host and the right the container side.
  • --net=host - Shares host networking with container, required
  • -v /homebridge - The Homebridge config and plugin location, required
Optional Settings:
  • -e TZ - for timezone information e.g. -e TZ=Australia/Canberra
  • -e ENABLE_AVAHI - default is 1; set to 0 to prevent the Avahi mDNS service running in the container

Homebridge UI

This image comes with the Homebridge UI pre-installed and is the easiest way to manage all aspects of Homebridge.
To manage Homebridge go to http://<ip of server>: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.

Automated Updates

Automated updates of the Homebridge Docker Image using tools such as Watchtower or similar are strongly discouraged and are done so at your own risk. You can update Homebridge, the Homebridge UI and the Node.js runtime from inside the container.

Troubleshooting

  1. Need ffmpeg?

ffmpeg, with libfdk-aac audio support is included in this image.

  1. Container will not start on older versions of Raspbian

If you're seeing errors like the following, your host operating system needs to be updated.
See #434 and #441 for potential solutions.
Node.js[445]: ../src/util.cc:188:double node::GetCurrentTimeInMicroseconds(): Assertion `(0) == (uv_gettimeofday(&tv))' failed.
Aborted (core dumped)

homebridge_1  | s6-svscan: warning: unable to iopause: Operation not permitted
homebridge_1  | s6-svscan: warning: executing into .s6-svscan/crash
homebridge_1  | s6-svscan crashed. Killing everything and exiting.

homebridge    | # Fatal error in , line 0
homebridge    | # unreachable code

  1. Ask on Discord

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

License

Copyright (C) 2023 homebridge Copyright (C) 2017-2022 oznu
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.

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs homebridge-debian
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Runs on the host network

This container shares your server's network directly, so port mappings are ignored and every port the app opens binds straight to the host.

  • If a port won't bind, find the clash with sudo ss -tlnp and stop the other service, or change the port in homebridge-debian's own settings.

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/debian-homebridge
  • Or set the PUID and PGID variables (defaults 1000:1000) to match your own user, found with id $USER

Image won't pull

Test the pull directly on the host: docker pull homebridge/homebridge:ubuntu-arm32v7

  • "manifest unknown" means the tag no longer exists.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64, arm/v7
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

  • Check the logs right after a restart, the last few lines before it died are the useful ones.
  • Get the exit code with docker inspect homebridge-debian --format '{{.State.ExitCode}}'
  • Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Privileged mode

This template runs the container in privileged mode, giving it full access to your host.

  • Only deploy it if you trust the app.
  • If deployment is blocked, your Portainer security settings or hardened host may not allow privileged containers.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A single container

Homebridge - Debian runs as one container, the simplest kind of app here. Just the one image to pull and nothing else wired up alongside it.

The app image

An image is the app packed up ready to go, everything Homebridge - Debian needs bundled into one download. This template pulls homebridge/homebridge:ubuntu-arm32v7, which Docker fetches once (about 418 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Homebridge - Debian's comes from Docker Hub, published by homebridge.

Version tags

The bit after the colon in the image name is the version tag. This one pins ubuntu-arm32v7, so every redeploy gives you that exact build until you bump it yourself.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, arm/v7, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Volumes

A volume is where Homebridge - Debian keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /homebridge from /portainer/Files/AppData/Config/debian-homebridge on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Homebridge - Debian takes 5 of them, all with defaults you can leave alone or tweak:

  • PGID, defaults to 1000
  • PUID, defaults to 1000
  • HOMEBRIDGE_CONFIG_UI, defaults to 1
  • HOMEBRIDGE_CONFIG_UI_PORT, defaults to 8581
  • TZ, defaults to America/New_York

Restart policy

The restart policy here is unless-stopped, so Docker restarts Homebridge - Debian after a crash or reboot, but leaves it off when you stop it on purpose. You can change this on the deploy screen. The choices are no (never restart), on-failure (only after a crash), unless-stopped (restart unless you stop it), and always (bring it back no matter what).

Users and permissions

The PUID and PGID settings tell it which user and group to act as on your host. Point them at your own account (find yours with id $USER) so the files it writes into your mounted folders come out owned by you rather than root.

Networking

Homebridge - Debian runs on the host network, so it shares your server's networking directly instead of getting a private one of its own. Its ports open straight on the server with no mapping in between.

Container name

Once it's deployed, Portainer names the container homebridge-debian. That's what you'll spot in the containers list and use in commands like docker logs homebridge-debian.

Privileged mode

This template runs Homebridge - Debian in privileged mode, which gives it nearly as much access to your server as the system itself. Some apps genuinely need it to reach hardware or manage the host, so it's one to run only if you trust the source.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

Homebridge - Debian is open source, released under the Apache-2.0 license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Homebridge - Debian up. Add the template list to Portainer once, then deploying Homebridge - Debian is a click rather than a wall of config.