https://github.com/NRCHKB/node-red-contrib-homekit-docker
Node-RED-homekit-docker is a Node-RED based project with support for homekit.
https://github.com/NRCHKB/node-red-contrib-homekit-docker
docker node-red nrchkb raspberry-pi raspberrypi
Last synced: 13 days ago
JSON representation
Node-RED-homekit-docker is a Node-RED based project with support for homekit.
- Host: GitHub
- URL: https://github.com/NRCHKB/node-red-contrib-homekit-docker
- Owner: NRCHKB
- License: apache-2.0
- Created: 2020-07-11T09:01:59.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2026-05-07T02:57:21.000Z (22 days ago)
- Last Synced: 2026-05-07T03:27:30.884Z (22 days ago)
- Topics: docker, node-red, nrchkb, raspberry-pi, raspberrypi
- Language: JavaScript
- Homepage: https://nrchkb.github.io
- Size: 992 KB
- Stars: 42
- Watchers: 1
- Forks: 8
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-projects - node-red-contrib-homekit-docker - Node-RED-homekit-docker is a Node-RED based project with support for homekit. ⭐42 `JavaScript` 🔥 (🚀 DevOps & Infrastructure)
README
git p# Node-RED-homekit-docker
[](https://github.com/NRCHKB/node-red-contrib-homekit-docker/actions/workflows/docker-build.yml)
[](https://hub.docker.com/r/nrchkb/node-red-homekit)
[](https://hub.docker.com/r/nrchkb/node-red-homekit)
Node-RED-homekit-docker is a Node-RED based project with support for homekit. It is based on
the [official Node-RED Docker](https://hub.docker.com/r/nodered/node-red) images with the necessary tools and npm
module [node-red-contrib-homekit-bridged](https://www.npmjs.com/package/node-red-contrib-homekit-bridged) installed to
run homekit within a docker container.
## Architecture
Node-RED-homekit-docker is supported by a manifest list, which means one doesn't need to specify the tag for a specific
architecture. Using the image without any tag or the latest tag will pull the right image for the architecture
required.
Currently, Node-RED-homekit images are published as a multi-arch manifest supporting the following architectures:
- `amd64` – Alpine based (most PCs/servers: x64, x86-64, x86_64)
- `arm32v7` – Alpine based (Raspberry Pi 2/3/4)
- `arm64v8` – Alpine based (64-bit ARM boards like Raspberry Pi 3/4 64-bit OS, Pine64, etc.)
Notes:
- The dedicated Raspbian variant (`*-raspbian` tags) is built for `arm32v7` only.
- We no longer build or publish `arm32v6` images because upstream Node-RED images no longer provide this architecture
for current tags.
**Note**: As of the Node-RED 4.0.0 release, we are no longer building docker images for previous versions. At the same
time,
images with NodeJS up to 18 (excluded) are dropped. The next major NRCHKB release will require NodeJS >= 22.
#### Verify the published architecture
You can verify the architectures available for a given tag using Docker Buildx:
```bash
docker buildx imagetools inspect nrchkb/node-red-homekit:latest
# or a specific tag, e.g. Node/variant tagged image
docker buildx imagetools inspect nrchkb/node-red-homekit:latest-22
```
### Quick Start (for those already running Docker)
```bash
docker run -d --net=host -v :/data -e TZ=Europe/Amsterdam -e DEBUG=NRCHKB:* --name=node-red-homekit nrchkb/node-red-homekit
```
Let's dissect that command:
docker run - Run this container.
-d - Run container in background and print container ID.
--net=host - Connect to the host network, which is required to work with homekit.
-v :/data - Persist container data
-e TZ=Europe/Amsterdam - Set timezone, see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
-e DEBUG=NRCHKB:* - Print basic debug logs for NRCHKB
--name node-red-homekit - Give this machine a friendly local name.
nrchkb/node-red-homekit - The image to base it.
### Raspberry Pi (including installation Docker)
Following these commands will install Docker, add user `pi` to a Docker group, then set the docker container to always
run.
We assume you have some basic knowledge of Linux and you are logged in as `pi` user.
1) Make sure we are in the home directory of the pi user:
```bash
cd ~
```
2) Make sure we have the latest packages available and upgrade to the latest versions (reboot if needed!):
```bash
sudo apt update && sudo apt upgrade -y
```
3) Download the docker install script and execute it to install Docker on your system.
```bash
curl -fsSL https://get.docker.com -o get-docker.sh && sudo sh get-docker.sh
```
4) As the Docker script explains, add the pi user to the Docker group so that the pi user has the permissions to execute
docker commands:
```bash
sudo usermod -aG docker pi
```
5) Reboot the Raspberry PI or just log out and back in:
```bash
sudo reboot
```
6) To test if your Docker installation went well:
```bash
docker run --rm hello-world
```
The above command should say 'Hello from Docker':
```
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
0e03bdcc26d7: Pull complete
Digest: sha256:7f0a9f93b4aa3022c3a4c147a449bf11e0941a1fd0bf4a8e6c9408b2600777c5
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(amd64)
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/
For more examples and ideas, visit:
https://docs.docker.com/get-started/
```
If the above steps went as expected, you are ready to run the `nrchkb/node-red-homekit` image as a container. But before
that we create a directory on the pi host so that all node-red / node-red-homekit files are stored outside the container
on your raspberry pi.
7) Make a directory in your pi user's home directory:
```bash
mkdir node-red-homekit
```
8) Run the Docker run command to deploy the `nrchkb/node-red-homekit` image as a container and where the container
`/data` directory is bound to the `/home/pi/node-red-homekit` directory on your Raspberry PI.
```bash
docker run -d --net=host -v ~/node-red-homekit:/data --restart always -e TZ=Europe/Amsterdam -e DEBUG=NRCHKB:* --name node-red-homekit nrchkb/node-red-homekit
```
You don't need to explicitly map ports, since all ports are opened on the host network! This is required for homekit to
work well.
### Upgrade to the latest image
Suppose there is a new `nrchkb/node-red-homekit` image available? How do I make use of this new image?
1) Find the id of your current deployed container:
```bash
docker container ls
```
The above command lists all running containers, and in the first column it displays the id of the container and in the
last column its name.
2) Stop the current container:
```
docker stop
```
3) Remove the current container:
```
docker rm
```
4) Pull the latest `nrchkb/node-red-homekit` image from [Docker Hub](https://hub.docker.com/r/nrchkb/node-red-homekit):
```bash
docker pull nrchkb/node-red-homekit
```
5) Deploy the container again:
```bash
docker run -d --net=host -v ~/node-red-homekit:/data --restart always -e TZ=Europe/Amsterdam -e DEBUG=NRCHKB:* --name node-red-homekit nrchkb/node-red-homekit
```
This runs the container based on the latest `nrchkb/node-red-homekit` image and retains your flows!
### Docker Compose (including installation Docker Compose)
For demo purpose we use a Raspberry Pi with Docker installed (see)
1) Install required packages for Docker Compose
```bash
sudo apt update && sudo apt install -y libffi-dev libssl-dev python3 python3-pip
```
2) Install Docker Compose using pip3
```
sudo pip3 -v install docker-compose
```
3) Create a Docker compose yml for `nrchkb/node-red-homekit`:
Let's assume you have a directory `/home/pi/node-red-homekit` with a `data` subdirectory:
```bash
node-red-homekit/
`-- data
1 directory, 0 files
```
Use your favorite editor like nano to create a file named `docker-compose.yml` with the content below and save it in
`/home/pi/node-red-homekit`.
```yaml
version: '2'
services:
node-red-homekit:
image: nrchkb/node-red-homekit
restart: always
network_mode: host
environment:
- TZ=Europe/Amsterdam
- DEBUG=NRCHKB:*
volumes:
- /home/pi/node-red-homekit/data:/data
```
note 1: `/home/pi/node-red-homekit/data` is the persistence directory where the Docker container stores its files.
note 2: there is no port mapping defined, since the container is attached / uses the host network.
4) Deploy the service as define in `docker-compose.yml`
From the `/home/pi/node-red-homekit` directory executed the command below to deploy the service and therefore the
container:
```bash
docker-compose up -d
```
5) Verify your deployed container:
```bash
docker container ls
```
6) To update to the latest image:
The command below stops the current running container, removes it and removes the image.
```bash
docker-compose down --rmi all
```
Run the command in step 4 to redeploy the service. It pulls the (latest) image, since now is available locally.
### Synology
Synology users need to add the environment variable DSM_HOSTNAME.
Click the Environment tab and add a new environment variable named DSM_HOSTNAME. The value of the DSM_HOSTNAME
environment variable should exactly match the server name as shown under Synology DSM Control Panel → Info Center →
Server name, it should contain no spaces or special characters.
```bash
docker run -it --net=host -v :/data -e DSM_HOSTNAME= -e TZ=Europe/Amsterdam -e DEBUG=NRCHKB:* --name=homekit nrchkb/node-red-homekit:
```
### Permissions
Since Node-RED 1.0 the container user is `node-red` and has uid `1000` and gid `1000`, make sure your has
the same uid and gid:
Verify command:
```bash
ls -nal
```
Modify command:
```bash
chown -R 1000:1000
```
### Debug
To debug NRCHKB, you have to add environment variable to command running node-red in docker by adding `-e` argument:
```-e "DEBUG=NRCHKB*,HAP-NodeJS*"```
To do that, modify a starting script like below:
```bash
docker run -it -e "DEBUG=NRCHKB*,HAP-NodeJS*" --net=host -v :/data -e DSM_HOSTNAME= -e TZ=Europe/Amsterdam -e DEBUG=NRCHKB:* --name=homekit nrchkb/node-red-homekit:
```
### Node-RED Docker official
For more detailed info refer to the [Node-RED Docker official](https://github.com/node-red/node-red-docker) pages.
### NRCHKB Support
For more info visit our [Website](https://nrchkb.github.io) or [Discord](https://discord.gg/uvYac5u).