Skip to content

Install Homebridge on Raspbian

oznu edited this page Oct 24, 2019 · 3 revisions

This guide provides step-by-step instructions to show you how to install Homebridge on Raspbian as a service so it will automatically start on boot.

Prerequisites

Before you get started, make sure you have the following ready:

  • A Raspberry Pi running a recent version of Raspbian OS.
  • Access to the Terminal. This can be via the Raspbian Desktop Terminal app, or remotely via SSH. You will need the ability to copy and paste commands from this guide into the terminal.
  • This guide is intended for a fresh install of Raspbian, at the very least you should ensure you do not already have Homebridge or Node.js installed on your system before getting started.

Installing Homebridge

Step 1: Assume Root

All the steps in this guide assume you are running as the root user.

sudo su

Step 2: Install Node.js and Homebridge

Install the LTS version of Node.js from the official repository, as well as additional dependencies:

curl -sL https://deb.nodesource.com/setup_12.x | bash -
apt-get install -y nodejs gcc g++ make python

# test node is working
node -v
Raspberry Pi 1 and Zero users click here for alternative Node.js installation instructions.

The installation of Node.js on arm32v6 devices such as the Raspberry Pi 1 and Raspberry Pi Zero is not supported by the official repository using the steps above. Instead use the following commands to install Node.js.

# update repos and install deps
apt-get update
apt-get install -y gcc g++ make python

# install node and npm
curl -Lsf "https://unofficial-builds.nodejs.org/download/release/v12.13.0/node-v12.13.0-linux-armv6l.tar.gz" | tar xzf - -C /usr/local --strip-components=1 --no-same-owner

# test node is working
node -v

Now install Homebridge:

npm install -g --unsafe-perm homebridge

If you want to be able to manage your Homebridge instance using a web based GUI, also install the Homebridge Config UI X plugin now:

npm install -g --unsafe-perm homebridge-config-ui-x

Step 3: Create Homebridge Service User

This is the user Homebridge will run under.

useradd -m --system homebridge

If you intended to run Homebridge Config UI X, the homebridge user you just created will require password-less sudo permissions to perform actions like installing plugins and restarting Homebridge, to safely update your /etc/sudoers file run this command once:

echo 'homebridge    ALL=(ALL) NOPASSWD: ALL' | sudo EDITOR='tee -a' visudo

Step 4: Create Homebridge Storage Directory

This is where Homebridge will store all it's config and cache. Other plugins may also use this directory to store persistent data.

mkdir -p /var/lib/homebridge

Step 5: Create Default config.json

Your Homebridge config.json file is located at /var/lib/homebridge. Please select one of the options below to create the initial config.json file on your system:

Click here to configure just Homebridge.

Use the following command to create the default config.json file:

Copy and paste this entire block into the terminal as one command, then press enter!

cat >/var/lib/homebridge/config.json <<EOL
{
    "bridge": {
        "name": "Homebridge",
        "username": "CB:22:3D:E2:CE:31",
        "port": 51826,
        "pin": "033-44-254"
    },
    "accessories": [],
    "platforms": []
}
EOL
Click here to configure Homebridge with Homebridge Config UI X support.

Use the following command to create the default config.json file:

Copy and paste this entire block into the terminal as one command, then press enter!

cat >/var/lib/homebridge/config.json <<EOL
{
    "bridge": {
        "name": "Homebridge",
        "username": "CB:22:3D:E2:CE:31",
        "port": 51826,
        "pin": "033-44-254"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8080,
            "auth": "form",
            "restart": "sudo -n systemctl restart homebridge",
            "sudo": true,
            "log": {
                "method": "systemd"
            },
            "platform": "config"
        }
    ]
}
EOL

Step 6: Create Systemd Service

Create Service File

Use the command below to create the required /etc/systemd/system/homebridge.service file:

Copy and paste this entire block into the terminal as one command, then press enter!
Do not use a text editor. This template includes variables that get populated by bash as the command is executed.

cat >/etc/systemd/system/homebridge.service <<EOL
[Unit]
Description=Homebridge
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=/etc/default/homebridge
ExecStart=$(which homebridge) \$HOMEBRIDGE_OPTS
Restart=on-failure
RestartSec=3
KillMode=process
CapabilityBoundingSet=CAP_IPC_LOCK CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SYS_CHROOT CAP_CHOWN CAP_FOWNER CAP_DAC_OVERRIDE CAP_AUDIT_WRITE CAP_SYS_ADMIN
AmbientCapabilities=CAP_NET_RAW

[Install]
WantedBy=multi-user.target
EOL

Create Environment File

Use the command below to create the required /etc/default/homebridge file:

Copy and paste this entire block into the terminal as one command!
Do not use a text editor. This template includes variables that get populated by bash as the command is executed.

cat >/etc/default/homebridge <<EOL
# Defaults / Configuration options for homebridge
# The following settings tells homebridge where to find the config.json file and where to persist the data (i.e. pairing and others)
HOMEBRIDGE_OPTS=-U /var/lib/homebridge -I

# If you uncomment the following line, homebridge will log more
# You can display this via systemd's journalctl: journalctl -f -u homebridge
# DEBUG=*

# To enable web terminals via homebridge-config-ui-x uncomment the following line
# HOMEBRIDGE_CONFIG_UI_TERMINAL=1
EOL

Step 7: Fix Permissions

Ensure the homebridge user can access the storage directory:

chown -R homebridge: /var/lib/homebridge

Step 8: Reload Systemd and Start Homebridge

This will ensure Homebridge starts on boot:

systemctl daemon-reload
systemctl enable homebridge
systemctl start homebridge

Manage and Configure Homebridge

Using the command line

To view your pairing QR code, you'll need to view the logs. To do this run this command:

sudo journalctl -f -n 200 -u homebridge

To edit your config.json file you can use the nano text editor:

sudo nano /var/lib/homebridge/config.json

After making any changes to your config.json you need to restart Homebridge:

systemctl restart homebridge

With the Homebridge Config UI X plugin

The Homebridge Config UI X will allow you to install, remove and update plugins, modify the Homebridge config.json and restart Homebridge, and view the logs right from your web browser.

If you chose to install Homebridge Config UI X, go to http://<ip of raspberry pi>:8080 in your browser.

For example, http://192.168.1.20:8080. The default username is admin with password admin.

To find the IP address of your Raspberry Pi you can run:

hostname -I

Major Node.js Version Updates

This guide provides instructions on how to install the current stable LTS version of Node.js. Should you need to upgrade to the next LTS in the future repeat the commands in Step 2 (this guide will be updated for each LTS).

After doing a major update to Node.js you may need to rebuild certain plugins:

cd $(npm -g prefix)/lib/node_modules
npm rebuild

Configuration Reference

This table contains important information about your setup. You can use the information provided here as a reference when configuring or troubleshooting your environment after setting up Homebridge using the instructions below.

File Location / Command
Config File Path /var/lib/homebridge/config.json
Storage Path /var/lib/homebridge
Restart Command systemctl restart homebridge
Stop Command systemctl stop homebridge
Start Command systemctl start homebridge
View Logs Command journalctl -f -n 100 -u homebridge
You can’t perform that action at this time.