HOWTO: Beginner's Guide to Installing openHAB, Mosquitto, etc. with Docker on Debian/Ubuntu + Tips on backup and more

miwok · April 26, 2025, 5:17pm

yes, it is a zipfile. and yes, that is the solution. I just copied the two folders into the coreponding folders, thanks a lot!

francoislavoie · April 28, 2025, 12:09pm

Done.

I am reading on yaml, docker, the openhab ui.

And I am trying to install a tuya mqtt binding thru openhab ui. I have a few tuya devices the alarm siren and a geya intelligent breaker good up to 20 amps or so.

I understand that working thru command line with docker and openhab is different than thru the openhab ui. Can I consider those as 2 different installations of openhab? How will they interact?

jimtng · April 28, 2025, 12:34pm

I have a guess at what you meant but could you please elaborate further on what you mean?

francoislavoie · April 28, 2025, 1:34pm

Good question, you are forcing me to integrate the information. The learning curve …

The answer is that the openhab Main ui is available because openhab has been runned by docker. Thus we have only one instalation of openhab running. The main ui can provide additionnal settings.

Another question is: If I run the mosquitto (mqtt broker) with docker, where can I see it in the Main ui of openhab?

Additional notes (mainly for my understanding).
I understand that I have installed openhab running from docker instead of working from an openhab instance running directly into kubuntu linux.

This means that thru docker I could install openhab in any other linux distribution, if I get to run docker in that linux distribution.

Docker is a very fast and flexible virtualization sofware that simplifies testing of softwares by the use of containers. From docker I have called and run openhab, but I could also call many other softwares: ubuntu, busybox, etc.

Command line: running docker or other applications.
Docker container or mages can be found with:
docker images
Thru openhab docker we are working together command line. Working with openhab for example:
run container
docker run -it openhab
(if I want to interact with openhab, and without -it just to run it)
stop container
docker compose stop openhab
start container
docker restart openhab

With docker we have installed the eclipse mosquito broker and the koenkk/zigbee2mqtt bridge. These seem to operate into their own containers.

Command line Main UI : http://xx.x.x.xx.local:8080/settings/

and http://xx.x.x.xx comes from

rlkoshak · April 28, 2025, 2:04pm

You don’t/ Mosquitto is a wholly separate program running (in this case) running in a wholly separate Docker container.

Mosquitto is represented in OH as an MQTT Broker Thing (see the other thread I’m helping you on for more details).

It’s more complicated than that, but this is a reasonable working model for now. Just realize this is like saying “electrons orbit around the nucleus of an atom”. It’s not strictly correct but it is still a useful way to present it.

Or Windows or Mac. I think there are limitations with device passthrough on Windows though.

Though you can already run OH on any Linux distrubution that supports running the needed version of Java. If running a distro that uses apt, yum or dnf you’d usually use those tools to install. Other systems have unofficial support for those package managers and of course you can always manually unzip it to a folder and run it that way.

Not really. Containers are not virtualization. And especially with Docker, a container is intended to be “just enough to run this one service”. You almost never have a window manager, for example.

And this is getting closer to “electron cloud” explanation of containers. What make a container different from a VM is that it shares the kernel with the host operating system. A VM is like building a house inside of another house. A container is like building a locked room inside of a house. It provides isolation but it does not provide a whole virtual machine.

The kinds of “other softwares” you’d run in a container are things like Mosquitto, Zigbee2mqtt, InfluxDB, etc. These are software you could run on Ubuntu (for example) but have created a separate little padded room in the Ubuntu house to run it. That way, it doesn’t interfear with any of the other software running in the Ubuntu house except in ways you explicitely allow (e.g. ports).

Above where I said “just enough to run this one service”, that’s the image. It contains just enough of the parts of the operating system that the software needs to run and usually nothing more. That’s the image. The image is like a boot disk. It has all the files but that’s it.

A container is one instance of a running image. You can have more than one.

Running with -it is like entering the same room that the service is in (to continue the house metaphore/simili). Running without -it means you can only interact with the running service through the windows you’ve explicitely opened into the room (e.g. connecting to a port with a browser, editing files mounted into the container as a volume, etc.).

Given the configuration in the OP, network_mode: host is being used which means we’ve given the openHAB container full access to the host’s network. That means the IP address of the host machine OH is running on is used by other containers on the same machine, and other computers on your LAN, to access the openHAB web ui.

jimtng · April 28, 2025, 2:04pm

You can configure everything to do with openhab using configuration files. You just need to know where the files are and what syntax to use. Most people find it easier to configure it using the UI but it’s not the only way.

Technically mosquitto is a completely different application. Like MS Word vs Adobe Photoshop. Furthermore, I am not aware of any GUI for mosquitto (doesn’t mean it doesn’t exist, just that in my years of using mosquitto, I have never known about it nor needed to use it. It is just configured using the simple mosquitto.conf).

Zigbee2mqtt on the other hand, does have a UI - export on port 8088 in the above compose file. You can add a link in openhab to open any external url you wish, including zigbee2mqtt.

You do it by adding the following in openhab/conf/services/runtime.cfg

Example:

org.openhab.core.ui.tiles:zigbee-link-name=Zigbee2MQTT
org.openhab.core.ui.tiles:zigbee-link-url=http://your.ubuntu.io:8088/
org.openhab.core.ui.tiles:zigbee-link-imageurl=https://www.zigbee2mqtt.io/logo.png

org.openhab.core.ui.tiles:frigate-link-name=Frigate
org.openhab.core.ui.tiles:frigate-link-url=http://x.x.x.x:5500
org.openhab.core.ui.tiles:frigate-link-imageurl=/static/frigate.png

You can add as many links as you wish.

You can see these links on your main openhab UI web page on the top right hand corner, see:

100% correct! And it’s installed the exact same way. Each docker container is a self contained “mini distribution” that shares the kernel. It even exists on Windows and MacOS

francoislavoie · April 29, 2025, 5:03pm

I have received my ZigBee 3.0 usb dongle plus.

How to configure the dongle:

I will do that.

Thanks.

francoislavoie · April 29, 2025, 6:31pm

Zigbee2MQTT seems to be up.

fl@Satellite-Z930:~$ docker compose exec mosquitto mosquitto_sub -v -C 1 -t '$SYS/broker/clients/total'
$SYS/broker/clients/total 1
fl@Satellite-Z930:~$ docker compose exec mosquitto mosquitto_sub -v -t 'zigbee2mqtt/#'

However, nothing appears following the last command line
docker compose exec mosquitto mosquitto_sub -v -t 'zigbee2mqtt
I will have to do ctrl-c to resume the command line prompt.

Actually there is only one movement sensor online, I have a few more and some door contacts. Where do I see the actual movement sensor?

jimtng · April 29, 2025, 11:29pm

First, ensure that zigbee2mqtt works with your dongle.
Next, ensure that your sensor is paired with zigbee2mqtt,

You can access zigbee2mqtt web interface to see more.

Check zigbee2mqtt’s docs / forums for more info, there should be plenty of details there.

francoislavoie · April 30, 2025, 1:55pm

My Sonoff Dongle Plus “ZBDongle-P” (based on CC2652P) is reccomended and approved

It is recognised on my system:

fl@Satellite-Z930:~$ ls -l /dev/serial/by-id
total 0
lrwxrwxrwx 1 root root 13 Apr 30 06:00 usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0

With the the adapter identification I have modified the configuration file that you help me set for Zigbee2mqqt which I found in my /home/fl/zigbee2mqtt/configuration.yaml
Modified section for my adapter:

serial:
    # Location of the adapter
    # USB adapters - use format "port: /dev/serial/by-id/XXX"
    # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
    port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0

I should see something in the port 8081, but I do not.

fl@Satellite-Z930:~$ sudo lsof -n -i :8081 | grep LISTEN
[sudo] password for fl: 
fl@Satellite-Z930:~$ sudo lsof -n -i :8080 | grep LISTEN
java    2014   fl  152u  IPv6  12166      0t0  TCP *:http-alt (LISTEN)
fl@Satellite-Z930:~$

However, I see that configuration file points to the port 8080, while it should points to the port 8081.
/home/fl/zigbee2mqtt/configuration.yaml

frontend:
  enabled: false
  port: 8080

Zigbee2MQTT states that I should be able to set my adapter with port 8081

Should I change something in the /home/fl/zigbee2mqtt/configuration.yaml
???

francoislavoie · May 1, 2025, 10:37am

*********in progress
To be used or garbage

Other related stuff:
(https://github.com/Koenkk/zigbee2mqtt.io/raw/master/docs/guide/adapters/flashing/zigbee-3.0-usb-dongle-plus-firmware_flashing-1-1.pdf) and required python script)

https://github.com/Koenkk/Z-Stack-firmware/releases/download/Z-Stack_3.x.0_coordinator_20240710/CC1352P2_CC2652P_launchpad_coordinator_20240710.zip

ZigBee2mqtt on openhabian

configuration page is available on port 8081

For some of my sensors

francoislavoie · May 1, 2025, 11:31am

jimtng:
Please see the second post above.

Thanks.

jimtng · May 1, 2025, 11:51am

Your zigbee2mqttt configuration is not correct, but first show your compose.yml file

francoislavoie · May 2, 2025, 11:52am

services:
openhab:
image: openhab/openhab:latest
# image: openhab/openhab:milestone
# image: openhab/openhab:snapshot
container_name: openhab
restart: always
network_mode: host
volumes:
- /etc/localtime:/etc/localtime:ro
- /etc/timezone:/etc/timezone:ro
- ./.ssh:/openhab/.ssh
- ./openhab/.karaf:/openhab/.karaf
- ./openhab/conf:/openhab/conf
- ./openhab/userdata:/openhab/userdata
- ./openhab/addons:/openhab/addons
environment:
USER_ID: 1000
GROUP_ID: 1000
# Adjust accordingly
OPENHAB_HTTP_PORT: 8080
OPENHAB_HTTPS_PORT: 8443
JAVA_MIN_MEM: 4g
JAVA_MAX_MEM: 4g

mosquitto:
image: eclipse-mosquitto:latest
container_name: mosquitto
restart: always
volumes:
- ./mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf
user: “1000:1000”
ports:
# These ports should not be changed unless absolutely necessary
- “1883:1883”
- “8883:8883”

zigbee2mqtt:
image: koenkk/zigbee2mqtt:latest
container_name: zigbee2mqtt
restart: always
# Make it run as the openhab user too
user: “1000:1000”
volumes:
- /etc/localtime:/etc/localtime:ro
- /etc/timezone:/etc/timezone:ro
- ./zigbee2mqtt:/app/data
ports:
# Adjust accordingly
- “8088:8080”
# Uncomment the devices section below and map the correct device
#devices:
#- /dev/serial/by-id/usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0001-if00-port0:/dev/ttyUSB0
depends_on:
- mosquitto

jimtng · May 2, 2025, 10:34pm

You should enclose code text like this with triple backticks: ```
You need to uncomment the devices: and then add a mapping:

    devices:
      - /dev/your/real/device/name:/dev/ttyUSB0

zigbee2mqtt inside docker, will see your real device as /dev/ttyUSB0 and then in zigbee2mqtt config, you’ll use /dev/ttyUSB0 - not your real device name.

Don’t forget to run docker compose up -d zigbee2mqtt after you’ve modified the compose.yml for it.

You’ll also need to restart zigbee2mqtt after modifying the port name in zigbee2mqtt config

francoislavoie · May 3, 2025, 12:33pm

I have followed the protocol
https://www.zigbee2mqtt.io/guide/configuration/adapter-settings.html#basic-configuration
Given the example of the USB adapter above in combination with a zstack adapter, we would add the following to the configuration.yaml:

serial:
    # Location of the adapter
    # USB adapters - use format "port: /dev/serial/by-id/XXX"
    # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
    port: /dev/serial/by-id/usb-Texas_Instruments_TI_CC2531_USB_CDC___0X00124B0018ED3DDF-if00
    # Adapter type, allowed values: `zstack`, `ember`, `deconz`, `zigate` or `zboss`
    adapter: zstack

which gave for my configuration.yaml:

serial:
    # Location of the adapter
    # USB adapters - use format "port: /dev/serial/by-id/XXX"
    # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
    port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0
# attacher a ligne precedente additonnal info fl -port0 -> ../../ttyUSB0
    # Adapter type, allowed values: `zstack`, `ember`, `deconz`, `zigate` or `zboss`
    adapter: zstack

jimtng · May 3, 2025, 12:46pm

francoislavoie:

which gave for my configuration.yaml:

serial:
    # Location of the adapter
    # USB adapters - use format "port: /dev/serial/by-id/XXX"
    # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
    port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0
# attacher a ligne precedente additonnal info fl -port0 -> ../../ttyUSB0
    # Adapter type, allowed values: `zstack`, `ember`, `deconz`, `zigate` or `zboss`
    adapter: zstack

Please read what I wrote above which says you should change your docker compose.yml first, and then change your zigbee2mqtt configuration.yaml to

serial:
  port: /dev/ttyUSB0

francoislavoie · May 3, 2025, 12:53pm

Sorry, I am slow, it took me time to implement your instructions. I just wanted that you knew what I did.

Following your instructions:
my new configuration.yaml:

serial:
    # Location of the adapter
    # USB adapters - use format "port: /dev/serial/by-id/XXX"
    # Ethernet adapters - use format "port: tcp://192.168.1.12:6638"
    #port: /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0
     port: /dev/ttyUSB0
# attacher a ligne precedente additonnal info fl -port0 -> ../../ttyUSB0
    # Adapter type, allowed values: `zstack`, `ember`, `deconz`, `zigate` or `zboss`
    adapter: zstack

Following your instructions:
my new compose.yaml

    devices:
    # - /dev/serial/by-id/usb-Silicon_Labs_Sonoff_Zigbee_3.0_USB_Dongle_Plus_0001-if00-port0:/dev/ttyUSB0
      - /dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 -> ../../ttyUSB0
    depends_on:
      - mosquitto

francoislavoie · May 3, 2025, 12:55pm

fl@Satellite-Z930:~/tuya-mqtt$ docker compose up -d zigbee2mqtt
[+] Running 1/2
Container mosquitto Running 0.0s
⠙ Container zigbee2mqtt Starting 0.2s
Error response from daemon: error gathering device information while adding custom device “/dev/serial/by-id/usb-Itead_Sonoff_Zigbee_3.0_USB_Dongle_Plus_V2_a88893f4dc73ef11abf0df1e313510fd-if00-port0 → …/…/ttyUSB0”: no such file or directory
fl@Satellite-Z930:~/tuya-mqtt$

francoislavoie · May 3, 2025, 12:56pm

removing → …/…/ttyUSB0 in compose.yml:

fl@Satellite-Z930:~/tuya-mqtt$ docker compose up -d zigbee2mqtt
[+] Running 2/2
 ✔ Container mosquitto    Running                                                                                                                         0.0s 
 ✔ Container zigbee2mqtt  Started                                                                                                                         0.3s 
fl@Satellite-Z930:~/tuya-mqtt$

Can we say it worked?