Installing Z-Wave JS with Docker and Home Assistant

To install Z-Wave JS with Docker Compose you'll need to actually use the zwavejs2mqtt application. You can find the official instructions on the Z-Wave JS documentation page, but I'll briefly describe below what I did to get it running in my smart home.

Firstly, you'll need to add an entry to your docker-compose.yaml file to spin up the zwavejs2mqtt application. Here is the one I use in my smart home.

 zwavejs2mqtt:
    container_name: zwavejs2mqtt
    image: zwavejs/zwavejs2mqtt:latest
    restart: always
    tty: true
    stop_signal: SIGINT
    environment:
      - SESSION_SECRET=<mysupersecretkey>
      - ZWAVEJS_EXTERNAL_CONFIG=/usr/src/app/store/.config-db
      # Uncomment if you want log times and dates to match your timezone instead of UTC
      # Available at https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      #- TZ=America/New_York
    devices:
      # Do not use /dev/ttyUSBX serial devices, as those mappings can change over time.
      # Instead, use the /dev/serial/by-id/X serial device for your Z-Wave stick.
      - '/dev/serial/by-id/<REPLACE WITH YOUR STICK REFERENCE>:/dev/zwave'
    volumes:
      - /opt/z-wave-js/:/usr/src/app/store
    ports:
      - "8091:8091" # port for web interface
      - "3000:3000" # port for Z-Wave JS websocket server

You will need to replace the SESSION_SECRET value with a string or set of random characters yourself, and you will also need to find the reference of your Z-Wave USB Dongle and add it into the devices key.

To find your Z-Wave USB stick reference, you will need to SSH into your Docker host and run the following command.

ls -l /dev/serial/by-id

This will output all the USB devices that are connected to your Host. In the screenshot below you can see both my Zigbee and Z-Wave dongles. I have highlighted the Z-Wave reference.

Copy the reference and paste it into the marked area in the Devices key in the Docker Compose sample. This means the line that is currently:

ls -l /dev/serial/by-id

Should now look more like this: (But with your own reference in place of mine)

/dev/serial/by-id/<REPLACE WITH YOUR STICK REFERENCE>:/dev/zwave'

The Docker Compose example I have shown above will also store all the Z-Wave JS configuration in the /opt/z-wave-js/ directory on your host machine. Feel free to change this if you want to store those data elsewhere.

Once you've got this added, you can create the container by running the docker-compose up -d command from the directory that your docker-compose.yaml file is stored in.

Use Portainer or similar to check that the container is running correctly.

You will now need to set up zwavejs2mqtt to let Home Assistant talk to it via a web socket. You can do this via the zwavejs2mqtt web UI that is usually running on port 8091. Navigate to the IP address of the Docker host and port 8091. Then click the Settings cog on the left hand menu and navigate down to the Home Assistant section.

Make sure that you turn on the WS Server toggle and save the changes.

You should now be able to install the Z-Wave Home Assistant integration.

To do this go to the Integrations section of Home Assistant and click Add New Integration. Search for the Z-Wave JS integration and click to add it.

When prompted, leave the defaults as they are to let Home Assistant talk to the Z-Wave JS server over the Web Socket

Now you should have Z-Wave JS running on Home Assitant and you can begin pairing devices!

To see the full end to end process, check out the YouTube video I made about this here.