Getting zwave-js running in docker

zwave-js_docker.md

Update: Just run ZwaveJS2Mqtt

Shortly after writing this, I realized that ZwaveJS2Mqtt can be used with a websocket connection instead of the mqtt. I've had a great experience with it, so there's really no good reason to use what is below.

Documentation: https://zwave-js.github.io/zwavejs2mqtt/#/

I'll leave the text below, because somebody might find it useful.

Getting zwave-js running in docker

Until a better solution comes around, this is how I got zwave-js running in docker for use in home assistant. The timing was just right for me to create a new network, as my first z-wave devices only arrive a few days before the Home Assitant annoucement.

I choose to run my containers with named local volumes, host networking, and automatic watchtower updates. Therefore, take this into account when following these instructions.

Generate a Key

Launch python

import random

bit_choices = ["0x{:02d}".format(x) for x in range(0,16)]
key = ", ".join([random.choice(bit_choices) for x in range(0,16)])
print(key)

save this key to a safe location. Set it as a variable for now

NETWORK_KEY="<script_output_here>"

Build the image

mkdir $HOME/zwavejs-image
cd $HOME/zwavejs-image
git clone https://github.com/kpine/dockerfiles.git
cd dockerfiles/zwave-js-server
docker build -t zwavejs .

Create volumes

docker volume create zwavejs-cache
docker volume create zwavejs-logs

Run the image

Note that network mode is set to host. You may want to add this container to a network or publish a port if this doesn't work for you. by default, zwave-js runs on port 3000

Note that I'm mounting my zwave stick to /dev/zwave. This is the default path set in zwave-js code, but it can be configured otherwise.

docker run --name=zwavejs \
--device=/dev/serial/by-id/usb-Silicon_Labs_HubZ_Smart_Home_Controller_81300326-if00-port0:/dev/zwave \
--network=host \
-e NETWORK_KEY=${NETWORK_KEY} \
-l com.centurylinklabs.watchtower.enable=false \
-v zwavejs-cache:/cache \
-v zwavejs-logs:/logs \
--restart=unless-stopped -d \
zwavejs

If you're doing this in docker compose:

version: "3"

services:
  zwave:
    build:
      context: ./dockerfiles/zwave-js-server
      dockerfile: Dockerfile
    ports:
      - "3000:3000/udp"
      - "3000:3000/tcp"
    environment:
      NETWORK_KEY:  "<KEY>"
    devices:
      - "/dev/serial/by-id/usb-0658_0200-if00:/dev/zwave"
    volumes:
      - ./cache:/cache
      - ./logs:/logs
    restart: unless-stopped

great guide!

I'm pretty sure the posted python generates a key of poor entropy. Each byte of the 16 will have a 0 for the high nibble.

I used the following to make one using python3:
python -c "import os;print(os.urandom(16).hex())"

Also for reference I added the following service to my homeassistant docker-compose.yml:
I didn't bother building anything, just pointing to kpine's docker was enough for the tool to pull and load automagically.

  zwave:
    container_name: zwavejs
    image: kpine/zwave-js-server:latest
    ports:
      - "3001:3000/udp"
      - "3001:3000/tcp"
    logging:
      driver: "none"
    volumes:
      - <wherever>/zwavejs/cache:/cache
      - <wherever>/zwavejs/logs:/logs
      - "/etc/localtime:/etc/localtime:ro"
    environment:
      - S0_LEGACY_KEY=<above generated key>
    devices:
      - "/dev/ttyUSB0:/dev/zwave"
    restart: unless-stopped

I had to move the exposed port to 3001 as the default conflicted with another service I had running.