Docker

Introduction

You can also install Domoticz as a Docker container. Using a Docker container gives you ease in the configuration and requirements of your system. No dependencies on libraries, Python versions etc.

Also some frequently used hardware gateways like Zigbee2MQTT and Zwave-JS-UI (and their interface Mosquitto MQTT) can run in separate Docker containers.

Using Docker with Domoticz will require some general knowledge how to use and maintain Docker environments. See for example https://docs.docker.com/get-started/docker-concepts/running-containers/publishing-ports/

It is important to understand that docker containers work with volumes. Volumes are the folders/files that needs to be persistent. (Like the configuration)

Everything else is 'virtual'. Also understand that a docker is not a virtual machine, It does not emulate, meaning, the performance is as fast as running this natively!

Make sure you have already installed both Docker Engine and Docker Compose.

We highly recommend using 'docker-compose' as maintaining the configuration will be much easier

Install docker on a linux system

sudo apt-get update && sudo apt-get upgrade

sudo apt-get install -y make git

curl -fsSL test.docker.com -o get-docker.sh && sh get-docker.sh

sudo usermod -aG docker ${USER}

sudo systemctl enable docker

sudo reboot

Platforms

The official docker image of Domoticz supports the following platforms

• 32 and 64 Arm
• 64 bit Linux

This should cover most platforms.

Default installation

The Docker image can be found here:

https://hub.docker.com/r/domoticz/domoticz

IMPORTANT: This website also gives the detailed instructions how to install and update the docker image based on docker compose.

Below mentioned topics are only to explain specific topics.

docker image tags

It is possible to use stable (preferred!) and beta images: https://hub.docker.com/r/domoticz/domoticz/tags

with docker pull or in the image section of the docker-compose.yml:

domoticz/domoticz:beta (will pull latest beta version)

domoticz/domoticz:stable (will pull latest stable version)

domoticz/domoticz:2022.1 (will pull latest stable version 2022.1)

domoticz/domoticz:2022-beta.12345 (will pull beta with build number 12345)

tag latest or no tag will pull the latest uploaded image, so could be a beta or stable image.

Update the Domoticz Docker Container

See also https://hub.docker.com/r/domoticz/domoticz

Docker-Compose: Use the following command in a terminal session in the directory where the docker-compose.yml is located:

docker compose pull && docker compose up --force-recreate --build -d && docker image prune -f

Domoticz Docker settings and tips

See also the basic install instructions on https://hub.docker.com/r/domoticz/domoticz

Serial Port

If you need to access a USB dongle connected to your system, we need to identify this serial device.

We do this by issuing the following command

ls /dev/serial/by-id

You should see one or multiple serial devices, find out which one is your RF stick, for example it's: usb-0658_0200-if00-port0

You need to add this device to the docker container in the docker-compose.yml like

devices:

- "/dev/serial/by-id/usb-0658_0200-if00-port0:/dev/ttyUSB0"

or in the docker startup line with

--device="/dev/serial/by-id/usb-0658_0200-if00-port0:/dev/ttyUSB0"

Ports

If you use ssl and or Device Sharing make sure those ports (eg default 443 and 6144) are enabled in your docker config

Docker Compose:

ports:   
 - "8080:8080"
 - "8443:443"
 - "6144:6144"

or with docker run: docker run -d -p 8080:8080 -p 8443:443 -p 6144:6144

Note: First port value is outside port, second value is inside container port (as configured in Domoticz). So for example the Domoticz configured ssl port 443 is accessible outside the container through port 8443.

custom startup script for the container

The container supports running a custom bash script (customstart.sh in userdata) before the Domoticz process starts. This way, you can customize anything in the container that you need:

• install incremental apt packages (don't forget to apt update before you apt install)
• install incremental python modules for plugins (pip3 install or pip3 install -r requirements.txt)
• and so on

The container calls a script named customstart.sh in userdata, if that script exists. Please note that the script gets called on EVERY start of the container, not just at creation time. If you want the script to run only once, you need to build that in your script (e.g. test for a file you create in the script).

Example script

#!/bin/bash

if [ -f /opt/domoticz/FIRSTRUN ]; then
true
else
echo 'updating packages'
apt-get -qq update
echo 'installing mosquitto clients'
apt-get -y install mosquitto-clients
echo 'installing iputils-ping'
apt-get -y install iputils-ping
echo 'creating FIRSTRUN file so script can check on next run'
touch /opt/domoticz/FIRSTRUN
echo 'copying event script templates to external mapped storage
cp -r /opt/domoticz/scripts/templates  /opt/domoticz/userdata/scripts
cd /opt/domoticz || return
fi

Python Plugins

When launching the docker container for the first time, a plugin folder is created in the mounted /opt/domoticz/userdata folder (inside the container). From the host this could be for example ./home/<user>/domoticz-docker/config/plugins, depending on your docker-compose volume settings. You need to place your python plugin in this folder on the host.

The stable container runs Python 3.11.2. (current beta too)

When plugins need extra python modules you need to install those in the Docker container! Python is also setup with a venv so no need to do something special on installing the required python modules.

Use the following command to get into the docker container:

docker exec -it domoticz bash

Then go to the plugin folder and install the modules

cd /opt/domoticz/userdata/plugins/<yourpluginfolder>

sudo pip3 install -r requirements.txt

You can use the custom startup script (customstart.sh asmentioned above) to be sure the required python modules are reinstalled when you update the docker image.

Docker and dzVents

Make sure you have created the following script subfolders manually in your mounted /opt/domoticz/userdata folder if you get errors complaining about these folders:

• scripts/dzVents/generated_scripts (so from within container /opt/domoticz/userdata/scripts/dzVents/generated_scripts)
• scripts/dzVents/scripts

Latest beta 2023.1 should have these folders create at startup.

Dzvents templates:

When creating a new dzvents script the templates are empty. To repair that add the following line in the customstart.sh file or run the command after a new image deploy in the docker container:

cp -r /opt/domoticz/scripts/templates /opt/domoticz/userdata/scripts

Custom templates

If you use custom templates make sure you added a volume so the custom templates are added and not overwritten at a Domoticz update. For example add ./config/www/templates:

 volumes: 
    - ./config:/opt/domoticz/userdata
    - ./config/www/templates:/opt/domoticz/www/templates

Custom Themes

To use custom themes mount the custom style subfolder. For example for the machinon template mount ./config/www/styles/machinon:/opt/domoticz/www/styles/machinon

 volumes: 
    - ./config:/opt/domoticz/userdata
    - ./config/www/styles/machinon:/opt/domoticz/www/styles/machinon

IP settings in Hardware gateways

If you have to enter an URL in one of the hardware gateways setting (menu Setup - Hardware) with values like localhost or 127.0.0.1 change these into the real IP of your Domoticz server (eg 192.168.1.32).

The redirect IP's like localhost and 127.0.0.1 are directing to the IP's in the container and so not connecting to the IP of the host. The Domoticz Hardware gateways would then not find the expected services running on the server.

Dockge

If you have more docker containers next to Domotcz you can use the application Dockge, a fancy, easy-to-use and reactive self-hosted docker compose.yaml stack-oriented manager. See for more information https://github.com/louislam/dockge

Debugging

Switch on Domoticz logging to OS

Switch on logging to an OS file with Docker environment parameter LOG_PATH=/opt/domoticz/userdata/domoticz.log

With the Docker environment parameter EXTRA_CMD_ARG (see the page https://hub.docker.com/r/domoticz/domoticz) you can set additional command line parameters (see also page Command Line Parameters) for extra debugging. For example:

EXTRA_CMD_ARG= -loglevel normal,status,error,debug -debuglevel normal,hardware,received,webserver,eventsystem,python,thread_id

Shell access while the container is running

To get into the docker container to check config files or install extra software use command

docker exec -it domoticz bash

Monitor the logs of the container

docker logs -f domoticz

Questions:

If you have questions about this new official Docker container, please go to the following forum topic: https://www.domoticz.com/forum/viewtopic.php?f=4&t=35454

In case you want to install a Domoticz Docker container on a Synology, please read Domoticz on a Synology NAS.