in IT on Linux, Homekit 2023-12-31
Setting up Multiple Homebridge Instances

This guide, adapted from oznu’s Homebridge Config UI X Wiki, will show you how to set up multiple instances of Homebridge and Homebridge Config UI X using systemd on a Raspberry Pi. This guide assumes you already have a Pi set up and running a recent version of Raspbian.

Multiple instance support is now depreciated (since Homebridge v1.3.0 or later), use Child Bridges instead.

Homebridge now supports Child Bridges which are an easier to manage alternative to running multiple instances. This feature allows any Homebridge platform or accessory to optionally run as its own independent accessory, separate from the main bridge, and in an isolated process.

Step 1: Assume root

1
sudo su -

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

Step 2: Install Node.js and Other Dependencies

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

1
2
3
4
5
curl -sL https://deb.nodesource.com/setup_14.x | bash -
apt-get install -y nodejs gcc g++ make python libavahi-compat-libdnssd-dev

# test that node is working
node -v

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.

1
2
3
4
5
6
7
8
9
# update repos and install deps
apt-get update
apt-get install -y gcc g++ make python libavahi-compat-libdnssd-dev

# install node and npm
curl -Lsf "https://nodejs.org/dist/v10.15.3/node-v10.15.3-linux-armv6l.tar.gz" | tar xzf - -C /usr/local --strip-components=1 --no-same-owner

# test that node is working
node -v

Step 3: Install Homebridge and Config UI X

Now install Homebridge and Homebridge Config UI X:

1
npm install -g --unsafe-perm homebridge@latest homebridge-config-ui-x@latest

Step 4: Create User for Homebridge Service

This is the user Homebridge will run under.

1
useradd -m --system homebridge

This user will require password-less sudo permissions. To safely update your /etc/sudoers file, run this command:

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

Step 5: Create Storage Directory for Homebridge

This is where Homebridge will store its configuration and cache. Other plugins may also use this directory to store persistent data.

1
mkdir -p /var/lib/homebridge@1

For more than one instance of Homebridge, create additional directories as needed:

1
2
mkdir -p /var/lib/homebridge@2
mkdir -p /var/lib/homebridge@3

Step 6: Create Default config.json

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

Copy and paste this entire block into the terminal as one command!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
cat > /var/lib/homebridge@1/config.json << EOL
{
    "bridge": {
        "name": "Homebridge@1",
        "username": "CB:22:3D:E2:CE:31",
        "port": 51826,
        "pin": "033-44-254"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8080,
            "auth": "form",
            "theme": "purple",
            "temp": "/sys/class/thermal/thermal_zone0/temp",
            "tempUnits": "f",
            "sudo": true,
            "standalone": true,
            "restart": "sudo -n systemctl restart homebridge@1",
            "log": {
                "method": "systemd",
                "service": "homebridge@1"
            },
            "platform": "config"
        }
    ]
}
EOL

For more than one instance of Homebridge, copy this config.json to /var/lib/homebridge@2/config.json, /var/lib/homebridge@3/config.json, etc.

Important: For each of these, you must change some values to be different:

  • Under "bridge":
    • "name"
    • "username"
    • "port"
    • "pin"
  • Under the "Config" platform:
    • "port" (e.g., 8081)
    • "restart" (e.g., "sudo -n systemctl restart homebridge@2")
    • Under "log":
      • "service" (e.g., "homebridge@2")

Example configuration file for 2nd instance of Homebridge.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
cat > /var/lib/homebridge@2/config.json << EOL
{
    "bridge": {
        "name": "Homebridge@2",
        "username": "CB:22:3D:E2:CE:32",
        "port": 51827,
        "pin": "033-44-255"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8081,
            "auth": "form",
            "theme": "teal",
            "temp": "/sys/class/thermal/thermal_zone0/temp",
            "tempUnits": "f",
            "sudo": true,
            "standalone": true,
            "restart": "sudo -n systemctl restart homebridge@2",
            "log": {
                "method": "systemd",
                "service": "homebridge@2"
            },
            "platform": "config"
        }
    ]
}
EOL

Example configuration file for 3rd instance of Homebridge.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
cat > /var/lib/homebridge@3/config.json << EOL
{
    "bridge": {
        "name": "Homebridge@3",
        "username": "CB:22:3D:E2:CE:33",
        "port": 51828,
        "pin": "033-44-256"
    },
    "accessories": [],
    "platforms": [
        {
            "name": "Config",
            "port": 8082,
            "auth": "form",
            "theme": "orange",
            "temp": "/sys/class/thermal/thermal_zone0/temp",
            "tempUnits": "f",
            "sudo": true,
            "standalone": true,
            "restart": "sudo -n systemctl restart homebridge@3",
            "log": {
                "method": "systemd",
                "service": "homebridge@3"
            },
            "platform": "config"
        }
    ]
}
EOL

Step 7: Create systemd Service Templates

Use the following command to create the systemd service template homebridge@.service:

Copy and paste this entire block into the terminal as one command!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
cat > /etc/systemd/system/homebridge@.service << EOL
[Unit]
Description=Homebridge @ %i
Wants=homebridge-config-ui-x@%i.service
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=-/etc/default/homebridge
EnvironmentFile=-/etc/default/homebridge@%i
ExecStartPre=+/bin/bash -c 'mkdir -p /var/lib/homebridge@%i; chown -R homebridge: /var/lib/homebridge@%i'
ExecStart=$(which homebridge) -U /var/lib/homebridge@%i \$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
DefaultInstance=1
EOL

Use the following command to create the systemd service template homebridge-config-ui-x@.service:

Copy and paste this entire block into the terminal as one command!

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
cat > /etc/systemd/system/homebridge-config-ui-x@.service << EOL
[Unit]
Description=Homebridge Config UI X @ %i
Wants=homebridge@%i.service
After=syslog.target network-online.target

[Service]
Type=simple
User=homebridge
EnvironmentFile=-/etc/default/homebridge
EnvironmentFile=-/etc/default/homebridge@%i
ExecStartPre=+/bin/bash -c 'mkdir -p /var/lib/homebridge@%i; chown -R homebridge: /var/lib/homebridge@%i'
ExecStart=$(which homebridge-config-ui-x) -U /var/lib/homebridge@%i \$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
DefaultInstance=1
EOL

Use the following command to create the service defaults file:

Copy and paste this entire block into the terminal as one command!

1
2
3
4
5
6
7
8
9
10
cat > /etc/default/homebridge << EOL
# Defaults / configuration options for Homebridge

# If you uncomment the following line, Homebridge will log more.
# You can display this via systemd's journalctl: journalctl -f -u homebridge@1 (or homebridge@2, etc.)
# DEBUG=*

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

Optional: You may create additional default files customized to each instance of Homebridge. First, copy /etc/defaults/homebridge into /etc/defaults/homebridge@1, /etc/defaults/homebridge@2, etc., and then edit them to suit your needs. This is useful, for example, to enable debug logging for a certain instance.

Step 8: Activate the New Services

This will ensure Homebridge starts on boot:

1
2
3
systemctl daemon-reload
systemctl enable homebridge@1
systemctl start homebridge@1

If you are creating multiple instances, list them alongside the first.

  • Example of activating 2 Homebridge instances.
1
2
3
systemctl daemon-reload
systemctl enable homebridge@1 homebridge@2
systemctl start homebridge@1 homebridge@2
  • Example of activating 3 Homebridge instances.
1
2
3
systemctl daemon-reload
systemctl enable homebridge@1 homebridge@2 homebridge@3
systemctl start homebridge@1 homebridge@2 homebridge@3

Step 9: Manage and Configure Homebridge

To manage Homebridge, go to http://<ip of server>:<port of instance> in your browser. For example, go to [http://192.168.1.20:8080](http://192.168.1.20:8080/), [http://192.168.1.20:8081](http://192.168.1.20:8081/), etc., depending on which instance you want to manage. From here you can install, remove, and update plugins; modify the Homebridge config.json; and restart Homebridge.

The default username is admin with password admin. Remember you will need to restart Homebridge to apply any changes you make to the config.json.

The Homebridge logs can be viewed using the web interface, but if you need to view them via the terminal, run this:

1
sudo journalctl -f -u homebridge@1

To view the logs of other instances, just change the index:

1
sudo journalctl -f -u homebridge@2